@tencentcloud/sdk-mcp 1.6.3 → 1.6.5

package/resource/integration/livekit/preset/live/ios/prepare-integration.md

@@ -0,0 +1,218 @@
+本章节主要指导您完成 `TUILiveKit` **UI 组件库接入**的环境配置。
+
+> **集成方案说明：**
+>
+> 本文档提供的是 **UI 组件库接入方案**，包含视频直播、语聊房的完整 UI 界面与全套业务逻辑。如果您有极高的 UI 定制需求，需要采用 无 UI（Core SDK） 集成方式，请直接参考 Core SDK 快速开始。
+>
+
+## 功能预览
+
+`TUILiveKit` 是一个功能全面的直播组件，集成后可快速实现以下场景功能。
+
+### **视频直播**
+
+|**主播准备页**|**主播开播页**|**直播列表**|**观众观看页**|
+|---------|---------|---------|---------|
+|||||
+
+### **语聊房**
+
+|**主播准备页**|**主播开播页**|**直播列表**|**观众观看页**|
+|---------|---------|---------|---------|
+|||||
+
+## 准备工作
+
+### 开通服务
+
+在使用 **TUILiveKit** 前，请先参考 开通服务，领取 TUILiveKit 体验版或者开通付费版。
+
+### 环境要求
+- **Xcode**：需使用 **Xcode 15** 或更高版本。
+
+- **iOS 系统**：支持 **iOS 14.0** 或更高版本的设备。
+
+- **CocoaPods 环境**：已安装 CocoaPods 环境。如果您尚未安装，请参见 [CocoaPods 官网安装](https://guides.cocoapods.org/using/getting-started.html)，或按以下步骤操作：
+
+  - **使用 gem 安装 CocoaPods**：在终端中执行 `sudo gem install cocoapods` 命令进行安装。
+
+      > **提示：**
+      >
+      >  `sudo gem install cocoapods` 安装过程中可能需要输入电脑密码，按提示输入管理员密码即可。
+      >
+
+## 代码集成
+
+### 步骤 1：通过 CocoaPods 导入组件
+1. **添加 Pod 依赖：**
+
+  - **若项目已有 Podfile 文件。**
+
+      在您项目的 `Podfile` 文件中添加 `pod 'TUILiveKit'` 依赖。例如：
+
+      ``` ruby
+        target 'YourProjectTarget' do
+          # 其他已有的 Pod 依赖...
+          # 添加 pod 'TUILiveKit' 依赖
+          pod 'TUILiveKit'
+
+        end
+      ```
+  - **若项目没有 Podfile 文件。**
+
+      在终端中通过 `cd` 命令切换到您的 `.xcodeproj` 目录下，然后执行 `pod init` 命令创建 `Podfile` 文件，创建完成后，在您的 `Podfile` 文件中添加 `pod 'TUILiveKit'` 依赖。例如:
+
+      ``` bash
+      // 如果您的项目目录是 /Users/yourusername/Projects/YourProject
+
+      // 1. cd 到您的.xcodeproj 工程目录下
+      cd /Users/yourusername/Projects/YourProject
+
+      // 2. 执行 pod init，此命令运行完后，会在您的工程目录下生成一个 Podfile 文件。
+      pod init
+
+      // 3. 在生成的 Podfile 文件中添加 pod 'TUILiveKit' 依赖
+        target 'YourProjectTarget' do
+          # 添加 pod 'TUILiveKit' 依赖
+          pod 'TUILiveKit'
+
+        end
+      ```
+2. **安装组件**：
+
+   在终端中 `cd` 到 `Podfile` 文件所在的目录，然后执行以下命令安装组件。
+
+   ``` bash
+   pod install
+   ```
+
+### 步骤 2：工程配置
+
+为了使用音视频功能，您的应用需要获取麦克风和摄像头的权限。请在应用的 `Info.plist` 文件中添加以下两项，并填写对应的使用说明，这些说明将在系统请求权限时向用户显示：
+``` bash
+<key>NSCameraUsageDescription</key>
+<string>TUILiveKit需要访问你的相机权限，开启后录制的视频才会有画面</string>
+<key>NSMicrophoneUsageDescription</key>
+<string>TUILiveKit需要访问您的麦克风权限，开启后录制的视频才会有声音</string>
+```
+
+## 完成登录
+
+代码集成完成后，您需要完成登录，这是**使用 TUILiveKit 的关键步骤**，因为只有在登录成功后才能正常使用 TUILiveKit 的各项功能，故请您耐心检查相关参数是否配置正确：
+
+> **说明：**
+>
+> 在示例代码中，登录操作是在 `didFinishLaunchingWithOptions` 方法内完成的。但在实际项目场景下，强烈推荐 **您在完成自己的用户身份验证等相关登录操作后，再调用 TUILiveKit 的登录服务**。这样可以避免因过早调用登录服务，导致业务逻辑混乱或数据不一致的问题，同时也能更好地适配您项目中现有的用户管理和权限控制体系。
+>
+
+【Swift】
+``` swift
+//
+//  AppDelegate.swift
+//
+
+// 1. 导入 AtomicXCore
+import AtomicXCore
+
+// 2. 示例代码在 didFinishLaunchingWithOptions 完成登录，推荐您在自己登录业务完成后再调用登录服务
+func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
+
+    // 3. 调用登录接口
+    LoginStore.shared.login(sdkAppID: 1400000001,                 // 请替换为开通服务控制台的 SDKAppID
+                            userID: "denny",                      // 请替换为您的 UserID
+                            userSig: "xxxxxxxxxxx") { [weak self] result in    // 您可以在控制台中计算一个 UserSig 并填在这个位置
+        guard let self = self else { return }
+        switch result {
+        case .success():
+            print("login success")
+        case .failure(let err):
+            print("login failed. code: \(err.code), error:\(err.message)")
+        }
+    }
+
+    return true
+}
+```
+
+**登录接口参数说明**
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| SDKAppID | Int | 从 <a href="https://console.cloud.tencent.com/trtc">TRTC 控制台 > 应用管理</a> 获取。 |
+| UserID | String | 当前用户的唯一 ID，仅包含英文字母、数字、连字符和下划线。 |
+| userSig | String | 用于腾讯云鉴权的票据。请注意：<br>- 开发环境：您可以采用本地 <code>GenerateTestUserSig.genTestSig</code> 函数生成 UserSig 或者通过 <a href="https://console.cloud.tencent.com/im/tool-usersig">UserSig 辅助工具</a> 生成临时的 UserSig。<br>- 生产环境：为了防止密钥泄露，请务必采用服务端生成 UserSig 的方式。详细信息请参见 <a href="https://cloud.tencent.com/document/product/647/17275#formal">服务端生成 UserSig</a>。<br>更多信息请参见 <a href="https://cloud.tencent.com/document/product/647/17275">如何计算及使用 UserSig</a>。 |
+
+## 登录异常状态处理【可选】
+
+`LoginStore` 提供了登录状态回调机制，方便您处理可能出现的登录异常情况，主要包括 **“被踢下线”** 和 **“签名过期”** 这两种异常状态的回调：
+- 被踢下线：用户在线情况下被踢，SDK 会通过 `onKickedOffline` 回调通知给您，此时可以在 UI 提示用户，并调用 `LoginStore.shared.login` 重新登录。
+
+- 签名过期：用户在线期间收到 `onUserSigExpired` 回调，说明您之前给该用户签发的 userSig 已经过期了，这个时候如果当前用户在您后台的登录态依然有效，您可以让您的 APP 向您的后台请求新的 userSig，并调用 `LoginStore.shared.login` 续签登录态。
+
+   ``` swift
+   // YourLoginService 代表您负责登录的业务模块
+   class YourLoginService: NSObject {
+       private var cancelableSet: Set<AnyCancellable> = []
+
+       // 监听登录状态回调
+       func subscribeLoginStatus() {
+           LoginStore.shared.loginEventPublisher
+               .receive(on: RunLoop.main)
+               .sink { [weak self] loginEvent in
+                   guard let self = self else { return }
+                   switch loginEvent {
+                   case .kickedOffline:  // 用户被踢下线回调
+
+                       // 您的业务代码：UI 交互提示用户，然后重新登录
+                       break
+                   case .loginExpired:   // 用户签名过期回调
+                       // 您的业务代码：如果当前用户在您后台的登录态依然有效，
+                       // 您可以让您的 app 向您的后台请求新的 userSig，
+                       // 并调用 LoginStore.shared.login 续签登录态。
+                       break
+                   default:
+                       break
+                   }
+               }
+               .store(in: &self.cancelableSet)
+       }
+   }
+
+   ```
+
+## 下一步
+
+恭喜您，现在您已经成功集成了**直播**组件并完成了登录。接下来，您可以根据您的业务场景实现**主播开播**、**观众观看**、**直播列表**等功能。
+| <strong>业务场景</strong> | <strong>描述</strong> | <strong>集成指引</strong> |
+| --- | --- | --- |
+| <strong>视频直播</strong> | 包含主播开播、观众观看、连麦互动、美颜设置、礼物弹幕等全套功能。 | - 主播开播<br>- 观众观看 |
+| <strong>语聊房</strong> | 包含麦位管理、背景音乐、礼物互动、语聊控场等完整业务逻辑。 | - 主播开播<br>- 观众观看 |
+| <strong>直播列表</strong> | 展示直播间/语聊房列表，支持封面、人数、房间标题等信息展示。 | - 直播列表 |
+
+## 常见问题
+
+### pod install 执行后本地安装找不到 TUILiveKit 最新版本？
+
+如果无法安装 TUILiveKit 最新版本，请按以下步骤操作：
+1. 在 Podfile 所在目录下删除 `Podfile.lock` 和 `Pods`，您可以选择手动删除或终端执行以下命令
+
+   ``` bash
+   // cd 到 Podfile 所在目录下
+
+   rm -rf Pods/
+   rm Podfile.lock
+   ```
+2. 在 Podfile 所在目录下执行 `pod install --repo-update`
+
+   ``` bash
+   // cd 到 Podfile 所在目录下
+
+   pod install --repo-update
+   ```
+
+### 每次进房都需要调用登录吗？
+
+不需要。通常您只需要完成一次 `LoginStore.shared.login` 调用即可，我们建议您将 `LoginStore.shared.login` 和 `LoginStore.shared.logout` 与自己的登录业务关联。
+
+### Podfile 文件有没有示例配置可以参考？
+
+您可以参考 [GitHub TUILiveKit Example](https://github.com/Tencent-RTC/TUIKit_iOS/blob/main/application/Podfile) 工程 `Podfile` 示例文件。

package/resource/integration/livekit/preset/live/vue/live-list-integration.md

@@ -33,11 +33,10 @@ yarn add tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3
 
 ### 步骤3: 直播列表页面接入
 
-在您的项目下创建 **live-list.vue **文件，可直接复制如下代码至您的项目中集成**直播列表页面**。
+在您的项目下创建 **live-list.vue** 文件，可直接复制如下代码至您的项目中集成**直播列表页面**。
 
 > **注意：**
 >
-
 > 您可以直接复制如下代码至您的工程中集成示例工程，也可以访问 [直播列表](https://github.com/Tencent-RTC/TUILiveKit/blob/main/Web/web-vite-vue3/src/TUILiveKit/LiveListView.vue) 地址，查看更加详细的源码内容。
 >
 
@@ -84,7 +83,6 @@ onMounted(async () => {
 
 > **注意：**
 >
-
 > 若您需要实现直播列表到进入直播间的跳转逻辑，可参考本文中 指定直播间 部分内容。
 >
 
@@ -96,8 +94,7 @@ onMounted(async () => {
 
 > **说明：**
 >
-
-> 上述命令执行成功后，请在浏览器地址栏输入本地访问地址（您可以根据项目参考，例如` http://localhost:5173/live-list`，具体端口号可能因您的项目配置而有所不同），即可看到直播列表页面。
+> 上述命令执行成功后，请在浏览器地址栏输入本地访问地址（您可以根据项目参考，例如 `http://localhost:5173/live-list`，具体端口号可能因您的项目配置而有所不同），即可看到直播列表页面。
 >
 
 ``` bash
@@ -106,7 +103,7 @@ onMounted(async () => {
 
 ### 指定直播间
 
-由于涉及到直播列表(或首页)到观看页面的跳转逻辑，您需要配置 Vue Router 来实现页面跳转 。您可以在项目 `src` 目录下新建 `router` 文件夹，并创建 `index.ts` 文件。然后，在您的主文件（例如 **main.ts **或 **index.ts**）中引入并使用路由。可参见 [GitHub 代码示例](https://github.com/Tencent-RTC/TUILiveKit/blob/main/Web/web-vite-vue3/src/main.ts)。
+由于涉及到直播列表(或首页)到观看页面的跳转逻辑，您需要配置 Vue Router 来实现页面跳转 。您可以在项目 `src` 目录下新建 `router` 文件夹，并创建 `index.ts` 文件。然后，在您的主文件（例如 **main.ts** 或 **index.ts**）中引入并使用路由。可参见 [GitHub 代码示例](https://github.com/Tencent-RTC/TUILiveKit/blob/main/Web/web-vite-vue3/src/main.ts)。
 
 #### 步骤1：配置页面路由
 
@@ -210,7 +207,7 @@ import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3';
 
 ### 按钮 Button 和 图标 Icon
 
-您可以对按钮、图标等控件进行自定义。以` live-list.vue` 为例，对` Button`、`Icon` 控件执行增删改等操作都可以满足您的自定义需求。除布局调整外，我们还支持对颜色、字体、圆角以及输入框、弹框等内容进行全面修改，充分满足您的 UI 定制需求。
+您可以对按钮、图标等控件进行自定义。以 `live-list.vue` 为例，对 `Button`、`Icon` 控件执行增删改等操作都可以满足您的自定义需求。除布局调整外，我们还支持对颜色、字体、圆角以及输入框、弹框等内容进行全面修改，充分满足您的 UI 定制需求。
 | <strong>类别</strong> | <strong>功能</strong> | <strong>描述</strong> |
 | --- | --- | --- |
 | <strong>素材管理</strong> | 自定义素材管理区域展示 | 支持调整 Icon 的大小、颜色或对 Icon 进行替换。 |

package/resource/integration/livekit/preset/live/vue/live-player-desk-integration.md

@@ -1,8 +1,7 @@
 本文对 TUILiveKit Demo 中的**观看页面**进行了详细的介绍，您可以在已有项目中直接参考本文档集成我们开发好的观看页面，也可以根据您的需求按照文档中的内容对页面的样式，布局以及功能项进行深度的定制。
 
-> **集成提示****：**
+> **集成提示：**
 >
-
 > 本文档介绍基于 **UI 组件** 的观众观看方式（含完整交互 UI）。若您需通过 **Core SDK** 自行搭建观众端界面，请参考 观众观看 (Core SDK)。
 >
 
@@ -21,7 +20,6 @@
 
    > **说明：**
    >
-
    > 本文档主要介绍观众端的核心功能逻辑。如果您需要修改观众端的界面样式（如修改某些默认控件、修改图标和颜色、调整弹窗风格），请直接前往 调整界面风格 指南进行配置。
    >
 
@@ -52,11 +50,10 @@ yarn add tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3
 
 ### 步骤3：观看页面接入
 
-在您的项目下创建 `live-player.vue`文件，可直接复制如下代码至您的项目中集成**观看页面**。
+在您的项目下创建 `live-player.vue` 文件，可直接复制如下代码至您的项目中集成**观看页面**。
 
 > **注意：**
 >
-
 > 您可以直接复制如下代码至您的工程中集成示例工程，也可以访问 [观众观看](https://github.com/Tencent-RTC/TUILiveKit/blob/main/Web/web-vite-vue3/src/TUILiveKit/component/LivePlayer/LivePlayerPC.vue) 地址，查看更加详细的源码内容。
 >
 
@@ -149,8 +146,7 @@ onMounted(async () => {
 
 > **说明：**
 >
-
-> 上述命令执行成功后，请在浏览器地址栏输入本地访问地址（您可以根据项目参考，例如` http://localhost:5173/live-player`，具体端口号可能因您的项目配置而有所不同），即可看到观看页面。
+> 上述命令执行成功后，请在浏览器地址栏输入本地访问地址（您可以根据项目参考，例如 `http://localhost:5173/live-player`，具体端口号可能因您的项目配置而有所不同），即可看到观看页面。
 >
 
 ``` bash
@@ -170,7 +166,6 @@ npm run dev
 
    > **重要提示：**
    >
-
    > 请使用不同的**用户 ID** 开播和观看，否则后登录的设备会强制先登录的设备下线（即**被踢下线**）。
    >
 
@@ -180,11 +175,10 @@ npm run dev
 
 ### 步骤3：路由配置
 
-由于涉及到直播列表(或首页)到直播间的跳转逻辑，您需要配置 Vue Router。在项目 **src** 目录下新建 **router **文件夹，并创建 **index.ts **文件。然后，在您的主文件（例如 **main.ts** 或 **index.ts**）中引入并使用路由。可参见 [GitHub 代码示例](https://github.com/Tencent-RTC/TUILiveKit/blob/main/Web/web-vite-vue3/src/main.ts)，如果需要直播列表，可参见文档 直播列表。
+由于涉及到直播列表(或首页)到直播间的跳转逻辑，您需要配置 Vue Router。在项目 **src** 目录下新建 **router** 文件夹，并创建 **index.ts** 文件。然后，在您的主文件（例如 **main.ts** 或 **index.ts**）中引入并使用路由。可参见 [GitHub 代码示例](https://github.com/Tencent-RTC/TUILiveKit/blob/main/Web/web-vite-vue3/src/main.ts)，如果需要直播列表，可参见文档 直播列表。
 
 > **注意：**
 >
-
 > 如下代码示例中的 `live-player.vue` 文件即代表 步骤3 中创建的示例文件。
 >
 
@@ -241,7 +235,7 @@ import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3';
 
 ### 按钮 Button 和图标 Icon
 
-若您需要对按钮 Button 或图标 Icon 等其他控件进行新增或替换等 UI 定制，您可以通过如下方式实现，以 `live-player.vue `文件中的按钮和图标为例，您可以参考下图找到对应按钮或图标的指定位置源码，对当前部分的控件进行**增加、删除、替换**等 UI 定制操作。
+若您需要对按钮 Button 或图标 Icon 等其他控件进行新增或替换等 UI 定制，您可以通过如下方式实现，以 `live-player.vue` 文件中的按钮和图标为例，您可以参考下图找到对应按钮或图标的指定位置源码，对当前部分的控件进行**增加、删除、替换**等 UI 定制操作。
 
 根据上述示例，我们同样支持您根据项目需求对**观众观看页面**进行 UI 定制的能力。除了页面 UI 布局调整，我们也支持您对**颜色主题、字体、圆角、按钮、图标、输入框、弹框等**内容进行**增加、删除、修改**等操作，满足您的 UI 定制需要。
 | <strong>类别</strong> | <strong>功能</strong> | <strong>描述</strong> |
@@ -299,7 +293,6 @@ export { useCustomizedAutoPlayDialog };
 
 > **说明：**
 >
-
 > 您需要安装对应的 `@tencentcloud/tuiroom-engine-js。`
 >
 

package/resource/integration/livekit/preset/live/vue/live-player-h5-integration.md

@@ -1,8 +1,7 @@
 本文对 TUILiveKit Demo 中的**观看页面**进行了详细的介绍，您可以在已有项目中直接参考本文档集成我们开发好的观看页面，也可以根据您的需求按照文档中的内容对页面的样式，布局以及功能项进行深度的定制。
 
-> **集成提示****：**
+> **集成提示：**
 >
-
 > 本文档介绍基于 **UI 组件** 的观众观看方式（含完整交互 UI）。若您需通过 **Core SDK** 自行搭建观众端界面，请参考 观众观看 (Core SDK)。
 >
 
@@ -46,11 +45,10 @@ yarn add tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3
 
 ### 步骤3：观看页面接入
 
-在您的项目下创建 **live-player.vue **文件，可直接复制如下代码至您的项目中集成**观看页面**。
+在您的项目下创建 **live-player.vue** 文件，可直接复制如下代码至您的项目中集成**观看页面**。
 
 > **注意：**
 >
-
 > 您可以直接复制如下代码至您的工程中集成示例工程，也可以访问 [观众观看](https://github.com/Tencent-RTC/TUILiveKit/blob/main/Web/web-vite-vue3/src/TUILiveKit/component/LivePlayer/LivePlayerH5.vue) 地址，查看更加详细的源码内容。
 >
 
@@ -143,8 +141,7 @@ onMounted(async () => {
 
 > **说明：**
 >
-
-> 上述命令执行成功后，请在浏览器地址栏输入本地访问地址（您可以根据项目配置参考，例如` http://localhost:5173/live-player`，具体端口号可能因您的项目配置而有所不同），即可看到观看页面。
+> 上述命令执行成功后，请在浏览器地址栏输入本地访问地址（您可以根据项目配置参考，例如 `http://localhost:5173/live-player`，具体端口号可能因您的项目配置而有所不同），即可看到观看页面。
 >
 
 ``` bash
@@ -164,7 +161,6 @@ npm run dev
 
    > **重要提示：**
    >
-
    > 请使用不同的**用户 ID** 开播和观看，否则后登录的设备会强制先登录的设备下线（即“被踢下线”）。
    >
 
@@ -174,17 +170,15 @@ npm run dev
 
 > **说明：**
 >
-
 > 另外，若您需要修改个人信息，请参考 步骤 3 示例代码中的 `setSelfInfo` 进行个人信息的设置。
 >
 
 ### 步骤3：路由配置
 
-由于涉及到直播列表(或首页)到直播间的跳转逻辑，您需要配置 Vue Router。在项目 **src** 目录下新建 **router **文件夹，并创建 **index.ts **文件。然后，在您的主文件（例如 **main.ts** 或 **index.ts**）中引入并使用路由。可参见 [GitHub 上的代码示例](https://github.com/Tencent-RTC/TUILiveKit/blob/main/Web/web-vite-vue3/src/main.ts)，如果需要直播列表，可参见文档 直播列表。
+由于涉及到直播列表(或首页)到直播间的跳转逻辑，您需要配置 Vue Router。在项目 **src** 目录下新建 **router** 文件夹，并创建 **index.ts** 文件。然后，在您的主文件（例如 **main.ts** 或 **index.ts**）中引入并使用路由。可参见 [GitHub 上的代码示例](https://github.com/Tencent-RTC/TUILiveKit/blob/main/Web/web-vite-vue3/src/main.ts)，如果需要直播列表，可参见文档 直播列表。
 
 > **注意：**
 >
-
 > 如下代码示例中的 `live-player.vue` 文件即代表 步骤3 中创建的示例文件。
 >
 
@@ -299,7 +293,6 @@ export { useCustomizedAutoPlayDialog };
 
 > **说明：**
 >
-
 > 您需要安装对应的 `@tencentcloud/tuiroom-engine-js。`
 >