@tencentcloud/sdk-mcp 1.3.8 → 1.4.0

package/resource/doc/chatkit/android/integration.md

@@ -0,0 +1,498 @@
+TUIKit Compose 是基于腾讯云 IM SDK 的一套 Jetpack Compose 组件库，提供了聊天、会话列表、联系人管理等即时通信功能的完整解决方案。本文介绍如何手动集成该组件并实现核心功能。
+
+## 关键概念
+
+TUIKit Compose 提供了一套完整的即时通信 UI 组件，向下依赖 AtomicXCore 数据层，向上可构建各种功能性 Page。
+- Page 层：基于 TUIKit Compose 组件封装的完整功能页面：ChatPage、ContactsPage、ConversationsPage，您可以直接使用。
+
+- TUIKit Compose（UI 组件层）：基于 AtomicXCore 构建的 Jetpack Compose 组件，您可将其嵌套到自己已有的 App 页面中。
+
+- AtomicXCore（数据层）：提供数据管理和业务逻辑，包含各种 Store 和 Manager。
+
+## 前提条件
+- Android Studio Ladybug | 2024.2.1 及以上版本
+
+- Android 5.0 及以上系统版本
+
+- Gradle 8.9 及以上版本
+
+- Android Gradle Plugin 8.6 及以上版本
+
+- JDK 17 及以上版本
+
+- Kotlin 1.9.0 及以上版本
+
+- 一个有效的腾讯云账号及 Chat 应用。可参考 开通服务 从控制台获取以下信息：
+
+  - SDKAppID：App 在控制台获取的 Chat 应用的 ID，为应用的唯一标识
+
+  - SDKSecretKey：应用的密钥
+
+      > **说明：**
+      >
+>     - 本项目目前仅支持手动集成，暂不支持通过 Maven 等包管理器集成。
+>     - 为确保构建环境稳定，请严格遵循官方兼容性要求进行配置：
+>     - Gradle、Android Gradle Plugin、JDK 与 Android Studio 的兼容性，请参阅 Android 官方文档：[版本说明](https://developer.android.com/build/releases/gradle-plugin#updating-gradle)。
+>     - Kotlin、Android Gradle Plugin 与 Gradle 的版本对应关系，请参阅 Kotlin 官方文档：[Kotlin-Gradle 插件兼容性](https://kotlinlang.org/docs/gradle-configure-project.html#apply-the-plugin)。
+
+      > 我们建议您根据上述指南，选择与项目要求完全匹配的版本组合。
+      >
+
+## 集成并引入组件
+
+### 下载源码
+1. 从 GitHub 下载 [TUIKit Compose](https://github.com/Tencent-RTC/TUIKit_android_compose) 源码：
+
+   ``` bash
+   git clone https://github.com/Tencent-RTC/TUIKit_Android_Compose.git
+   ```
+
+   项目目录结构说明：
+
+   ``` bash
+   atomic-x/
+   ├── src/main/
+   │   ├── java/io/trtc/tuikit/atomicx/     # UI 组件源码（必需集成）
+   │       ├── messagelist/      # 消息列表组件
+   │       ├── messageinput/     # 消息输入组件
+   │       ├── conversationlist/ # 会话列表组件
+   │       ├── contactlist/      # 联系人列表组件
+   │       ├── basecomponent/    # 基础组件
+   │       └── ...               # 其他 UI 组件
+   │   # 资源文件（必需集成）
+   │   ├── res/                    # 公共资源
+   │   ├── res-message-list/       # 消息列表组件资源
+   │   ├── res-message-input/      # 消息输入组件资源
+   │   ├── res-conversation-list/  # 会话列表组件资源
+   │   └── ...                     # 其他组件资源
+   chat/
+   ├── uikit/src/main/java/io/trtc/tuikit/chat/pages    # Page 组件（参考实现）
+   │   ├── ChatPage.kt
+   │   ├── ContactsPage.kt
+   │   └── ConversationsPage.kt
+   └── demo/                 # 示例应用（可选参考）
+   ```
+
+### 集成组件
+1. 将组件目录完整复制到您的 Android 项目中，如下图所示，其中 ComposeDemo 是示例项目，TUIKit_Android_Compose 是从 GitHub 上下载的组件源码：
+
+2. 在您的 settings.gradle.kts/settings.gradle 文件中添加 TUIKit Compose 组件：
+
+   > **说明：**
+   >
+
+   > TUIKit_Android_Compose 可以放在任何位置，只要在 settings.gradle 中正确设置相对路径即可。
+   >
+
+【Kotlin DSL (推荐)】
+``` java
+// settings.gradle.kts
+include(":atomicx")
+project(":atomicx").projectDir = file("../TUIKit_Android_Compose/atomic-x")
+```
+
+【Groovy DSL】
+``` java
+// settings.gradle
+include ':atomicx'
+project(':atomicx').projectDir = new File(settingsDir, '../TUIKit_Android_Compose/atomic-x')
+```
+
+3. 在 app 模块的 build.gradle.kts/build.gradle 中添加下列依赖：
+
+【Kotlin DSL (推荐)】
+``` java
+// app/build.gradle.kts
+dependencies {
+    implementation(project(":atomicx"))
+}
+```
+
+【Groovy DSL】
+``` java
+// app/build.gradle
+dependencies {
+    api project(':atomicx')
+}
+```
+
+   > **注意：**
+   >
+>   - 使用本地集成方案时，如需升级时需要从 GitHub 获取最新的组件代码，覆盖您本地项目的 TUIKit Compose 目录。
+>   - 当私有化修改和远端有冲突时，需要手动合并，处理冲突。
+
+### 配置项目
+1. 在 app 目录下找到 AndroidManifest.xml 文件，在 `application` 节点中添加 `tools:replace="android:allowBackup"`，覆盖组件内的设置，使用自己的设置。
+
+   ``` java
+     // app/src/main/AndroidManifest.xml
+     <application
+       android:name=".BaseApplication"
+       android:allowBackup="false"
+       android:icon="@drawable/app_ic_launcher"
+       android:label="@string/app_name"
+       android:largeHeap="true"
+       android:theme="@style/AppTheme"
+       tools:replace="android:allowBackup">
+   ```
+2. 配置依赖项。
+
+   在您的项目工程的 gradle/libs.versions.toml 文件中添加如下依赖项：
+
+   ``` python
+   # gradle/libs.versions.toml
+   [versions]
+   agp = "8.13.0"
+   kotlin = "2.0.21"
+   coreKtx = "1.10.1"
+   junit = "4.13.2"
+   junitVersion = "1.1.5"
+   espressoCore = "3.5.1"
+   appcompat = "1.7.1"
+   material = "1.13.0"
+   runner = "1.0.2"
+   espressoCoreVersion = "3.0.2"
+   appcompatV7 = "28.0.0"
+
+   tuicore = "8.6.7021"
+   lifecycleRuntimeKtx = "2.8.7"
+   ui = "1.8.0"
+   foundation = "1.8.0"
+   composeBom = "2024.09.00"
+   activityCompose = "1.10.1"
+   activity = "1.8.0"
+   constraintlayout = "2.2.1"
+
+   [libraries]
+   androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "coreKtx" }
+   junit = { group = "junit", name = "junit", version.ref = "junit" }
+   androidx-junit = { group = "androidx.test.ext", name = "junit", version.ref = "junitVersion" }
+   androidx-espresso-core = { group = "androidx.test.espresso", name = "espresso-core", version.ref = "espressoCore" }
+   androidx-appcompat = { group = "androidx.appcompat", name = "appcompat", version.ref = "appcompat" }
+   material = { group = "com.google.android.material", name = "material", version.ref = "material" }
+   runner = { group = "com.android.support.test", name = "runner", version.ref = "runner" }
+   espresso-core = { group = "com.android.support.test.espresso", name = "espresso-core", version.ref = "espressoCoreVersion" }
+   appcompat-v7 = { group = "com.android.support", name = "appcompat-v7", version.ref = "appcompatV7" }
+
+   androidx-lifecycle-viewmodel-compose = { module = "androidx.lifecycle:lifecycle-viewmodel-compose", version.ref = "lifecycleRuntimeKtx" }
+   androidx-compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "composeBom" }
+   androidx-compose-foundation = { group = "androidx.compose.foundation", name = "foundation", version.ref = "foundation" }
+   androidx-compose-ui = { group = "androidx.compose.ui", name = "ui", version.ref = "ui" }
+   androidx-compose-ui-graphics = { group = "androidx.compose.ui", name = "ui-graphics" }
+   androidx-ui-tooling = { group = "androidx.compose.ui", name = "ui-tooling" }
+   androidx-compose-material3 = { group = "androidx.compose.material3", name = "material3" }
+   androidx-activity-compose = { group = "androidx.activity", name = "activity-compose", version.ref = "activityCompose" }
+   androidx-lifecycle-runtime-ktx = { group = "androidx.lifecycle", name = "lifecycle-runtime-ktx", version.ref = "lifecycleRuntimeKtx" }
+   androidx-ui-tooling-preview = { group = "androidx.compose.ui", name = "ui-tooling-preview" }
+   androidx-ui-test-manifest = { group = "androidx.compose.ui", name = "ui-test-manifest" }
+   tuicore = { module = "com.tencent.liteav.tuikit:tuicore", version.ref = "tuicore" }
+   com-tencent-mmkv = { group = "com.tencent", name = "mmkv", version = "1.3.14" }
+
+   [plugins]
+   android-application = { id = "com.android.application", version.ref = "agp" }
+   kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
+   android-library = { id = "com.android.library", version.ref = "agp" }
+
+   kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
+   ```
+3. 开启 Compose 支持。
+
+   在 app 模块的 build.gradle.kts/build.gradle 中添加下列配置：
+
+【Kotlin DSL (推荐)】
+``` java
+// app/build.gradle.kts
+plugins {
+    // 添加 Compose 插件
+    alias(libs.plugins.kotlin.compose)
+}
+android {
+    // 开启 Compose
+    buildFeatures {
+        compose = true
+    }
+}
+```
+
+【Groovy DSL】
+``` java
+// app/build.gradle
+plugins {
+    // 添加 Compose 插件
+    id libs.plugins.kotlin.compose.get().pluginId
+}
+android {
+    // 开启 Compose
+    buildFeatures {
+        compose true
+    }
+}
+```
+
+4. 配置混淆规则。
+
+   在您的 app/proguard-rules.pro 文件中添加以下混淆规则：
+
+   ``` java
+   -keep class com.tencent.** { *; }
+   ```
+5. Android Studio 中点击 **File > Sync Project with Gradle Files** 集成组件。
+
+## 接入步骤
+
+### 步骤1：配置用户鉴权
+
+在 [即时通信 IM 控制台](https://console.cloud.tencent.com/im/tool-usersig) 根据 UserID 获取 UserSig 用于后续登录时的用户鉴权。
+
+### 步骤2：用户登录
+
+登录鉴权后才能正常使用组件的功能。您可以调用 login 接口，传入上文获取的 SDKAPPID、userSig 用于登录鉴权:
+``` swift
+// 用户登录
+LoginStore.shared.login(context, SDKAPPID, userID, userSig,
+    object : CompletionHandler {
+        override fun onSuccess() {
+              // 登录成功，可跳转聊天或会话页
+        }
+        override fun onFailure(code: Int, desc: String) {
+              // 登录失败，可弹框报错
+        }
+    })
+```
+
+> **注意：**
+>
+
+> 在正式的生产环境中，建议在您的服务端生成 UserSig，在需要 UserSig 时由您的 App 向业务服务器发起请求获取动态 UserSig 来进行鉴权。详见 [服务端生成 UserSig](https://cloud.tencent.com/document/product/269/32688)。
+>
+
+### 步骤3： 构建会话列表界面
+
+您可以基于 TUIKit Compose 中的 ConversationList 组件，构建一个会话列表页面。ConversationList 内建的功能是：
+- 展示用户的会话列表，包含单聊和群聊会话
+
+- 支持用户操作单个会话：置顶、删除、清空会话消息等
+
+   您可以将 ConversationList 直接集成到现有的 App 页面中，也可以新构建一个完整的会话列表页，组装后的一种 UI 效果如下图所示：
+
+   将 ConversationList 封装为会话列表页，可参考 `chat/uikit/src/main/java/io/trtc/tuikit/chat/pages/ConversationsPage.kt` 文件里的实现，`ConversationsPage` 主要做了以下工作：
+
+1. 在 ConversationList 上方添加了 headerView。
+
+2. 传递点击会话列表 cell 事件。
+
+   核心示例代码如下所示：
+
+   ``` swift
+   @Composable
+   fun ConversationsPage(
+       onConversationClick: (ConversationInfo) -> Unit = {},
+       editContent: @Composable () -> Unit = {},
+   ) {
+       val colors = LocalTheme.current.colors
+       Column(
+           modifier = Modifier
+               .fillMaxSize()
+               .background(Colors.Transparent)
+       ) {
+
+           PageHeader(stringResource(R.string.chat_uikit_chat)) {
+               editContent()
+           }
+
+           Box(modifier = Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
+               ConversationList(modifier = Modifier.navigationBarsPadding(), onConversationClick = onConversationClick)
+           }
+       }
+   }
+   ```
+
+### 步骤4：构建聊天界面
+
+您可以基于 TUIKit Compose 中的 MessageList、MessageInput  组件，构建一个聊天页面。
+
+MessageList 内建的功能是：
+- 展示单聊或群聊消息列表。
+
+- 支持对单条消息操作：查看图片消息大图、播放视频或语音消息、复制文本消息、撤回消息、删除消息等。
+
+   MessageInput 内建的功能是：
+
+- 支持用户组建并发送多种类型的消息：文本、表情、图片、语音、视频、文件等。
+
+   您可以将 MessageList 和  MessageInput 直接集成到现有的 App 页面中，也可以新构建一个完整的聊天页，组装后的一种 UI 效果如下图所示：
+
+   将 MessageList 和 MessageInput 组装为聊天页，可参考  `chat/uikit/src/main/java/io/trtc/tuikit/chat/pages/ChatPage.kt` 文件里的实现，`ChatPage` 主要做了以下工作：
+
+1. 在最上方添加了 headerView，展示会话的名称。
+
+2. 按照移动端用户使用习惯，上下拼接 MessageList 和 MessageInput。
+
+   核心示例代码如下所示：
+
+   ``` swift
+   @Composable
+   fun ChatPage(
+       conversationID: String,
+       locateMessage: MessageInfo? = null,
+       onUserClick: (String) -> Unit,
+       onChatHeaderClick: (String) -> Unit,
+       onBackClick: () -> Unit,
+   ) {
+       ...
+
+       val avatarUrl = conversationState.value?.avatarURL
+       val displayName = conversationState.value?.title
+       val colors = LocalTheme.current.colors
+       Scaffold(
+           modifier = Modifier
+               .background(color = colors.bgColorOperate)
+               .fillMaxSize()
+               .wrapContentHeight(), topBar = {
+               Box(
+                   modifier = Modifier
+                       .background(color = colors.bgColorOperate)
+                       .fillMaxWidth()
+                       .statusBarsPadding()
+               ) {
+                   ChatHeader(
+                       avatarUrl = avatarUrl,
+                       name = displayName ?: "",
+                       onBackClick = onBackClick,
+                       onAvatarClick = {
+                           onChatHeaderClick(conversationID)
+                       }
+                   )
+               }
+           },
+           bottomBar = {
+               Box(
+                   modifier = Modifier
+                       .fillMaxWidth()
+                       .background(color = colors.bgColorOperate)
+               ) {
+                   MessageInput(modifier = Modifier.navigationBarsPadding(), conversationID = conversationID)
+               }
+
+           }) { padding ->
+           Box(
+               modifier = Modifier
+                   .padding(padding)
+           ) {
+               MessageList(conversationID = conversationID, locateMessage = locateMessage) {
+                   onUserClick(it)
+               }
+           }
+       }
+   }
+   ```
+
+### 步骤5：构建联系人界面
+
+您可以基于 TUIKit Compose 中的 ContactList 组件，构建一个联系人页面。ContactList 内建的功能是：
+- 查看好友申请列表。
+
+- 查看已加入的群列表。
+
+- 处理群组邀请和申请。
+
+- 管理黑名单列表。
+
+- 查看好友。
+
+   您可以将 ContactList 直接集成到现有的 App 中，也可以新构建一个完整的联系人列表页，组装后的一种 UI 效果如下图所示：
+
+   将 ContactList 封装为联系人列表页，可参考 `chat/uikit/src/main/java/io/trtc/tuikit/chat/pages/ContactsPage.kt `文件里的实现，`ContactsPage` 主要做了以下工作：
+
+1. 在 ContactList 上方添加了 headerView。
+
+2. 传递点击联系人列表 cell 事件。
+
+   核心示例代码如下所示：
+
+   ``` swift
+   @Composable
+   fun ContactsPage(
+       onContactClick: (ContactInfo) -> Unit = {},
+       onGroupClick: (ContactInfo) -> Unit = {},
+       editContent: @Composable () -> Unit = {},
+   ) {
+
+       val colors = LocalTheme.current.colors
+       Column(
+           modifier = Modifier
+               .fillMaxSize()
+               .background(Colors.Transparent)
+       ) {
+           PageHeader(stringResource(R.string.chat_uikit_contacts)) {
+               editContent()
+           }
+
+           Box(
+               modifier = Modifier
+                   .fillMaxSize()
+                   .navigationBarsPadding(), contentAlignment = Alignment.Center
+           ) {
+               ContactList(onGroupClick = onGroupClick, onContactClick = onContactClick)
+           }
+       }
+   }
+   ```
+
+### 步骤6：完善界面间的跳转逻辑
+
+ConversationsPage、ChatPage、ContactsPage 中暴露了一些用户点击事件，您可以自定义事件来实现页面间的交互：
+| Page | 回调 | 建议跳转逻辑 |
+| --- | --- | --- |
+| **ConversationsPage** | `onConversationClick: (ConversationInfo) -> Unit` | 点击会话列表中的会话时触发，建议跳转到聊天页面（ChatPage）。 |
+| **ContactsPage** | `onContactClick: (ContactInfo) -> Unit` | 点击联系人 cell 时触发，建议跳转用户信息页（C2CChatSetting）。 |
+| `onGroupClick: (ContactInfo) -> Unit` | 点击群组 cell 时触发，建议跳转群聊页面（ChatPage）。 |  |
+| **ChatPage** | `onUserClick: (String) -> Unit` | 点击消息中的用户头像或昵称时触发，建议跳转用户信息页（C2CChatSetting）。 |
+| `onChatHeaderClick: (String) -> Unit` | 点击导航栏中的头像时触发，建议跳转用户信息页（C2CChatSetting）或群聊信息页（GroupChatSetting） |  |
+| `onBackClick: () -> Unit` | 点击返回按钮时触发，建议返回上一级页面。 |  |
+
+**chat/demo/app/src/main/java/io/trtc/tuikit/chat/MainActivity.kt **和 **chat/demo/app/src/main/java/io/trtc/tuikit/chat/chat/ChatActivity.kt** 作为上述 Page 的粘合层，实现了各个 Page 的回调事件，核心示例代码如下：
+``` java
+// chat/demo/app/src/main/java/io/trtc/tuikit/chat/MainActivity.kt
+
+// 点击会话列表 cell 跳转
+ConversationsPage(onConversationClick = {
+    activity?.startActivity(
+        Intent(activity, ChatActivity::class.java).apply {
+            putExtra("conversationID", it.conversationID)
+        }
+    )
+})
+
+// 点击联系人页面跳转
+ContactsPage(onGroupClick = {
+    ChatSettingActivity.start(context, "", it.contactID, true)
+}, onContactClick = {
+    ChatSettingActivity.start(context, it.contactID, "", true)
+})
+```
+``` java
+// chat/demo/app/src/main/java/io/trtc/tuikit/chat/chat/ChatActivity.kt
+
+// 点击聊天页面跳转
+ChatPage(
+   conversationID = conversationID,
+   locateMessage = message,
+   onUserClick = {
+       handleChatSettingNavigation(it)
+   }, onChatHeaderClick = {
+       val userID = getUserID(conversationID)
+       val groupID = getGroupID(conversationID)
+       handleChatSettingNavigation(userID, groupID)
+   }, onBackClick = { finish() })
+```
+
+您可以参考上述回调说明及参考代码，实现 Page 之间交互逻辑。
+
+## 常见问题
+
+### 功能常见问题
+
+**登录失败，提示签名错误**
+
+请检查 SDKAppID 和 UserSig 是否正确，UserSig 是否已过期。可以参考上文 配置用户鉴权 重新生成 UserSig。