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

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

@@ -0,0 +1,411 @@
+本文将介绍如何快速接入 TUICallKit 组件。您可以在 10 分钟内完成以下关键步骤，最终获得一个功能完备的音视频通话界面。
+
+## AI接入
+
+本接入文档已通过 **CodeBuddy** 的工程化验证，完全适配 **MCP (Model Context Protocol)** 协议。如需通过 AI 辅助接入，请参考以下**提示语**：
+
+“您现在是一名资深的 iOS 开发专家。请基于本文档，协助我在现有的 iOS 项目中接入音视频通话功能。”
+
+## 准备工作
+
+### 环境要求
+- **iOS 系统版本要求：**iOS 13.0 及以上。
+
+- **开发工具版本要求：**Xcode 13 及以上版本，Xcode 15 及以上版本可能会遇到 Sandbox 错误，请参见 Sandbox 问题解决方案 进行修复。
+
+- **依赖管理工具要求：**CocoaPods 环境安装。
+
+- **设备需满足：**搭载 iOS 13.0 及以上系统的 iPhone、iPad 等 Apple 移动设备（确保应用可正常安装与运行）。
+
+### 开通服务
+
+在使用腾讯云提供的音视频服务前，您需要前往控制台，为应用开通音视频服务。具体步骤详细参见 开通服务。开通服务后，请记录 `SDKAppID` 和 `SDKSecretKey`，在后续的（登录）步骤中会用到。
+
+## 快速接入
+
+### 步骤1：导入组件
+1. 添加 Pod 依赖。
+
+若项目已有 Podfile 文件
+
+在您项目的 `Podfile` 文件中添加 `pod 'TUICallKit_Swift'` 依赖。例如：
+``` ruby
+  target 'YourProjectTarget' do
+    pod 'TUICallKit_Swift'
+
+  end
+```
+
+若项目没有 Podfile 文件
+
+在终端中进入到您的 `.xcodeproj` 目录下，然后执行 `pod init` 命令创建 `Podfile` 文件，创建完成后，在您的 `Podfile` 文件中添加 `pod 'TUICallKit_Swift'`依赖。例如:
+``` swift
+
+// 1 终端中进入到您的 .xcodeproj 目录下
+cd /Users/yourusername/Projects/YourProject
+
+// 2
+pod init
+
+// 3 在生成的 Podfile 文件中
+  target 'YourProjectTarget' do
+    pod 'TUICallKit_Swift'
+
+  end
+```
+
+2. 安装组件。
+
+   在终端进入到 `Podfile` 文件所在的目录，然后执行以下命令安装组件。
+
+   ``` ruby
+   pod install --repo-update
+   ```
+
+   > **提示：**
+   >
+
+   > 安装完成后，使用 `YourProjectName.xcworkspace` 文件打开项目
+   >
+
+### 步骤2：工程配置
+
+为了使用音视频功能，您的应用需要获取麦克风和摄像头的权限。请在应用的 `Info.plist` 文件中添加以下两项，并填写对应的使用说明，这些说明将在系统请求权限时向用户显示：
+
+Info.plist 代码示例
+``` swift
+<key>NSCameraUsageDescription</key>
+<string>TUICallKitApp 需要访问您的摄像头，并可用于视频通话、群组视频通话等功能。</string>
+<key>NSMicrophoneUsageDescription</key>
+<string>TUICallKitApp 需要访问您的麦克风，并可用于音频通话、群组音频通话、视频通话、群组视频通话等功能</string>
+```
+
+### 步骤3：登录
+
+在您的项目中添加如下代码，调用 `login` 方法实现 TUI 组件的登录。这一步骤至关重要，只有在成功登录之后，您才能正常使用 TUICallKit 提供的各项功能。
+
+【iOS (Swift)】
+``` swift
+import TUICore
+import TUICallKit_Swift
+
+func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
+
+    let userID = "denny"       // 请替换为您的 UserId
+    let sdkAppID: Int = 0    // 请替换为在控制台得到的 SDKAppID
+    let secretKey = "****"     // 请替换为在控制台得到的 SecretKey
+
+    let userSig = GenerateTestUserSig.genTestUserSig(userID: userID, sdkAppID: sdkAppID, secretKey: secretKey)
+
+    TUILogin.login(Int32(sdkAppID), userID: userID, userSig: userSig) {
+      print("login success")
+    } fail: { code, message in
+      print("login failed, code: \(code), error: \(message ?? "nil")")
+    }
+
+    return true
+}
+```
+
+【iOS (Objective-C)】
+``` objectivec
+#import <TUICore/TUILogin.h>
+#import <TUICallKit_Swift/TUICallKit_Swift-Swift.h>
+
+- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
+
+    NSString *userID = @"denny";     // 请替换为您的 UserId
+    int sdkAppID = 0;                // 请替换为第一步在控制台得到的 SDKAppID
+    NSString *secretKey = @"****";   // 请替换为第一步在控制台得到的 SecretKey
+
+    NSString *userSig = [GenerateTestUserSig genTestUserSigWithUserID:userID sdkAppID:sdkAppID secretKey:secretKey];
+
+    [TUILogin login:sdkAppID
+             userID:userID
+            userSig:userSig
+               succ:^{
+        NSLog(@"login success");
+    } fail:^(int code, NSString * _Nullable msg) {
+        NSLog(@"login failed, code: %d, error: %@", code, msg);
+    }];
+
+    return YES;
+}
+```
+
+|参数|类型|说明|
+|---------|---------|---------|
+|userID|String|只允许包含大小写英文字母(a-z A-Z)、数字(0-9)及下划线和连字符。|
+|sdkAppId|int|在 [实时音视频 TRTC 控制台](https://console.cloud.tencent.com/trtc) 创建的音视频应用的唯一标识 SDKAppID。|
+|secretKey|String|在 [实时音视频 TRTC 控制台](https://console.cloud.tencent.com/trtc) 创建的音视频应用的 SDKSecretKey。|
+|userSig|String|一种安全保护签名，用于对用户进行登录鉴权认证，确认用户是否真实，阻止恶意攻击者盗用您的云服务使用权。|
+
+> **说明：**
+>
+> - **开发环境**：如果您在本地开发调试阶段，可以采用本地 [GenerateTestUserSig.genTestUserSig](https://github.com/Tencent-RTC/TUIKit_iOS/blob/main/call/TUICallKit_Swift/Debug/GenerateTestUserSig.swift) 函数生成 userSig。该方法中 secretKey 很容易被反编译逆向破解，一旦您的密钥泄露，攻击者就可以盗用您的腾讯云流量。
+> - **生产环境**：如果您的项目要发布上线，请采用 服务端生成 UserSig 的方式。
+
+### 步骤4：设置昵称和头像[可选]
+
+首次登录的用户没有头像和昵称信息，您可以通过 [setSelfInfo](https://cloud.tencent.com/document/product/647/78753#setSelfInfo) 接口设置头像和昵称：
+
+【iOS (Swift)】
+``` swift
+import TUICallKit_Swift
+import AtomicXCore
+
+TUICallKit.createInstance().setSelfInfo(nickname: "jack", avatar: "https:/****/user_avatar.png", completion: { result in
+    switch result {
+    case .success:
+        // 成功处理
+    case .failure(let error):
+        // 失败处理:
+    }
+})
+
+```
+
+|参数|类型|说明|
+|---------|---------|---------|
+|nickname|String|目标用户的昵称。|
+|avatar|String|目标用户的头像。|
+|completion|CompletionClosure|异步操作的结果回调。|
+
+### 步骤5：发起通话
+
+拨打方可以通过调用 calls 函数，并指定通话类型和被叫方的 userID，来发起语音或视频通话。calls 接口同时支持一对一通话和多人通话。当 userIDList 中包含一个 userID 时，为一对一通话；当 userIDList 包含多个 userID 时，则为多人通话。
+
+> **注意：**
+>
+
+> calls 接口不能写在 viewDidLoad 方法中，应放在按钮的点击事件或其他用户交互的响应方法中调用。
+>
+
+【iOS (Swift)】
+``` swift
+import TUICallKit_Swift
+import AtomicXCore
+
+TUICallKit.createInstance().calls(userIdList: ["mike"], mediaType: .audio, params: nil, completion: { result in
+    switch result {
+    case .success:
+      // 成功处理
+    case .failure(let error):
+      // 失败处理
+    }
+}
+```
+
+|参数|类型|说明|
+|---------|---------|---------|
+|userIdList|[String]|目标用户的 userID 列表。|
+|mediaType|[CallMediaType](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callmediatype)|通话的媒体类型，例如：视频通话、语音通话。|
+|params|[CallParams](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callparams)|通话扩展参数，例如：房间号、通话邀请超时时间等。|
+|completion|CompletionClosure|异步操作的结果回调。|
+
+### 步骤6：接听通话
+
+接听端完成登录后，拨打端发起通话，接听端就可以收到通话邀请，同时伴随铃声和振动。
+
+## 更多功能
+
+### AI 转录与翻译
+
+您可以通过调用 `enableAITranscriber` 开启/关闭 AI 转录与翻译功能。
+
+> **注意：**
+>
+> - 该功能默认为开启状态（enable = true）。如需关闭，请在发起通话前调用 `enableAITranscriber`(enable: false)。
+> - AI 实时转录与翻译为增值服务。体验版赠送免费额度，可直接体验。如需开通正式版，请在 [实时音视频控制台](https://console.cloud.tencent.com/trtc) 开通套餐包，详见 [计费说明](https://cloud.tencent.com/document/product/647/111976)。
+
+【iOS (Swift)】
+``` swift
+import TUICallKit_Swift
+
+TUICallKit.createInstance().enableAITranscriber(enable: true)
+```
+
+【iOS (Objective-C)】
+``` objectivec
+#import <TUICallKit_Swift/TUICallKit_Swift-Swift.h>
+
+[[TUICallKit createInstance] enableAITranscriber:YES];
+```
+
+**详情：**默认为 true，通话界面上显示 AI 翻译相关页面，设置为 false 后关闭。
+
+### 开启悬浮窗功能
+
+您可以通过调用 [enableFloatWindow](https://cloud.tencent.com/document/product/647/78753#enableFloatWindow) 开启/关闭悬浮窗功能，在初始化 TUICallKit 组件时启用该功能，默认状态为关闭（false）。可通过点击通话界面左上角的悬浮窗按钮，将通话界面缩小为悬浮窗形式。
+
+【iOS (Swift)】
+``` swift
+import TUICallKit_Swift
+
+TUICallKit.createInstance().enableFloatWindow(enable: true)
+```
+
+【iOS (Objective-C)】
+``` objectivec
+[[TUICallKit createInstance] enableFloatWindow:YES];
+```
+
+**详情：**默认为 false，通话界面左上角的悬浮窗按钮隐藏，设置为 true 后显示。
+
+### 开启来电横幅
+
+您可以通过调用 [enableIncomingBanner](https://cloud.tencent.com/document/product/647/78753#enableIncomingBanner) 开启/关闭来电横幅显示，该功能默认为关闭状态（false）。当被叫端收到来电时，默认展示全屏通话等待界面。启用此功能后，将首先显示一个横幅通知，然后根据需要切换到全屏通话界面。请注意，显示来电横幅需要授予悬浮窗权限，具体的显示策略将根据权限设置及应用当前是否在前台或后台运行来决定。
+
+【iOS (Swift)】
+``` swift
+import TUICallKit_Swift
+
+TUICallKit.createInstance().enableIncomingBanner(enable: true)
+```
+
+【iOS (Objective-C)】
+``` objectivec
+[[TUICallKit createInstance] enableIncomingBanner:YES];
+```
+
+**详情：**默认为 false，被叫端收到邀请后默认弹出全屏通话等待界面。开启后先展示一个横幅，然后根据需要拉起全屏通话界面。
+
+### 多人通话
+
+主叫方使用 `calls` 方法发起通话时，若被叫用户列表超过一人，则自动视为群组通话。其他成员可通过 `join` 方法加入该多人通话。
+- **发起多人通话：**使用 `calls` 方法发起通话时，若被叫用户列表（`userIdList`）超过一人，则自动视为群组通话。
+
+【iOS (Swift)】
+``` swift
+import TUICallKit_Swift
+import AtomicXCore
+
+TUICallKit.createInstance().calls(userIdList: ["mike", "tate"], mediaType: .audio, params: nil, completion: { result in
+    switch result {
+    case .success:
+        // 成功处理
+    case .failure(let error):
+        // 失败处理
+    }
+})
+
+```
+
+|参数|类型|说明|
+|---------|---------|---------|
+|userIdList|[String]|目标用户的 userId 列表|
+|mediaType|[CallMediaType](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callmediatype)|通话的媒体类型，例如：视频通话、语音通话|
+|params|[CallParams](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callparams)|通话扩展参数，例如：房间号、通话邀请超时时间等|
+|completion|CompletionClosure|异步操作的结果回调|
+
+- **加入多人通话：**可使用 `join` 方法加入指定的群组通话。
+
+【iOS (Swift)】
+``` swift
+import TUICallKit_Swift
+
+TUICallKit.createInstance().join(callId: "")
+```
+
+|参数|类型|说明|
+|---------|---------|---------|
+|callId|String|此次通话的唯一标识。|
+
+### 语言设置
+- **支持的语言：**目前支持**简体中文、繁体中文、英文、日文和阿拉伯语。**
+
+- **切换语言：**TUICallKit 默认语言与手机系统保持一致 。如果需要切换语言，可以使用 `TUIGlobalization.setPreferredLanguage`方法设置语言，以设置语言为英文示例的代码如下:
+
+【iOS (Swift)】
+``` swift
+import TUICore
+
+func setLanguage() {
+    TUIGlobalization.setPreferredLanguage("en")
+}
+```
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| language | String | 设置的语言：<br>- "zh-Hans" ：简体中文 。<br>- "zh-Hant" ：繁体中文。<br>- "en" ：英文。<br>- "ja"：日文。<br>- "ar" ：阿拉伯语。 |
+
+> **说明：**
+>
+
+>
+
+### 铃声设置
+
+您可通过以下方式设置默认铃声、来电静音模式、离线推送铃声：
+- **设置默认铃声（方式1）：**如果您通过源码依赖 TUICallKit 组件，您可以替换铃声资源文件（[发起呼叫时的铃音](https://github.com/Tencent-RTC/TUIKit_iOS/blob/main/call/TUICallKit_Swift/Resources/AudioFile/phone_dialing.m4a)、[接到呼叫时的铃音](https://github.com/Tencent-RTC/TUIKit_iOS/blob/main/call/TUICallKit_Swift/Resources/AudioFile/phone_ringing.mp3)）设置默认铃声。
+
+- **设置默认铃声（方式2）：**通过 [setCallingBell](https://cloud.tencent.com/document/product/647/78753#setCallingBell) 接口设置被叫端收到的来电铃声。
+
+【iOS (Swift)】
+``` swift
+import TUICallKit_Swift
+
+TUICallKit.createInstance().setCallingBell(filePath: "***/callingBell.mp3")
+```
+
+【iOS (Objective-C)】
+``` objectivec
+[[TUICallKit createInstance] setCallingBell:@"***/callingBell.mp3"];
+```
+
+**详情：**这里仅限传入本地文件地址，需要确保该文件目录是应用可以访问的。铃声设置后与设备绑定，更换用户，铃声依旧会生效。如需恢复默认铃声，filePath 传空即可。
+
+|参数|类型|说明|
+|---------|---------|---------|
+|filePath|String|铃声文件的路径。|
+
+- **来电静音模式：**您可以通过 [enableMuteMode](https://cloud.tencent.com/document/product/647/78750#enableMuteMode) 设置静音模式。
+
+【iOS (Swift)】
+``` swift
+import TUICallKit_Swift
+
+TUICallKit.createInstance().enableMuteMode(enable: true)
+```
+
+【iOS (Objective-C)】
+``` objectivec
+[TUICallKit createInstance] enableMuteMode: YES];
+```
+
+**详情：**开启后，收到通话请求，不会播放来电铃声。
+
+- **自定义离线推送铃声**：离线推送默认铃声是由系统决定的，如果您需要自定义铃声，请按以下步骤操作：
+
+  1. 准备自定义铃声：将您的铃声文件命名为 `phone_ringing.mp3`。
+
+  2. 替换项目文件：替换项目中现有的[同名铃声文件](https://github.com/Tencent-RTC/TUIKit_iOS/blob/main/call/TUICallKit_Swift/Resources/AudioFile/phone_ringing.mp3)。
+
+## 自定义您的 UI
+
+### 替换图标按钮
+
+您可以直接替换 [Resources/AtomicX.xcassets](https://github.com/Tencent-RTC/TUIKit_iOS/tree/main/atomic_x/Resources/AtomicX.xcassets) 文件夹下的图标，以确保整个 App 中的图标色调风格保持一致。以下列出了基本的功能按钮，您可以替换对应的图标以适配自己的业务场景。
+
+常用图标文件名列表
+| 图标 | 文件名称 | 说明 |
+| --- | --- | --- |
+|  | icon_dialing.png | 接听来电图标 |
+|  | icon_hangup.png | 挂断通话图标 |
+|  | icon_mute_on.png | 关闭麦克风图标 |
+|  | icon_handsfree.png | 关闭扬声器图标 |
+|  | icon_camera_off.png | 关闭摄像头图标 |
+|  | icon_add_user.png | 通话过程中邀请用户图标 |
+
+## 常见问题
+
+### **TUIKit 是否支持后台运行？**
+
+**支持**，如需要进入后台仍然运行相关功能，可选中当前工程项目，在 **Capabilities** 下的 **Background Modes** 模块中勾选 **Audio，AirPlay, and Picture in Picture** ，如下图所示：
+
+### Xcode 出现 **Sandbox: rsync **编译报错？
+
+可以在 **Build Settings **中把 **User Script Sandboxing **设置为 **NO：**
+
+如果您在接入和使用中遇到其他问题，请参见 常见问题。
+
+## 交流与反馈