@tencentcloud/sdk-mcp 1.7.1 → 1.7.3

package/resource/knowledge/roomkit/preset/harmonyos/integration.md

@@ -0,0 +1,461 @@
+TUIRoomKit 是腾讯云提供的一站式多人音视频房间解决方案，集成了完整的 UI 组件和核心功能。通过本文档，开发者可以快速了解如何将 TUIRoomKit 集成到项目中，实现多人音视频房间功能。本文还将详细介绍如何快速替换图片资源、本地化文案等个性化配置，帮助开发者打造符合品牌特色的音视频应用。
+
+## 前提条件
+
+### 开通服务
+
+请参考 开通服务 领取 TUIRoomKit 体验版，并在 [应用管理](https://console.cloud.tencent.com/trtc) 页面获取以下信息：
+- **SDKAppID**：应用标识（必填），腾讯云基于 SDKAppID 完成计费统计。
+
+- **SDKSecretKey**：应用密钥，用于初始化配置文件的密钥信息。
+
+### 环境准备
+- 集成开发环境：6.0.0.858 或以上。
+
+- 手机操作系统：HarmonyOS 5.0.5 或以上。
+
+- API Version：17 或以上。
+
+## 快速接入
+
+### 步骤1：集成 TUIRoomKit 组件
+
+#### 下载源码
+
+从 GitHub 下载 [TUIKit Harmony](https://github.com/Tencent-RTC/TUIKit_Harmony) 源码：
+``` bash
+git clone https://github.com/Tencent-RTC/TUIKit_Harmony.git
+```
+
+#### 集成组件
+
+2. 在您的工程 `entry` 的 `oh-package.json5` 文件中，添加以下插件依赖。
+
+   ``` json
+   "dependencies": {
+       "@tencentcloud/atomicxcore": "^4.1.0",
+       "@tencentcloud/atomicx": "file:../../../atomic_x",
+       "@tencentcloud/tuiroomkit": "file:../../../room",
+   }
+   ```
+
+   > **说明：**
+   >
+   > room 和 atomic_x 可以放在任何位置，只要在 oh-package.json5 中正确设置相对路径即可。
+   >
+
+3. **oh-package.json5** 修改完毕后，执行以下命令，安装本地 TUIKit 组件。示例：
+
+   ``` bash
+   ohpm install
+   ```
+
+   ohpm install 会自动安装所需的依赖库。
+
+   > **注意：**
+   >
+   > - 使用本地集成方案时，如需升级时需要从 GitHub 获取最新的组件代码，覆盖您本地项目的 atomic_x 目录。
+   > - 当私有化修改和远端有冲突时，需要手动合并，处理冲突。
+
+### 步骤2：工程配置
+1. 权限配置：您需要在您工程 entry 的 module.json5 的 module 模块中，声明以下所需要的权限：
+
+   ``` json
+   "requestPermissions":[
+     {
+       "name" : "ohos.permission.INTERNET"
+     },
+     {
+       "name" : "ohos.permission.USE_BLUETOOTH"
+     },
+     {
+       "name" : "ohos.permission.GET_BUNDLE_INFO"
+     },
+     {
+       "name" : "ohos.permission.GET_NETWORK_INFO"
+     },
+     {
+       "name" : "ohos.permission.GET_WIFI_INFO"
+     },
+     {
+       "name" : "ohos.permission.MODIFY_AUDIO_SETTINGS"
+     },
+     {
+       "name" : "ohos.permission.MICROPHONE",
+       "reason": "$string:module_desc",
+       "usedScene": { "abilities": [ "EntryAbility" ], "when":"always" }
+     },
+     {
+       "name" : "ohos.permission.CAMERA",
+       "reason": "$string:module_desc",
+       "usedScene": { "abilities": [ "EntryAbility" ], "when":"always" }
+     },
+     {
+       "name" : "ohos.permission.KEEP_BACKGROUND_RUNNING"
+     },
+   ]
+   ```
+2. 模块声明：已有项目集成源码后，需在 build-profile.json5 文件声明模块：
+
+   ``` bash
+    "modules": [
+       {
+         "name": "entry",
+         "srcPath": "./entry",
+         "targets": [
+           {
+             "name": "default",
+             "applyToProducts": [
+               "default"
+             ]
+           }
+         ]
+       },
+       {
+         "name": "tuiroomkit",
+         "srcPath": "../room",  // 根据实际目录调整
+         "targets": [
+           {
+             "name": "default",
+             "applyToProducts": [
+               "default"
+             ]
+           }
+         ]
+       },
+       {
+         "name": "atomic_x",
+         "srcPath": "../atomic_x",  // 根据实际目录调整
+         "targets": [
+           {
+             "name": "default",
+             "applyToProducts": [
+               "default"
+             ]
+           }
+         ]
+       }
+     ]
+   ```
+3. 声明 backgroundModes。在承载会议界面的 UIAbility（通常是 EntryAbility）下，给 module.json5 的 abilities 节点添加 backgroundModes：
+
+   ``` java
+   "abilities": [
+     {
+       "name": "EntryAbility",
+       // ... 其他配置保持不变
+       "backgroundModes": [
+         "audioRecording",
+         "audioPlayback"
+       ]
+     }
+   ]
+   ```
+
+### 步骤3：登录
+
+代码集成完成后，需要完成登录操作，这是**使用 TUIRoomKit 的关键步骤**。只有在登录成功后，才能正常使用 TUIRoomKit 的各项功能，因此请仔细检查相关参数配置是否正确：
+
+> **说明：**
+> 在示例代码中，直接进行了登录接口的调用。但在实际项目场景下，强烈推荐**您在完成自己的用户身份验证等相关登录操作后，再调用 TUIRoomKit 的登录服务**。这样可以避免因过早调用登录服务，导致业务逻辑混乱或数据不一致的问题，同时也能更好地适配您项目中现有的用户管理和权限控制体系。
+>
+
+【ArkTS】
+``` typescript
+import { LoginStore } from '@tencentcloud/atomicxcore'
+
+try {
+  await LoginStore.shared().login(
+    1400000000,     // 替换为您的 SDKAPPID
+    'userID',       // 替换为您的 UserID
+    'userSig',      // 替换为您的 UserSig
+  );
+  // login success
+} catch (error) {
+  // login error
+}
+```
+
+**登录接口参数说明：**
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| <code>sdkAppID</code> | <code>number</code> | 从 <a href="https://console.cloud.tencent.com/trtc">控制台</a> 获取，通常是以 <code>140</code> 或 <code>160</code> 开头的 10 位整数。 |
+| <code>userID</code> | <code>string</code> | 当前用户的唯一 ID，仅包含英文字母、数字、连字符和下划线。为避免多端登录冲突，<strong>请勿使用</strong> <code>1</code>、<code>123</code> <strong>等简单 ID</strong>。 |
+| <code>userSig</code> | <code>string</code> | 用于腾讯云鉴权的票据。更多信息请参见 如何计算及使用 UserSig。<br>【注意事项】<br>- 开发环境：可以采用本地 <code>GenerateTestUserSig.genTestSig</code> 函数生成 userSig 或者通过 <a href="https://console.cloud.tencent.com/im/tool-usersig">UserSig 辅助工具</a> 生成临时的 userSig。<br>- 生产环境：为了防止密钥泄露，请务必采用服务端生成 userSig 的方式。详细信息请参考 服务端生成 UserSig。 |
+
+### 步骤4：设置头像和昵称
+
+首次登录的用户没有头像和昵称信息，需要通过 `LoginStore` 的 `setSelfInfo` 接口设置个人信息：
+``` typescript
+import { LoginStore, UserProfile, ErrorInfo } from '@tencentcloud/atomicxcore';
+
+try {
+  await LoginStore.shared().setSelfInfo(new UserProfile('userID', 'userName', 'avatarURL'));
+  console.info("setSelfInfo success");
+} catch (error) {
+  const err = error as ErrorInfo;
+  console.error(`setSelfInfo failed [code: ${err.code}] ${err.message}`);
+}
+```
+
+**setSelfInfo 接口参数/返回值说明：**
+| 参数/返回值 | 类型 | 说明 |
+| --- | --- | --- |
+| <code>userProfile</code> | <code>UserProfile</code> | 个人用户信息核心模型，包含：<br>- userID：要设置用户信息的用户 ID。<br>- nickname：昵称信息。<br>- avatarURL：头像链接。 |
+
+### 步骤5：创建房间
+
+在 `TUIRoomKit` 组件中，`RoomMainPage` 是集成了完整的多人音视频房间功能的核心界面，以下将向开发者演示如何以房主身份将 `RoomMainPage` 嵌入到应用中。
+
+#### **实现方式：**
+1. **构造进房的配置项**：进入房间后是否需要自动打开音视频设备的配置项。
+
+2. **配置房间创建选项**：配置房间名称等信息。
+
+3. **初始化房间主页面**：通过房主身份初始化房间主页面。
+
+4. **导航到房间页面**：将 `RoomMainPage` 推入导航栈。
+
+   > **说明：**
+   >
+   > Harmony 目前仅支持创建标准房间，如您需要创建大型研讨会房间，请参考 Web 快速接入 使用 Web 端创建。
+   >
+
+#### **示例代码：**
+``` typescript
+import {
+  RoomMainPage,
+  RoomBehavior,
+  ConnectConfig,
+  EnterRoomParams,
+} from '@tencentcloud/tuiroomkit';
+import { CreateRoomOptions } from '@tencentcloud/atomicxcore';
+
+@Entry
+@Component
+struct YourMainPage {
+  private navStack: NavPathStack = new NavPathStack();
+
+  build() {
+    Navigation(this.navStack) {
+      Column() {
+        Button('创建房间')
+          .onClick(() => this.createRoom())
+      }
+      .width('100%')
+      .height('100%')
+      .justifyContent(FlexAlign.Center)
+    }
+    .navDestination(this.routerMap)
+    .hideTitleBar(true)
+  }
+
+  private createRoom(): void {
+    // 1. 构造进房的配置项
+    const config = new ConnectConfig(
+      true,   // autoEnableMicrophone: 进房后是否自动开启麦克风
+      true,   // autoEnableCamera:     进房后是否自动开启摄像头
+      true,   // autoEnableSpeaker:    进房后是否自动开启扬声器
+    );
+
+    // 2. 配置房间创建选项
+    const options = new CreateRoomOptions();
+    options.roomName = 'roomName';  // 房间名称
+
+    // 3. 配置进房行为（创建房间）
+    const behavior = RoomBehavior.create(options);
+
+    // 4. 导航到房间页面
+    const params = new EnterRoomParams('123456', behavior, config);
+    this.navStack.pushPath({ name: 'RoomMain', param: params });
+  }
+
+  @Builder
+  routerMap(name: string, param: Object) {
+    if (name === 'RoomMain') {
+      RoomMainDestination({ navStack: this.navStack, params: param as EnterRoomParams })
+    }
+  }
+}
+
+@Component
+struct RoomMainDestination {
+  navStack: NavPathStack = new NavPathStack();
+  params?: EnterRoomParams;
+
+  build() {
+    NavDestination() {
+      RoomMainPage({
+        roomID: this.params?.roomID ?? '',
+        behavior: this.params?.behavior ?? RoomBehavior.join(),
+        config: this.params?.config ?? new ConnectConfig(),
+        onExit: () => {
+          this.navStack.pop();
+        },
+      })
+    }
+    .hideTitleBar(true)
+    .width('100%')
+    .height('100%')
+    .onBackPressed(() => true)
+  }
+}
+```
+
+**RoomMainPage 构造函数参数详细说明：**
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| <code>roomID</code> | <code>string</code> | - 字符串类型的房间唯一标识符。<br>- 限制长度为 0-48 字节。<br>- 建议仅包含数字、英文字母（区分大小写）、下划线（_）和连字符（-）。避免使用空格和中文字符。 |
+| <code>behavior</code> | <code>RoomBehavior</code> | - 房间主页面初始化来源。<br>- 参数含义：<br>- create: 房主身份创建房间，此方式需要构造创建房间配置项 CreateRoomOptions。<br>- join：参与者身份加入房间。 |
+| <code>config</code> | <code>ConnectConfig</code> | 进房后音视频设备控制的配置项。 |
+
+**ConnectConfig 参数详细说明：**
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| autoEnableMicrophone | <code>boolean</code> | - 进房后是否自动开启麦克风。<br>- 参数含义：<br>- true: 自动开启 （默认值）。<br>- false: 不自动开启。 |
+| autoEnableCamera | <code>boolean</code> | - 进房后是否自动开启摄像头。<br>- 参数含义：<br>- true: 自动开启 （默认值）。<br>- false: 不自动开启。 |
+| autoEnableSpeaker | <code>boolean</code> | - 进房后是否自动开启扬声器。<br>- 参数含义：<br>- true: 自动开启 （默认值）。<br>- false: 不自动开启。 |
+
+### 步骤6：加入房间
+
+以下示例将向开发者演示如何以参与者身份将 `RoomMainPage` 嵌入到应用中。
+
+#### **实现方式：**
+1. **构造进房的配置项**：进入房间后是否需要自动打开音视频设备的配置项。
+
+2. **初始化房间主页面**：通过参与者身份初始化房间主页面。
+
+3. **导航到房间页面**：将 `RoomMainPage` 推入导航栈。
+
+#### 代码示例：
+``` typescript
+import {
+  RoomMainPage,
+  RoomBehavior,
+  ConnectConfig,
+  EnterRoomParams,
+} from '@tencentcloud/tuiroomkit';
+
+@Entry
+@Component
+struct YourMainPage {
+  private navStack: NavPathStack = new NavPathStack();
+
+  build() {
+    Navigation(this.navStack) {
+      Column() {
+        Button('加入房间')
+          .onClick(() => this.enterRoom())
+      }
+      .width('100%')
+      .height('100%')
+      .justifyContent(FlexAlign.Center)
+    }
+    .navDestination(this.routerMap)
+    .hideTitleBar(true)
+  }
+
+  private enterRoom(): void {
+    // 1. 构造进房的配置项
+    const config = new ConnectConfig(
+      true,   // autoEnableMicrophone: 进房后是否自动开启麦克风
+      true,   // autoEnableCamera:     进房后是否自动开启摄像头
+      true,   // autoEnableSpeaker:    进房后是否自动开启扬声器
+    );
+
+    // 2. 配置进房行为（加入房间）
+    const behavior = RoomBehavior.join();
+
+    // 3. 导航到房间页面
+    const params = new EnterRoomParams('roomID', behavior, config);
+    this.navStack.pushPath({ name: 'RoomMain', param: params });
+  }
+
+  @Builder
+  routerMap(name: string, param: Object) {
+    if (name === 'RoomMain') {
+      RoomMainDestination({ navStack: this.navStack, params: param as EnterRoomParams })
+    }
+  }
+}
+
+@Component
+struct RoomMainDestination {
+  navStack: NavPathStack = new NavPathStack();
+  params?: EnterRoomParams;
+
+  build() {
+    NavDestination() {
+      RoomMainPage({
+        roomID: this.params?.roomID ?? '',
+        behavior: this.params?.behavior ?? RoomBehavior.join(),
+        config: this.params?.config ?? new ConnectConfig(),
+        onExit: () => {
+          this.navStack.pop();
+        },
+      })
+    }
+    .hideTitleBar(true)
+    .width('100%')
+    .height('100%')
+    .onBackPressed(() => true)
+  }
+}
+```
+
+**参数详细说明请参考：**[RoomMainPage 构造函数参数详细说明]( 构造函数参数详细说明) 和 [ConnectConfig 参数详细说明]( 参数详细说明)。
+
+> **说明：**
+> 使用 TUIRoomKit 组件进入大型研讨会房间时，需确保 Web 端创建的研讨会房间的房间 ID 以 `webinar_` 开头。
+>
+
+## 核心功能
+
+接入 `RoomMainPage` 代码后，开发者将得到一个完整的多人音视频页面，内部包含成员管理，音视频设备控制，房间信息展示等功能，这是 `TUIRoomKit` 组件的核心。
+
+## 界面定制
+
+`RoomMainPage` 房间主页面内功能丰富，可定制化度高，开发者可以根据实际产品需求，对 UI 进行定制化修改，以适配业务交互场景。以下将详细为开发者展示 `RoomMainPage` 中视图组件，便于开发者快速修改。
+
+`RoomMainPage` **中组件详细说明**
+
+|组件|功能描述|定制化建议|
+|---------|---------|---------|
+|[RoomMainPage](https://github.com/Tencent-RTC/TUIKit_Harmony/blob/main/room/src/main/ets/pages/RoomMainPage.ets)|房间主视图容器，负责协调各子组件的布局与数据流转。|可调整整体背景、安全区域适配、组件显隐逻辑。|
+|[RoomTopBarView](https://github.com/Tencent-RTC/TUIKit_Harmony/blob/main/room/src/main/ets/pages/main/RoomTopBarView.ets)|顶部导航栏，包含房间信息、摄像头和声音控制、退出房间功能入口。|可替换图标、调整背景透明度、添加自定义按钮（例如录制、 窗口化）。|
+|[RoomView](https://github.com/Tencent-RTC/TUIKit_Harmony/blob/main/room/src/main/ets/pages/main/RoomView.ets)|视频流展示区域，采用瀑布流布局管理多个用户视频画面。|可修改布局算法（行列数、间距）、分页指示器样式、空状态视图。|
+|[ParticipantVideoItemView](https://github.com/Tencent-RTC/TUIKit_Harmony/blob/main/room/src/main/ets/pages/main/room_view/ParticipantVideoItemView.ets)|单个视频流单元格，承载用户视频画面与基本信息。|可自定义视频渲染层、用户信息面板（头像、徽章）、互动控件（语音波形）。|
+|[RoomBottomBarView](https://github.com/Tencent-RTC/TUIKit_Harmony/blob/main/room/src/main/ets/pages/main/RoomBottomBarView.ets)|底部工具栏，集成麦克风、摄像头、成员管理操作按钮。|可重新排列按钮顺序、修改按钮样式（颜色、尺寸）、添加业务相关功能（例如屏幕分享、会中呼叫、美颜）。|
+
+## 图标定制
+
+接入 TUIRoomKit 组件后，开发者可以根据实际 UI 交互需求直接替换组件下的图标资源，以适配开发者的业务场景。
+
+TUIRoomKit 使用 `src/main/resources/base/media` 目录管理 UI 所需的图片资源，您可以直接替换该目录下的图片文件来自定义界面所需的图标。
+
+**常用的图片文件列表**
+
+|图标|文件名|说明|
+|---------|---------|---------|
+||room_camera_off.png|摄像头关闭图标|
+||room_camera_on.png|摄像头开启图标|
+||room_mic_off.png|麦克风关闭图标|
+||room_mic_on_empty.png|麦克风开启图标|
+||room_administrator_icon.png|管理员身份标识图标|
+||room_owner_icon.png|房主身份标识图标|
+
+## 文案定制
+
+TUIRoomKit 使用 HarmonyOS 标准的资源文件来管理 UI 所需的文案显示，您可以直接修改 atomic_x/src/main/resources/ 目录下对应语言文件夹中的 `string.json` 等 JSON 资源文件来调整需要的文案。
+
+## 常见问题
+
+### 每次进房都需要调用登录吗？
+
+不需要。通常您只需要完成一次 `LoginStore.shared.login` 调用即可，我们建议您将 `LoginStore.shared.login` 和
+
+`LoginStore.shared.logout` 与自己的登录业务关联。
+
+### oh-package.json5 文件有没有示例配置可以参考？
+
+您可以参考 GitHub TUIKit_Harmony [application](https://github.com/Tencent-RTC/TUIKit_Harmony/tree/main/application) 工程中的 `oh-package.json5` 示例文件。

package/resource/knowledge/roomkit/preset/react/features/network-proxy.md

@@ -0,0 +1,80 @@
+视频会议 SDK 基于腾讯云即时通信 IM 与实时音视频 TRTC 提供服务，支持在内网 / 防火墙环境下统一配置 IM 与 TRTC 代理，适用于私有化部署、企业内网隔离等无法直连腾讯云服务的场景。
+
+## 代理架构
+
+|代理服务器|代理链路|
+|---------|---------|
+|IM 代理|代理 IM 登录、消息收发等信令通道（WebSocket），以及聊天图片、文件等资源的上传与下载。|
+|TRTC WebSocket 代理（如 Nginx）|代理 TRTC 进房、控制等信令通道（WebSocket），负责房间管理与用户状态同步。|
+|TRTC TURN Server|中继转发 TRTC 音视频媒体流。|
+
+> **说明：**
+> 代理服务器（IM 代理、Nginx、TURN）需自行部署，搭建方式参见 [TRTC Web SDK 应对防火墙受限](https://web.sdk.qcloud.com/trtc/webrtc/v5/doc/zh-cn/tutorial-34-advanced-proxy.html)。
+>
+
+## 接口与参数
+
+视频会议 SDK 支持用户在调用 `login()` 之前通过 `callExperimentalAPI` 接口统一配置内网代理：
+``` typescript
+callExperimentalAPI({
+  api: 'setNetworkProxy',
+  params: {
+    im?: { /* IM 代理参数 */ },
+    rtc?: { /* TRTC 代理参数 */ },
+  },
+});
+```
+
+### IM 代理参数
+
+|参数|类型|说明|
+|---------|---------|---------|
+|`proxyServer`|String|IM 信令 WebSocket 代理地址。|
+|`fileUploadProxy`|String|IM 文件上传代理地址。|
+|`fileDownloadProxy`|String|IM 文件下载代理地址。|
+
+### TRTC 代理参数
+
+|参数|类型|说明|
+|---------|---------|---------|
+|`websocketProxy`|String|TRTC 信令 WebSocket 代理地址，如 `wss://proxy.example.com/ws/`。|
+|`turnServer`|Array|TURN 服务器列表，每项含 `url` / `username` / `credential`。|
+|`iceTransportPolicy`|`'relay' \| 'all'`|客户端 ICE 传输策略；内网环境建议设为 `'relay'`，强制连接 TURN server。|
+
+## 示例代码
+
+``` typescript
+import { conference } from '@tencentcloud/roomkit-web-react';
+
+conference.callExperimentalAPI({
+  api: 'setNetworkProxy',
+  params: {
+    im: {
+      proxyServer: 'wss://proxy.example.com:8080',
+      fileUploadProxy: 'https://proxy.example.com:8080',
+      fileDownloadProxy: 'https://proxy.example.com:8080',
+    },
+    rtc: {
+      websocketProxy: 'wss://proxy.example.com/ws/',
+      turnServer: [
+        { url: '14.3.3.3:3478', username: 'turn', credential: 'turn' },
+      ],
+      iceTransportPolicy: 'relay',
+    },
+  },
+});
+
+await conference.login({ sdkAppId, userId, userSig });
+await conference.createAndJoinRoom({ roomId });
+```
+
+## 常见问题
+
+### 用户在外网正常进会，但是内网无法进会？
+
+检查是否在 `login()` 前调用了 `setNetworkProxy`；若已配置仍失败，排查 TURN 端口与代理服务器出站白名单。
+
+### 用户能进会但看不到远端画面、听不到远端声音？
+
+确认 `turnServer` 可达，内网环境将 `iceTransportPolicy` 设为 `'relay'`。
+