@tencentcloud/sdk-mcp 1.4.7 → 1.6.0-beta.1

package/resource/integration/chat/preset/ios/integration.md

@@ -0,0 +1,568 @@
+TUIKit SwiftUI 是基于腾讯云 IM SDK 的一套 SwiftUI UI 组件库，提供了聊天、会话列表、联系人管理等即时通信功能的完整解决方案。本文介绍如何手动集成该组件并实现核心功能。
+
+## 关键概念
+
+TUIKit SwiftUI 提供了一套完整的即时通信 UI 组件，向下依赖 AtomicXCore 数据层，向上可构建各种功能性 Page。
+- Page 层：基于 TUIKit SwiftUI 组件封装的完整功能页面：ChatPage、ContactsPage、ConversationsPage，您可以直接使用。
+
+- TUIKit SwiftUI （UI 组件层）：基于 AtomicXCore 构建的 SwiftUI UI 组件，您可将其嵌套到自己已有的 App 页面中。
+
+- AtomicXCore（数据层）：提供数据管理和业务逻辑，包含各种 Store 和 Manager。
+
+## 前提条件
+- Xcode 12.0 及以上版本。
+
+- iOS 14.0 及以上系统版本  。
+
+- Swift 5 及以上版本。
+
+- 一个有效的腾讯云账号及 Chat 应用。可参见 开通服务 从控制台获取以下信息：
+
+  - SDKAppID：App 在控制台获取的 Chat 应用的 ID，为应用的唯一标识。
+
+  - SDKSecretKey：应用的密钥。
+
+      > **说明：**
+      >
+
+      > 本项目当前仅支持手动集成，暂不支持通过 CocoaPods、SPM 等包管理器集成。
+      >
+
+## 集成并引入组件
+
+### 下载源码
+
+从 GitHub 下载 [TUIKit SwiftUI](https://github.com/Tencent-RTC/TUIKit_iOS_SwiftUI/tree/main/atomic-x) 源码：
+``` bash
+git clone https://github.com/Tencent-RTC/TUIKit_iOS_SwiftUI.git
+```
+
+项目目录结构说明：
+``` bash
+atomic-x/
+├── Sources/              # UI 组件源码（必需集成）
+│   ├── MessageList/      # 消息列表组件
+│   ├── MessageInput/     # 消息输入组件
+│   ├── ConversationList/ # 会话列表组件
+│   ├── ContactList/      # 联系人列表组件
+│   ├── BaseComponent/    # 基础组件
+│   └── ...               # 其他UI组件
+├── Resources/            # 资源文件（必需集成）
+│   ├── assets/           # 图片资源
+│   └── strings/          # 本地化字符串文件
+chat/
+├── uikit/                # Page 组件（参考实现）
+│   ├── ChatPage.swift
+│   ├── ContactsPage.swift
+│   └── ConversationsPage.swift
+└── demo/                 # 示例应用（可选参考）
+```
+
+### 集成组件
+1. 将组件目录完整复制到您的 Xcode 项目中，如下图所示，其中 SwiftUIDemo 是示例项目，TUIKit_iOS_SwiftUI 是从 GitHub 上下载的组件源码：
+
+2. 修改您 Podfile 中每个组件的本地路径。path 是 TUIKit_iOS_SwiftUI 文件夹相对于您工程 Podfile 文件的位置，常见的有：
+
+  - TUIKit_iOS_SwiftUI 文件夹位于您工程 Podfile 文件**父目录**： `pod 'AtomicX/Chat', :path => '../TUIKit_iOS_SwiftUI/atomic-x/AtomicX.podspec'`
+
+  - TUIKit_iOS_SwiftUI 文件夹位于您工程 Podfile 文件**当前目录**： `pod 'AtomicX/Chat', :path => './TUIKit_iOS_SwiftUI/atomic-x/AtomicX.podspec'`
+
+  - TUIKit_iOS_SwiftUI 文件夹位于您工程 Podfile 文件**子目录**： `pod 'AtomicX/Chat', :path => '/TUIKit_iOS_SwiftUI/atomic-x/AtomicX.podspec'`
+
+      以 Podfile 跟 TUIKit_iOS_SwiftUI 是同级目录为例，Podfile 中添加：
+
+      ``` json
+      platform :ios, '14.0'
+
+      target 'Demo' do
+        use_frameworks! :linkage => :static
+
+        pod 'AtomicX/Chat', :path => './TUIKit_iOS_SwiftUI/atomic-x/AtomicX.podspec'
+        pod 'ChatUIKit', :path => './TUIKit_iOS_SwiftUI/chat/uikit/ChatUIKit.podspec'
+        pod 'AtomicXCore', '3.4.0'
+
+      end
+
+      #Pods config
+      post_install do |installer|
+          installer.pods_project.targets.each do |target|
+              target.build_configurations.each do |config|
+
+                  config.build_settings['SWIFT_VERSION'] = '5.0'
+
+                  #Do not strip Swift symbols
+                  config.build_settings['STRIP_SWIFT_SYMBOLS'] = 'NO'
+                  config.build_settings['DEBUG_INFORMATION_FORMAT'] = 'dwarf-with-dsym'
+
+                  #Fix Xcode14 Bundle target error
+                  config.build_settings['EXPANDED_CODE_SIGN_IDENTITY'] = ""
+                  config.build_settings['CODE_SIGNING_REQUIRED'] = "NO"
+                  config.build_settings['CODE_SIGNING_ALLOWED'] = "NO"
+                  config.build_settings['ENABLE_BITCODE'] = "NO"
+                  config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = "14.0"
+
+              end
+          end
+      end
+
+      ```
+3. Podfile 修改完毕后，执行以下命令，安装本地 TUIKit SwiftUI 组件。示例：
+
+   ``` bash
+   pod install
+   ```
+
+   pod install 会自动安装所需的依赖库：
+
+   > **注意：**
+   >
+>   - 使用本地集成方案时，如需升级时需要从 GitHub 获取最新的组件代码，覆盖您本地项目的 TUIKit SwiftUI 目录。
+>   - 当私有化修改和远端有冲突时，需要手动合并，处理冲突。
+
+### 配置项目
+1. **配置 Build Settings**
+
+   在项目的 Build Settings 中添加以下配置：
+
+  - Swift Language Version: Swift 5。
+
+  - iOS Deployment Target: 14.0 或更高。
+
+2. **配置 Info.plist**
+
+   添加必要的权限配置：
+
+   ``` xml
+   <key>NSCameraUsageDescription</key>
+   <string>App需要访问相机来拍摄照片和视频</string>
+   <key>NSMicrophoneUsageDescription</key>
+   <string>App需要访问麦克风来录制音频</string>
+   <key>NSPhotoLibraryUsageDescription</key>
+   <string>App需要访问相册来选择图片和视频</string>
+   ```
+
+## 接入步骤
+
+### 步骤1：配置用户鉴权
+
+在 [即时通信 IM 控制台](https://console.cloud.tencent.com/im/tool-usersig) 根据 UserID 获取 UserSig 用于后续登录时的用户鉴权。
+
+### **步骤2：用户登录**
+
+登录鉴权后才能正常使用组件的功能。您可以调用 login 接口，传入上文获取的 SDKAPPID、userSig 用于登录鉴权:
+``` swift
+import AtomicXCore
+
+// 用户登录
+LoginStore.shared.login(sdkAppID: sdkAppID, userID: userID, userSig: userSig, completion: { [weak self] result in
+      guard let self = self else { return }
+      switch result {
+      case .success:
+          // 登录成功，可跳转聊天或会话页
+      case .failure(let error):
+          // 登录失败，可弹框报错
+      }
+  })
+
+```
+
+> **警告：**
+>
+
+> 在正式的生产环境中，请在您的服务端生成 UserSig，在需要 UserSig 时由您的 App 向业务服务器发起请求获取动态 UserSig 来进行鉴权。详见 服务端生成 UserSig。
+>
+
+### 步骤3：构建会话列表界面
+
+您可以基于 TUIKit SwiftUI 中的 ConversationList 组件，构建一个会话列表页面。ConversationList 内建的功能是：
+- 展示用户的会话列表，包含单聊和群聊会话。
+
+- 支持用户操作单个会话：置顶、删除、清空会话消息等。
+
+   您可以将 ConversationList 直接集成到现有的 App 页面中，也可以新构建一个完整的会话列表页，组装后的一种 UI 效果如下图所示：
+
+   将 ConversationList 封装为会话列表页，可参考 `chat/uikit/ConversationsPage.swift` 文件里的实现，`ConversationsPage` 主要做了以下工作：
+
+1. 在 ConversationList 上方添加了 headerView。
+
+2. 实现点击会话列表 cell 事件。
+
+3. 支持创建会话和群组功能：
+
+  1. 点击右上角 "+" 按钮可以创建新会话或群组。
+
+  2. 支持从联系人列表选择好友创建单聊。
+
+  3. 支持选择多个好友创建群聊。
+
+      核心示例代码如下所示：
+
+      ``` swift
+      import AtomicX
+      import AtomicXCore
+      import SwiftUI
+
+      public struct ConversationsPage: View {
+          ...
+
+          public var body: some View {
+              VStack(spacing: 0) {
+                  headerView
+                  ConversationList(
+                      onConversationClick: { conversation in
+                          // Customize onConversationClick event
+                          onShowMessage?(NavigationInfo(conversation: conversation))
+                      }
+                  )
+                  .environmentObject(themeState)
+              }
+              .onReceive(contactListStore.state.subscribe(StatePublisherSelector(keyPath: \ContactListState.friendList))) { friendList in
+                  if self.friendList != friendList {
+                      self.friendList = friendList
+                  }
+              }
+              .onAppear {
+                  contactListStore.fetchFriendList(completion: { _ in })
+              }
+              .overlay(
+                  // Click + to show this menu.
+                  ChatsMenuOverlay(
+                      showChatsMenu: $showChatsMenu,
+                      showStartConversation: $showStartConversation,
+                      showUserPicker: $showUserPicker
+                  )
+              )
+              ...
+          }
+          ...
+      }
+
+      private var headerView: some View {
+          HStack {
+              Text(LocalizedChatString("TabChats"))
+                  .font(.system(size: 34, weight: .semibold))
+                  .tracking(0.3)
+                  .foregroundColor(themeState.colors.textColorPrimary)
+                  .background(themeState.colors.listColorDefault)
+                  .padding(.leading, 16)
+              Spacer()
+              if AppBuilderConfig.shared.enableCreateConversation {
+                  Button(action: {
+                      showChatsMenu.toggle()
+                  }) {
+                      Image(systemName: "plus")
+                          .font(.system(size: 20))
+                          .foregroundColor(themeState.colors.buttonColorPrimaryDefault)
+                          .frame(width: 28, height: 28)
+                          .cornerRadius(14)
+                  }
+                  .padding(.trailing, 16)
+              }
+          }
+          .padding(.top, 12)
+          .padding(.bottom, 16)
+      }
+      ```
+
+### 步骤4：构建聊天界面
+
+您可以基于 TUIKit SwiftUI 中的 MessageList、MessageInput  组件，构建一个聊天页面。
+- MessageList 内建的功能是：
+
+  - 展示单聊或群聊消息列表。
+
+  - 支持对单条消息操作：查看图片消息大图、播放视频或语音消息、复制文本消息、撤回消息、删除消息等。
+
+- MessageInput 内建的功能是：
+
+  - 支持用户组建并发送多种类型的消息：文本、表情、图片、语音、视频、文件等。
+
+      您可以将 MessageList 和  MessageInput 直接集成到现有的 App 页面中，也可以新构建一个完整的聊天页，组装后的一种 UI 效果如下图所示：
+
+      将 MessageList 和 MessageInput 组装为聊天页，可参考 `chat/uikit/ChatPage.swift` 文件里的实现，`ChatPage` 主要做了以下工作：
+
+1. 在最上方添加了 headerView，展示会话的名称。
+
+2. 按照移动端用户使用习惯，上下拼接 MessageList 和 MessageInput。
+
+   核心示例代码如下所示：
+
+   ``` swift
+   import AtomicX
+   import AtomicXCore
+   import SwiftUI
+
+   public struct ChatPage: View {
+       ...
+
+       public var body: some View {
+           return VStack(spacing: 0) {
+               self.navigationBarView
+
+               Divider()
+                   .background(self.themeState.colors.strokeColorPrimary)
+
+               VStack(spacing: 0) {
+                   MessageList(
+                       conversationID: self.conversation.id,
+                       listStyle: self.listStyle,
+                       locateMessage: self.locateMessage,
+                       onUserClick: { userID in
+                           onUserAvatarClick?(userID)
+                       }
+                   )
+
+                   self.messageInputAreaView
+               }
+               .ignoresSafeArea(.keyboard)
+           }
+           .toast(toast)
+       }
+
+       // Header
+       private var navigationBarView: some View {
+           HStack {
+               Button(action: {
+                   onBack?()
+               }) {
+                   Image(systemName: "chevron.left")
+                       .font(.system(size: 18, weight: .semibold))
+                       .foregroundColor(themeState.colors.textColorLink)
+               }
+               .padding(.leading, 16)
+
+               Button(action: {
+                   onNavigationAvatarClick?()
+               }) {
+                   HStack(spacing: 12) {
+                       Avatar(
+                           url: conversation.avatarURL,
+                           name: conversation.title ?? conversation.conversationID,
+                           size: .s
+                       )
+
+                       VStack(alignment: .leading, spacing: 2) {
+                           Text(conversation.title ?? conversation.conversationID)
+                               .font(.system(size: 17, weight: .semibold))
+                               .foregroundColor(themeState.colors.textColorPrimary)
+                               .lineLimit(1)
+
+                           if conversation.type == .group {
+                               Text("Group Chat")
+                                   .font(.system(size: 12))
+                                   .foregroundColor(themeState.colors.textColorSecondary)
+                           }
+                       }
+                   }
+               }
+               .buttonStyle(PlainButtonStyle())
+
+               Spacer()
+           }
+           .frame(height: 44)
+       }
+
+       // MessageInput
+       private var messageInputAreaView: some View {
+           VStack(spacing: 0) {
+               MessageInput(
+                   text: $messageText,
+                   conversationID: conversation.id,
+                   style: inputStyle,
+                   onHeightChange: { height in
+                       self.inputAreaHeight = height
+                   }
+               )
+               .padding(.bottom, 8)
+           }
+       }
+
+       ...
+   }
+   ```
+
+### 步骤5：构建联系人界面
+
+您可以基于 TUIKit SwiftUI 中的 ContactList 组件，构建一个联系人页面。ContactList 内建的功能是：
+- 查看好友申请列表。
+
+- 查看已加入的群列表。
+
+- 处理群组邀请和申请。
+
+- 管理黑名单列表。
+
+- 查看好友。
+
+   您可以将 ContactList 直接集成到现有的 App 中，也可以新构建一个完整的联系人列表页，组装后的一种 UI 效果如下图所示：
+
+   将 ContactList 封装为联系人列表页，可参考 `chat/uikit/ContactsPage.swift` 文件里的实现，`ContactsPage` 主要做了以下工作：
+
+1. 在 ContactList 上方添加了 headerView。
+
+2. 实现点击联系人列表 cell 事件。
+
+3. 支持添加联系人和添加群组：
+
+  1. 点击右上角 "+" 按钮可以添加联系人或群组。
+
+  2. 支持根据 UserID 搜索目标联系人。
+
+  3. 支持根据 GroupID 搜索目标群组。
+
+      核心示例代码如下所示：
+
+      ``` swift
+      import AtomicX
+      import AtomicXCore
+      import SwiftUI
+
+      public struct ContactsPage: View {
+          ...
+
+          public var body: some View {
+              VStack(spacing: 0) {
+                  headerView
+                  ContactList(
+                      contactStore: contactStore,
+                      onShowMessage: onShowMessage,
+                      onContactClick: onContactClick,
+                      onGroupClick: onGroupClick,
+                      onNewFriendsClick: onNewFriendsClick,
+                      onGroupApplicationsClick: onGroupApplicationsClick,
+                      onGroupListClick: onGroupListClick,
+                      onBlackListClick: onBlackListClick
+                  )
+              }
+              .overlay(
+                  Group {
+                      if showAddContactMenu {
+                          VStack {
+                              HStack {
+                                  Spacer()
+                                  AddContactPopView(
+                                      onDismiss: {
+                                          showAddContactMenu = false
+                                      },
+                                      onShowAddFriend: {
+                                          showAddFriend = true
+                                      },
+                                      onShowJoinGroup: {
+                                          showJoinGroup = true
+                                      }
+                                  )
+                                  .padding(.trailing, 16)
+                                  .padding(.top, 50)
+                              }
+                              Spacer()
+                          }
+                          .background(
+                              Color.clear
+                                  .contentShape(Rectangle())
+                                  .onTapGesture {
+                                      showAddContactMenu = false
+                                  }
+                          )
+                          .animation(.easeInOut(duration: 0.2), value: showAddContactMenu)
+                      }
+                  }
+              )
+              .sheet(isPresented: $showAddFriend) {
+                  AddFriendView(contactStore: contactStore)
+              }
+              .sheet(isPresented: $showJoinGroup) {
+                  JoinGroupView(contactStore: contactStore)
+              }
+          }
+
+          private var headerView: some View {
+              HStack {
+                  Text(LocalizedChatString("TabContacts"))
+                      .font(.system(size: 34, weight: .semibold))
+                      .tracking(0.3)
+                      .foregroundColor(themeState.colors.textColorPrimary)
+                      .padding(.leading, 16)
+                  Spacer()
+                  Button(action: {
+                      showAddContactMenu = true
+                  }) {
+                      Image(systemName: "plus")
+                          .font(.system(size: 20))
+                          .foregroundColor(themeState.colors.buttonColorPrimaryDefault)
+                          .frame(width: 28, height: 28)
+                          .cornerRadius(14)
+                  }
+                  .padding(.trailing, 16)
+              }
+              .padding(.top, 12)
+              .padding(.bottom, 16)
+          }
+
+          ...
+      }
+      ```
+
+### 步骤6：完善界面间的跳转逻辑
+
+ConversationsPage、ChatPage、ContactsPage 中暴露了一些用户点击事件，您可以自定义事件来实现页面间的交互：
+| Page | 回调 | 建议跳转逻辑 |
+| --- | --- | --- |
+| <strong>ConversationsPage</strong> | <code>onConversationClick: ((NavigationInfo) -> Void)?</code> | 点击会话列表中的会话时触发，建议跳转到聊天页面（ChatPage）。 |
+| <strong>ContactPage</strong> | <code>onContactClick: ((AZOrderedListItem) -> Void)?</code> | 点击联系人 cell 时触发，建议跳转联系人详情页面（C2CChatSetting）。 |
+| <code>onGroupClick: ((AZOrderedListItem) -> Void)?</code> | 点击群组 cell 时触发，建议跳转群聊页面（ChatPage）。 |  |
+| <strong>ChatPage</strong> | <code>onBack: (() -> Void)?</code> | 点击返回按钮时触发，建议返回上一级页面。 |
+| <code>onUserAvatarClick: ((String) -> Void)?</code> | 点击消息中的用户头像时触发，建议跳转用户信息页（C2CChatSetting）。 |  |
+| <code>onNavigationAvatarClick: (() -> Void)?</code> | 点击导航栏中的头像时触发，建议跳转用户信息页（C2CChatSetting）或群聊信息页（GroupChatSetting）。 |  |
+
+**chat/demo/ChatDemo/Pages/HomePage.swift** 作为上述 Page 的粘合层，实现了各个 Page 的回调事件，核心示例代码如下：
+``` swift
+// 点击会话列表 cell 跳转
+ConversationsPage(
+    onConversationClick: { navigationInfo in
+        showChatPage(conversation: navigationInfo.conversation, locateMessage: navigationInfo.locateMessage)
+    }
+)
+
+// 点击联系人页面跳转
+ContactsPage(
+    onContactClick: { user in
+        showContactDetail(user)
+    },
+    onGroupClick: { group in
+        let conversation = createConversationFromGroup(group)
+        showChatPage(conversation: conversation)
+    }
+)
+
+// ChatNavPage 是对 ChatPage 外层封装了导航栏的页面
+ChatNavPage(
+    conversation: conversation,
+    locateMessage: currentLocateMessage,
+    onBack: {
+        dismissChatPage()
+    },
+    onContactDelete: {
+        dismissChatPage()
+    },
+    onGroupDelete: {
+        dismissChatPage()
+    },
+    onNavigateToChat: { newConversation in
+        // First dismiss current chat page, then navigate to the new chat
+        dismissChatPage()
+        DispatchQueue.main.asyncAfter(deadline: .now() + 0.3) {
+            showChatPage(conversation: newConversation)
+        }
+    }
+)
+```
+
+您可以参考上述回调说明及参考代码，实现 Page 之间交互逻辑。
+
+## 常见问题
+
+### 功能常见问题
+
+#### **登录失败，提示签名错误怎么办？**
+
+请检查 SDKAppID 和 UserSig 是否正确，UserSig 是否已过期。可以参考上文“配置用户鉴权”重新生成 UserSig。