@tencentcloud/sdk-mcp 1.6.4 → 1.6.5

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：观众的弹幕内容涉及关键词屏蔽，请确认观众发送的弹幕内容是否符合直播间规则。

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

@@ -0,0 +1,358 @@
+TUILiveKit 主播开播页为直播场景提供**开箱即用的全功能界面**，支持快速搭建主播开播所需的核心能力，让您无需关注复杂 UI 与逻辑实现，即可高效集成直播开播流程。
+
+> **集成提示：**
+>
+> 本文档介绍基于 **UI 组件** 的开播方式（含完整交互 UI）。若您需通过 **Core SDK** 自行搭建主播端界面，请参考 主播开播 (Core SDK)。
+>
+
+## 功能概览
+- **开播前预览：**支持主播开播前的房间名称、背景、视频预览、美颜调试、音效调试、布局模板等多种个性化配置。
+
+- **连麦互动：**支持直播过程中与观众 或 与其他直播间主播实时互动。
+
+- **观众互动：**支持弹幕、礼物等丰富直播互动形式。
+
+- **直播间管理：**支持在线用户列表展示、以及直播间内的禁言、踢人等多种管理操作。
+
+| 开播前预览 | 连麦互动 | 观众互动 | 直播间管理 |
+| --- | --- | --- | --- |
+|  |  |  |  |
+
+## 快速接入
+
+### 步骤1：开通服务
+
+参考 开通服务 文档开通「体验版」或「大规模直播版」套餐。
+
+### 步骤2：代码集成
+
+参考 准备工作 接入 `TUILiveKit`。
+
+### 步骤3：添加开播前的准备页面
+
+`AnchorPrepareView` 组件已内置了摄像头预览、音效设置、布局设置、以及其它功能设置，您需创建并加载主播开播页视图，具体示例代码如下：
+
+【Swift】
+``` swift
+import UIKit
+import Snapkit
+import TUILiveKit
+import AtomicXCore
+
+// YourAnchorPrepareViewController 代表您加载主播开播页的视图控制器
+class YourAnchorPrepareViewController: UIViewController {
+    private let roomId = "testLiveId"
+
+    // 懒加载 AnchorPrepareView
+    private lazy var prepareView: AnchorPrepareView = {
+        // AnchorPrepareView 初始化时传入roomId
+        let view = AnchorPrepareView(roomId: roomId)
+        return view
+    }()
+
+    public override func viewDidLoad() {
+        super.viewDidLoad()
+        // 将 prepareView 添加到视图上
+        view.addSubview(prepareView)
+        prepareView.snp.makeConstraints { make in
+            make.edges.equalToSuperview()
+        }
+    }
+}
+```
+
+### 步骤4：添加主播用的推流页面
+
+`AnchorView` 组件已内置了音视频推流、观众连麦、直播互动、直播管理等功能，您只需创建并加载 `AnchorView` ，具体示例代码如下：
+
+【swift】
+``` swift
+import UIKit
+import Snapkit
+import TUILiveKit
+import AtomicXCore
+
+// YourAnchorPrepareViewController 代表您加载主播开播页的视图控制器
+class YourAnchorViewController: UIViewController {
+    // 核心 view 组件
+    private let coreView: LiveCoreView
+
+    // 声明 anchorView 实例
+    private let anchorView: AnchorView
+
+    public init(liveInfo: LiveInfo, coreView: LiveCoreView? = nil, behavior: RoomBehavior = .createRoom) {
+        if let coreView = coreView {
+            self.coreView = coreView
+        } else {
+            self.coreView = LiveCoreView(viewType: .pushView)
+        }
+        // 实例化主播开播页
+        self.anchorView = AnchorView(liveInfo: liveInfo, coreView: self.coreView, behavior: behavior)
+        super.init(nibName: nil, bundle: nil)
+    }
+
+    required init?(coder: NSCoder) {
+        fatalError("init(coder:) has not been implemented")
+    }
+
+    public override func viewDidLoad() {
+        super.viewDidLoad()
+        // 将 anchorView 添加到视图上
+        view.addSubview(anchorView)
+        anchorView.snp.makeConstraints { make in
+            make.edges.equalToSuperview()
+        }
+    }
+}
+```
+
+### 步骤5：事件回调定制
+
+`AnchorView` 还提供了 `delegate`（`AnchorViewDelegate`）扩展点，用于监听主播开播页内的核心生命周期事件，包括真正开播成功、下播（含统计数据）、点击悬浮窗等回调，建议在 步骤 4 创建 `AnchorView` 后立即设置：
+
+|方法|说明|
+|---------|---------|
+|`func onStartLiving()`|主播已成功开始直播（房间创建/进入成功，推流已开始）时回调。|
+|`func onEndLiving(state: AnchorState)`|主播下播时回调，`state` 携带本场直播的统计数据：`totalDuration`（直播时长）、`totalViewers`（观众总数）、`totalMessageSent`（弹幕总数）、`totalGiftCoins`（礼物总收益）、`totalGiftUniqueSenders`（送礼人数）、`totalLikesReceived`（点赞总数）、`liveEndedReason`（下播原因），可用于展示下播结算页。|
+|`func onClickFloatWindow()`|用户点击悬浮窗回调。|
+
+``` swift
+import UIKit
+import Snapkit
+import TUILiveKit
+import AtomicXCore
+
+// YourAnchorPrepareViewController 代表您加载主播开播页的视图控制器
+class YourAnchorViewController: UIViewController {
+    // 核心 view 组件
+    private let coreView: LiveCoreView
+
+    // 声明 anchorView 实例
+    private let anchorView: AnchorView
+
+    public init(liveInfo: LiveInfo, coreView: LiveCoreView? = nil, behavior: RoomBehavior = .createRoom) {
+        if let coreView = coreView {
+            self.coreView = coreView
+        } else {
+            self.coreView = LiveCoreView(viewType: .pushView)
+        }
+        // 实例化主播开播页
+        self.anchorView = AnchorView(liveInfo: liveInfo, coreView: self.coreView, behavior: behavior)
+        super.init(nibName: nil, bundle: nil)
+        // 设置代理，监听主播页核心事件
+        anchorView.delegate = self
+    }
+
+    required init?(coder: NSCoder) {
+        fatalError("init(coder:) has not been implemented")
+    }
+
+    public override func viewDidLoad() {
+        super.viewDidLoad()
+        // 将 anchorView 添加到视图上
+        view.addSubview(anchorView)
+        anchorView.snp.makeConstraints { make in
+            make.edges.equalToSuperview()
+        }
+    }
+}
+
+// 实现 AnchorViewDelegate 回调代理
+extension YourAnchorViewController: AnchorViewDelegate {
+    // 主播已成功开始直播（推流已开始）
+    func onStartLiving() {
+    }
+
+    // 主播下播，state 携带本场直播的统计数据
+    func onEndLiving(state: AnchorState) {
+        let duration = state.totalDuration
+        let viewers = state.totalViewers
+        let messageCount = state.totalMessageSent
+        let giftCoins = state.totalGiftCoins
+        let giftSenders = state.totalGiftUniqueSenders
+        let likes = state.totalLikesReceived
+        let reason = state.liveEndedReason
+        // 可在此处跳转到您的下播结算页，展示以上统计数据
+    }
+
+    // 用户点击了悬浮窗
+    func onClickFloatWindow() {
+    }
+}
+
+// 实现 FloatWindowProvider 回调代理
+extension YourAnchorViewController: FloatWindowProvider {
+    public func getRoomId() -> String {
+        liveID
+    }
+
+    public func getOwnerId() -> String {
+        LiveListStore.shared.state.value.currentLive.liveOwner.userID
+    }
+
+    public func getCoreView() -> AtomicXCore.LiveCoreView {
+        coreView
+    }
+
+    public func relayoutCoreView() {
+        anchorView.relayoutCoreView()
+    }
+
+    public func getIsLinking() -> Bool {
+        let connectedSeats = CoGuestStore.create(liveID: liveID).state.value.connected
+        let selfUserID = LoginStore.shared.state.value.loginUserInfo?.userID ?? ""
+        return connectedSeats.contains(where: { $0.userID == selfUserID })
+    }
+}
+
+```
+
+### **步骤6：从准备页面跳转到推流页面**
+
+结合 步骤 3 实现 `AnchorPrepareView` 组件的代理事件，完成主播开播页的路由跳转，具体示例代码如下：
+
+> **配合服务端 (RESTFUL API) 开播：**
+>
+> 如果您的房间是先通过 服务端 API 创建的，在集成时无需修改任何代码逻辑，只需将示例代码中的 `liveID` 替换为服务端生成的 ID 即可。SDK 将自动接管该房间并开启直播。
+>
+
+【swift】
+``` swift
+import UIKit
+import TUILiveKit
+import AtomicXCore
+
+// 在 AnchorPrepareView 初始化时设置代理
+class YourAnchorPrepareViewController: UIViewController {
+    private lazy var prepareView: AnchorPrepareView = {
+        let view = AnchorPrepareView(roomId: roomId)
+        // 设置代理
+        view.delegate = self
+        return view
+    }()
+}
+
+// 实现 AnchorPrepareViewDelegate 回调代理
+extension YourAnchorPrepareViewController : AnchorPrepareViewDelegate {
+    // 响应开播按钮点击事件
+    //   - state: PrepareState 封装了主播开播页的摄像头、音效等功能设置，您只需按以下示例代码设置即可
+    public func onClickStartButton(state: PrepareState) {
+        // 跳转到主播开播页
+        // 初始化直播信息
+        var liveInfo = LiveInfo(seatTemplate: .videoDynamicGrid9Seats)
+        // 如果您使用了服务端 API 预创房，请在此处填入服务端返回的 RoomId。
+        liveInfo.liveID = roomId
+        liveInfo.liveName = state.roomName
+        liveInfo.coverURL = state.coverUrl
+        liveInfo.isPublicVisible = state.privacyMode == .public
+        liveInfo.backgroundURL = state.coverUrl
+
+        // 实例化您的直播开播视图控制器
+        let anchorVC = YourAnchorViewController(liveInfo: liveInfo, coreView: prepareView.getCoreView())
+        anchorVC.modalPresentationStyle = .fullScreen
+        // 跳转到您的直播开播视图控制器
+        present(anchorVC, animated: false)
+    }
+
+    // 响应返回按钮点击事件
+    public func onClickBackButton() {
+        if let nav = navigationController {
+            nav.popViewController(animated: true)
+        } else {
+            dismiss(animated: true)
+        }
+    }
+}
+```
+
+###
+
+## 自定义您的界面布局
+
+`TUILiveKit` 支持灵活定制开播页与直播页的功能和样式，您可根据业务需求调整布局、隐藏 / 显示功能模块。
+
+### 直播布局模板选择
+
+`TUILiveKit` 提供 **4 种直播布局模板**，您可在主播开播页的 **UI 交互「布局」入口** 选择合适样式：
+
+#### 布局模板一览：
+| <strong>布局</strong> | <strong>动态宫格布局</strong> | <strong>浮动小窗布局</strong> | <strong>固定宫格布局</strong> | <strong>固定小窗布局</strong> |
+| --- | --- | --- | --- | --- |
+| <strong>模板取值</strong> | <code>.videoDynamicGrid9Seats</code> | <code>.videoDynamicFloat7Seats</code> | <code>.videoFixedGrid9Seats</code> | <code>.videoFixedFloat7Seats</code> |
+| <strong>描述</strong> | 默认布局，可根据连麦人数动态调整宫格大小。 | 连麦嘉宾以浮动小窗形式显示。 | 连麦人数固定，每个嘉宾占据一个固定宫格。 | 连麦人数固定，嘉宾以固定小窗形式显示。 |
+| <strong>预览</strong> |  |  |  |  |
+
+### 自定义开播页功能区
+
+通过调用 步骤 3 创建的 `prepareView` 的 API，可自定义隐藏开播准备页的操作区或特定功能：
+
+【swift】
+``` swift
+import UIKit
+import Snapkit
+import TUILiveKit
+import AtomicXCore
+
+// YourAnchorPrepareViewController 代表您加载主播开播页的视图控制器
+class YourAnchorPrepareViewController: UIViewController {
+    private let roomId = "testLiveId"
+    private lazy var prepareView: AnchorPrepareView = {
+        let view = AnchorPrepareView(roomId: roomId)
+        view.delegate = self
+        return view
+    }()
+
+    public override func viewDidLoad() {
+        super.viewDidLoad()
+        // 1. 将 prepareView 添加到视图上
+        view.addSubview(prepareView)
+        prepareView.snp.makeConstraints { make in
+            make.edges.equalToSuperview()
+        }
+        // 2. 自定义功能区 - 示例：隐藏美颜功能
+        prepareView.disableMenuBeauty(true)
+    }
+}
+```
+
+|隐藏整个功能区|隐藏美颜按钮|隐藏音效按钮|隐藏摄像头切换按钮|
+|---------|---------|---------|---------|
+|`disableFeatureMenu(true)`|`disableMenuBeauty(true)`|`disableMenuAudioEffect(true)`|`disableMenuSwitchCamera(true)`|
+|||||
+
+### 自定义主播直播页界面
+- 参考 主播核心页面 进行主播界面定制，在 `AnchorView` 中修改 UI 样式，添加您的业务组件。
+
+- 参考 调整视频直播挂件 进行视频位挂件定制，在 `AnchorView` 中修改视频位上的名称、头像挂件等 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** > **相机**，检查摄像头权限是否开启，可参考下图：
+
+### 点击开播按钮无法开播，提示“未登录”？
+
+参考 登录指引， 确认已完成登录功能接入。