@tencentcloud/sdk-mcp 1.6.3 → 1.6.5

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

@@ -0,0 +1,271 @@
+本章节主要指导您完成 `TUILiveKit` **UI 组件库接入**的环境配置。
+
+> **集成方案说明：**
+>
+> 本文档提供的是 **UI 组件库接入方案**，包含视频直播、语聊房的完整 UI 界面与全套业务逻辑。如果您有极高的 UI 定制需求，需要采用 无 UI（Core SDK） 集成方式，请直接参考 Core SDK 快速开始。
+>
+
+## 功能预览
+
+TUILiveKit UI 组件为您提供的是功能闭环、交互丰富的直播全链路逻辑，集成后可快速实现一套交互完整、业务丰富的直播系统。
+
+### **视频直播**
+
+|**主播准备页**|**主播开播页**|**直播列表**|**观众观看页**|
+|---------|---------|---------|---------|
+|||||
+
+### **语聊房**
+
+|**主播准备页**|**主播开播页**|**直播列表**|**观众观看页**|
+|---------|---------|---------|---------|
+|||||
+
+## **准备工作**
+
+### 开通服务
+
+在使用 **TUILiveKit** 前，请先参考 开通服务，领取 TUILiveKit 体验版或者开通付费版。
+
+### 环境要求
+- **Android Studio Arctic Fox (2020.3.1)** 及以上版本。
+
+- **Gradle 7.0** 及以上的版本。
+
+- **Android** **5.0** 及以上的手机设备。
+
+## 代码集成
+
+### **步骤 1：下载 TUILiveKit 组件**
+
+在 [GitHub](https://github.com/Tencent-RTC/TUIKit_Android) 中克隆/下载代码，然后将 `live` 目录和 `atomic_x` 目录拷贝到您当前 `Android` 项目的 `app` 文件夹同级目录中。
+
+### 步骤 2：工程配置
+
+#### 1. 配置 JitPack 仓库
+
+在工程**根目录**下的 `settings.gradle.kts` 或 `settings.gradle` 文件中，添加 JitPack 仓库地址，项目中播放礼物 SVG 动画的第三方库托管在 JitPack 仓库中，需要从 JitPack 仓库中查找依赖项。
+
+【settings.gradle.kts】
+``` java
+dependencyResolutionManagement {
+    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
+    repositories {
+        google()
+        mavenCentral()
+
+        // 添加 JitPack 仓库地址
+        maven { url = uri("https://jitpack.io") }
+    }
+}
+```
+
+【settings.gradle】
+``` java
+dependencyResolutionManagement {
+    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
+    repositories {
+        google()
+        mavenCentral()
+
+        // 添加 JitPack 仓库地址
+        maven { url 'https://jitpack.io' }
+    }
+}
+```
+
+#### 2. 导入 TUILiveKit 组件
+
+在工程根目录下的 `settings.gradle.kts` 或 `settings.gradle` 文件中，增加以下代码以导入 **tuilivekit** 组件。
+
+【settings.gradle.kts】
+``` java
+include(":tuilivekit")
+project(":tuilivekit").projectDir = File(settingsDir, "live/tuilivekit")
+
+include(":atomic_x")
+project(":atomic_x").projectDir = File(settingsDir, "atomic_x")
+```
+
+【settings.gradle】
+``` java
+include ':tuilivekit'
+project(':tuilivekit').projectDir = new File(settingsDir, "live/tuilivekit")
+
+include(":atomic")
+project(':atomic').projectDir = new File(settingsDir, "atomic_x")
+```
+
+#### 3. 添加组件依赖
+
+在 `app` 目录下找到 `build.gradle.kts`（或 `build.gradle`）文件，并在文件中增加以下代码，该步骤的作用是声明当前 App 对新加入的 **tuilivekit** 组件的依赖。
+
+【build.gradle.kts】
+``` java
+dependencies {
+    // 添加 tuilivekit 依赖
+    api(project(":tuilivekit"))
+}
+```
+
+【build.gradle】
+``` java
+dependencies {
+    // 添加 tuilivekit 依赖
+    api project(':tuilivekit')
+}
+```
+
+   > **说明：**
+   >
+   > TUILiveKit 内部已默认依赖 TRTC SDK、IM SDK 等公共库，您无需单独配置。
+   >
+
+#### 4. 配置混淆规则
+
+由于 SDK 内部使用了 Java 反射，请在 `proguard-rules.pro` 文件中添加以下代码，将相关类加入不混淆名单，以确保功能正常运行。
+``` java
+-keep class com.tencent.** { *; }
+-keep class com.tencent.beacon.** { *; }
+-keep class com.tencent.cloud.iai.lib.** { *; }
+-keep class com.tencent.qimei.** { *; }
+-keep class com.tencent.xmagic.** { *; }
+-keep class com.trtc.uikit.livekit.component.gift.store.model.** { *; }
+-keep class com.trtc.uikit.livekit.livestreamcore.** { *; }
+-keep class com.tcmediax.** { *; }
+
+# Google 序列化/反序列化框架 Gson 库相关混淆
+-keep class com.google.gson.** { *; }
+
+# 美颜特效相关混淆
+-keep class androidx.exifinterface.** { *; }
+-keep class com.gyailib.** { *; }
+-keep class org.extra.** { *; }
+-keep class org.libpag.** { *; }
+-keep class org.light.** { *; }
+
+# 播放礼物 SVG 动画相关混淆
+-keep class com.opensource.svgaplayer.proto.** { *; }
+-keep class com.squareup.wire.** { *; }
+```
+
+#### 5. 修改 AndroidManifest.xml
+
+为了防止编译时 `AndroidManifest` 合并过程中产生属性冲突，您需要在 `app/src/main/AndroidManifest.xml` 文件的 `<application>` 节点中，添加 `tools:replace="android:allowBackup"` 和 `android:allowBackup="false"`，用以覆盖组件内的设置。
+``` xml
+ <application
+    ...
+
+    // 添加如下配置覆盖 依赖的 sdk 中的配置
+    android:allowBackup="false"
+    tools:replace="android:allowBackup">
+```
+
+#### 6. 完成项目同步
+
+在您完成上述步骤后，通常情况下 Android Studio 会自动为您弹出 **Sync Now** 按钮，您需要点击该同步按钮完成项目的同步，若 IDE 没有自动弹出同步按钮，请您手动点击工具栏中的同步按钮进行项目的同步，同步后 IDE 会完成项目的构建配置和索引等工作，您就可以在您的项目中正常使用 TUILiveKit 组件了。
+
+## 完成登录
+
+代码集成完成后，您需要完成登录。这是**使用 TUILiveKit 的关键步骤**，因为只有在登录成功后才能正常使用 TUILiveKit 的各项功能，故请您耐心检查相关参数是否配置正确：
+
+> **说明：**
+>
+> 在示例代码中，直接进行了登录接口的调用。但在实际项目场景下，强烈推荐**您在完成自己的用户身份验证等相关登录操作后，再调用 TUILiveKit 的登录服务**。这样可以避免因过早调用登录服务，导致业务逻辑混乱或数据不一致的问题，同时也能更好地适配您项目中现有的用户管理和权限控制体系。
+>
+
+【Kotlin】
+``` java
+// 1.导入依赖
+import io.trtc.tuikit.atomicxcore.api.CompletionHandler
+import io.trtc.tuikit.atomicxcore.api.login.LoginStore
+
+private const val TAG = "LoginStore"
+
+// 2.调用登录接口，推荐您在自己登录业务完成后再调用 LoginStore 登录
+LoginStore.shared.login(applicationContext,
+  1400000001,      // 请替换为开通服务控制台的 SDKAppID
+  "denny",         // 请替换为您的 UserID
+  "xxxxxxxxxxx",   // 您可以在控制台中计算一个 UserSig 并填在这个位置
+  object : CompletionHandler {
+      override fun onSuccess() {
+          Log.i(TAG, "LoginStore login success")
+      }
+
+      override fun onFailure(code: Int, desc: String) {
+          Log.e(TAG, "LoginStore login failed, $code errorMessage:$desc")
+      }
+  })
+```
+
+**登录接口参数说明**
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| 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` 续签登录态。
+
+【kotlin】
+``` java
+import io.trtc.tuikit.atomicxcore.api.login.LoginListener
+import io.trtc.tuikit.atomicxcore.api.login.LoginStore
+
+class YourLoginService {
+
+    // 实例化监听器
+    private val loginListener = object : LoginListener() {
+        // 用户被踢下线回调
+        override fun onKickedOffline() {
+            // 您的业务代码：UI 交互提示用户，然后重新登录
+        }
+
+        // 用户签名过期回调
+        override fun onLoginExpired() {
+            // 您的业务代码：如果当前用户在您后台的登录态依然有效，您可以让您的 app 向您的后台请求新的 userSig，
+            // 并调用 LoginStore.shared.login 续签登录态。
+        }
+    }
+
+    // 监听登录状态回调
+    fun subscribeLoginStatus() {
+        LoginStore.shared.addLoginListener(loginListener)
+    }
+
+    // 取消监听登录状态回调
+    fun unsubscribeLoginStatus() {
+        LoginStore.shared.removeLoginListener(loginListener)
+    }
+}
+```
+
+## 下一步
+
+恭喜您，现在您已经成功集成了**直播**组件并完成了登录。接下来，您可以根据您的业务场景实现**主播开播**、**观众观看**、**直播列表**等功能。
+| <strong>业务场景</strong> | <strong>描述</strong> | <strong>集成指引</strong> |
+| --- | --- | --- |
+| <strong>视频直播</strong> | 包含主播开播、观众观看、连麦互动、美颜设置、礼物弹幕等全套功能。 | - 主播开播<br>- 观众观看 |
+| <strong>语聊房</strong> | 包含麦位管理、背景音乐、礼物互动、语聊控场等完整业务逻辑。 | - 主播开播<br>- 观众观看 |
+| <strong>直播列表</strong> | 展示直播间/语聊房列表，支持封面、人数、房间标题等信息展示。 | - 直播列表 |
+
+## 常见问题
+
+### 每次进房都需要调用登录吗？
+
+不需要。通常您只需要完成一次 `TUILogin.login` 调用即可，我们建议您将 `TUILogin.login` 和 `TUILogin.logout` 与自己的登录业务关联。
+
+### 集成代码后产生如下图所示编译报错 allowBackup 异常，如何处理？
+
+- **问题原因**：多个模块的 `AndroidManifest.xml` 中都配置了 `allowBackup` 属性，造成冲突。
+
+- **解决方法**：您可以在您工程的 `AndroidManifest.xml` 文件中删除 `allowBackup` 属性或将该属性改为 `false`，表示关闭备份和恢复功能；并在 `AndroidManifest.xml` 文件的 application 节点中添加 `tools:replace="android:allowBackup"` 表示覆盖其他模块的设置，使用您自己的设置。修复示例如图所示：
+
+### 集成代码后还需要添加摄像头麦克风等权限的声明吗？
+
+不需要，TUILiveKit 中已经内置了摄像头麦克风等权限的声明，在接入过程中您无需再关心这些权限的声明。

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

@@ -0,0 +1,207 @@
+TUILiveKit 的观众观看页为用户提供了丰富且便捷的直播观看与互动功能，能快速集成到您的应用中，满足观众多样化的需求。
+
+> **集成提示：**
+>
+> 本文档介绍基于 **UI 组件** 的观众观看方式（含完整交互 UI）。若您需通过 **Core SDK** 自行搭建观众端界面，请参考 观众观看 (Core SDK)。
+>
+
+## 功能概览
+- **直播观看：**清晰、流畅观看主播实时直播画面。
+
+- **互动连麦：**申请连麦，与主播进行音视频互动。
+
+- **直播信息：**查看直播间标题、简介，及在线观众列表等信息。
+
+- **直播互动：**送礼物（有动画特效，主播接收提示）、点赞（有动画及实时统计）、发弹幕互动。
+
+| 直播观看 | 互动连麦 | 直播信息 | 直播互动 |
+| --- | --- | --- | --- |
+|  | ### |  |  |
+
+## 快速接入
+
+### 步骤1：开通服务
+
+参考 开通服务 文档开通「体验版」或「大规模直播版」套餐。
+
+### 步骤2：代码集成
+
+参考 准备工作 接入 TUILiveKit。
+
+### 步骤3：添加观众拉流页面
+
+在您的观众视图控制器中 `YourAudienceViewController` 初始化添加 `AudienceView` 观众拉流视图：
+
+【Swift】
+``` swift
+import UIKit
+import SnapKit
+import TUILiveKit
+
+// YourAudienceViewController 代表您观众观看页的视图控制器
+class YourAudienceViewController: UIViewController {
+
+    // 1.  声明 audienceView 作为成员变量
+    private let audienceView: AudienceView
+
+     // 2. 新增便利构造函数：
+     //       - roomId: 直播房间id
+    public init(roomId: String) {
+        // 3. 初始化 AudienceView 组件
+        self.audienceView = AudienceView(roomId: roomId)
+        super.init(nibName: nil, bundle: nil)
+    }
+
+    @available(*, unavailable)
+    required init?(coder: NSCoder) {
+        fatalError("init(coder:) has not been implemented")
+    }
+
+    public override func viewDidLoad() {
+        super.viewDidLoad()
+        // 4. 将 audienceView 添加到视图上
+        view.addSubview(audienceView)
+        audienceView.snp.makeConstraints { make in
+            make.edges.equalToSuperview()
+        }
+    }
+}
+```
+
+### 步骤4：事件回调与数据源定制
+
+除了 UI 样式定制外，`AudienceView` 还提供了以下三个可选扩展点，帮助您接入自定义的直播列表数据源、监听观众页生命周期事件、以及处理屏幕旋转：
+
+|扩展点|类型|说明|
+|---------|---------|---------|
+|`delegate`|`AudienceViewDelegate`|监听观众页内的核心事件，包括直播视图的创建/展示/隐藏、点击悬浮窗、直播结束等回调。|
+|`dataSource`|`AudienceViewDataSource`|自定义直播列表的拉取逻辑。若不设置，`AudienceView` 默认从 TUILiveKit 内置的直播列表拉取数据；设置后，观众滑动切换直播间时将改为调用您自己的直播间列表接口。|
+|`rotateScreenDelegate`|`RotateScreenDelegate`|监听观众页横竖屏切换事件，用于同步您业务侧的 UI 布局。|
+
+``` swift
+import UIKit
+import SnapKit
+import TUILiveKit
+import AtomicXCore
+
+class YourAudienceViewController: UIViewController {
+
+    private let audienceView: AudienceView
+
+    public init(roomId: String) {
+        self.audienceView = AudienceView(roomId: roomId)
+        super.init(nibName: nil, bundle: nil)
+        // 设置回调与数据源
+        audienceView.delegate = self
+        audienceView.dataSource = self
+        audienceView.rotateScreenDelegate = self
+    }
+
+    @available(*, unavailable)
+    required init?(coder: NSCoder) {
+        fatalError("init(coder:) has not been implemented")
+    }
+
+    public override func viewDidLoad() {
+        super.viewDidLoad()
+        view.addSubview(audienceView)
+        audienceView.snp.makeConstraints { make in
+            make.edges.equalToSuperview()
+        }
+    }
+}
+
+// MARK: - AudienceViewDelegate
+extension YourAudienceViewController: AudienceViewDelegate {
+    // 创建了某个直播间对应的播放视图 liveView 时回调，可在此处叠加自定义 UI
+    func audienceView(_ audienceView: AudienceView, onCreateLiveView liveView: AudienceLiveView, for liveInfo: LiveInfo) {
+    }
+
+    // 观众滑动切换到某个直播间，其播放视图 liveView 已展示到屏幕上
+    func audienceView(_ audienceView: AudienceView, liveViewDidAppear liveView: AudienceLiveView, for liveInfo: LiveInfo) {
+    }
+
+    // 观众已滑离某个直播间，其播放视图 liveView 已从屏幕上移除
+    func audienceView(_ audienceView: AudienceView, liveViewDidDisappear liveView: AudienceLiveView, for liveInfo: LiveInfo) {
+
+    }
+
+    // 用户点击了悬浮窗
+    func onClickFloatWindow() {
+     FloatWindow.shared.showFloatWindow(controller: self, provider: audienceView)
+    }
+
+    // 直播已结束（主播下播/房间被解散等）
+    func onLiveEnded(roomId: String, ownerName: String, ownerAvatarUrl: String) {
+    // 展示直播结束的结算页（含主播头像/昵称、"直播已结束"提示等）
+       let endView = AudienceEndStatisticsView(roomId: roomId, avatarUrl: ownerAvatarUrl, userName: ownerName)
+       endView.delegate = self
+       view.addSubview(endView)
+       endView.snp.makeConstraints { make in
+         make.edges.equalToSuperview()
+       }
+    }
+}
+
+// MARK: - RotateScreenDelegate
+extension YourAudienceViewController: RotateScreenDelegate {
+    // isPortrait: true 表示当前为竖屏，false 表示当前为横屏
+    func rotateScreen(isPortrait: Bool) {
+    }
+}
+```
+
+### 步骤5：导航路由到观众拉流页面
+
+通常在 直播列表 或者 **点击主播开播推送通知** 时，您需要导航跳转到观众观看页，可参考如下代码示例：
+
+【Swift】
+``` swift
+// 1. 实例化您的观众观看视图控制器
+let audienceVC = YourAudienceViewController(roomId: "您的直播房间 id")
+audienceVC.modalPresentationStyle = .fullScreen
+// 2. 跳转到您的观众观看视图控制器
+present(audienceVC, animated: false)
+```
+
+## 自定义您的界面布局
+
+### 自定义观众观看页界面
+- 参考 观众核心页面 进行观众界面定制，在 `AudienceView` 中修改 UI 样式，添加您的业务组件。
+
+- 参考 调整视频直播挂件 进行视频位挂件定制，在 `AudienceView` 中修改视频位上的名称、头像挂件等 UI。
+
+### 文案定制
+
+TUILiveKit 使用更为方便的 [Apple Strings Catalog](https://developer.apple.com/documentation/xcode/localizing-and-varying-text-with-a-string-catalog) 工具来管理 UI 所需的文案显示，您可以很直观的通过 Xcode 视图化管理工具修改需要调整的文案：
+
+> **说明：**
+>
+> [Apple Strings Catalog](https://developer.apple.com/documentation/xcode/localizing-and-varying-text-with-a-string-catalog) (.xcstrings) 是在 Xcode 15 中引入的本地化格式。它增强了开发者管理本地化字符串的方式，支持处理复数、设备特定变体等的结构化格式。这种格式正成为管理 iOS 和 macOS 应用程序本地化的推荐方法。
+>
+
+### 图标定制
+
+TUILiveKit 使用 `TUILiveKit.xcassets` 管理 UI 所需的图片资源，您可以借助 Xcode 图形化工具快速修改自定义界面所需的图标。
+
+## 下一步
+
+恭喜您，现在您已经成功集成了观众观看。接下来，您可以实现**主播开播**、**直播列表**等功能，可参考下表：
+| <strong>功能</strong> | <strong>描述</strong> | <strong>集成指引</strong> |
+| --- | --- | --- |
+| <strong>主播开播</strong> | 主播开播全流程功能，包括开播前的准备和开播后的各种互动 | 主播开播 |
+| <strong>直播列表</strong> | 展示直播列表界面和功能，包含直播列表，房间信息展示功能 | 直播列表 |
+| <strong>礼物系统</strong> | 实现自定义礼物素材配置、计费系统对接、PK 场景互动等功能 | 礼物系统 |
+
+## 常见问题
+
+### 观众选择视频连麦后，视频画面显示黑屏？
+
+请前往**手机设置** > **App >** **相机**，检查摄像头权限是否开启，可参考下图：
+
+### 观众发送弹幕时，直播间内其他观众看不到弹幕内容？
+- 原因1：先检查网络连接，确保观众设备网络正常。
+
+- 原因2：该观众被主播禁言，无法发送弹幕。
+
+- 原因3：观众的弹幕内容涉及关键词屏蔽，请确认观众发送的弹幕内容是否符合直播间规则。