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

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

@@ -0,0 +1,499 @@
+本文将介绍如何快速接入 TUICallKit 组件。您可以在 10 分钟内完成以下关键步骤，最终获得一个功能完备的音视频通话界面。
+
+> **推荐使用更高效的 AI 集成助手**
+>
+
+> 我们为您提供了全新的 AI 集成方式，只需要简单描述您的需求，即可**自动生成集成代码**，大幅提升开发效率。
+>
+
+> [点击这里，立即体验 AI 集成](https://cloud.tencent.com/document/product/647/125504)
+>
+
+## 准备工作
+
+### 环境要求
+- React ^18.0.0 || React^19.0.0。
+
+- [Node.js](https://nodejs.org/en/) version 16+。
+
+- Modern browser, supporting WebRTC APIs。
+
+### 开通服务
+
+在使用腾讯云提供的音视频服务前，您需要前往控制台，为应用开通音视频服务。具体步骤详见 [开通服务](https://cloud.tencent.com/document/product/647/104662)。开通服务后，请记录获取 `SDKAppID、SecretKey`，在后续的步骤中会用到。
+
+### 创建项目
+
+如果已有项目可忽略这一步。使用 Vite 创建一个新的名称为 call-demo 的 Vue3 项目。
+
+> **说明：**
+>
+
+> 高版本 Vite 需要使用最新的 Node.js 版本。
+>
+
+``` bash
+npm create vite@latest
+```
+
+## 快速接入
+
+### 步骤1：下载 TUICallKit 组件
+1. 下载 [@trtc/calls-uikit-react](https://www.npmjs.com/package/@trtc/calls-uikit-react) 组件。在已有项目或者通过 vite 等脚手架创建的空项目中，下面是以 vite 创建的空项目介绍。
+
+   【shell】
+   ``` bash
+   npm install @trtc/calls-uikit-react
+   ```
+2. 将`debug`目录复制到您的项目目录`src/debug`，本地生成 userSig 时需要使用。
+
+【MacOS】
+``` bash
+cp -r node_modules/@trtc/calls-uikit-react/debug ./src
+```
+
+【Windows】
+``` bash
+xcopy node_modules\@trtc\calls-uikit-react\debug .\src\debug /i /e
+```
+
+### 步骤2：引入 TUICallKit 组件
+
+您可以选择在 `/src/App.tsx（或 App.jsx）` 文件引入示例代码。
+1. 引入 TUICallKit 相关 API 对象。
+
+   ``` tsx
+   import { useState } from 'react';
+   import { TUICallKit, TUICallKitAPI, CallMediaType } from "@trtc/calls-uikit-react";
+   import * as GenerateTestUserSig from "./debug/GenerateTestUserSig-es"; // Refer to Step 3
+   ```
+2. 引入[<TUICallKit />](https://cloud.tencent.com/document/product/647/81015#TUICallKit)，该组件包含通话时的完整 UI 交互。
+
+   ``` javascript
+   return (
+     <div className="demo-wrapper">
+         <div className="demo-card">
+           <h2 className="demo-title">📞 Call Demo</h2>
+           <div className="form-row">
+             <label className="form-label">主叫用户 ID</label>
+             <div className="form-controls">
+               <input className="form-input" type="text" placeholder="请输入主叫用户 ID" value={callerUserID}
+                 onChange={(e) => setCallerUserID(e.target.value)}
+               />
+               <button className="btn btn-primary" onClick={init}>Step 1. Init</button>
+             </div>
+           </div>
+           <div className="form-row">
+             <label className="form-label">被叫用户 ID</label>
+             <div className="form-controls">
+               <input className="form-input" type="text" placeholder="请输入被叫用户 ID" value={calleeUserID}
+                 onChange={(e) => setCalleeUserID(e.target.value)}
+               />
+               <button className="btn btn-success" onClick={call}>Step 2. Call</button>
+             </div>
+           </div>
+         </div>
+         <div className="callkit-area">
+           {/* 【1】Import the TUICallKit component: Call interface UI */}
+           <TUICallKit />
+         </div>
+     </div>
+   );
+   ```
+3. 更新 App.css 样式文件。
+
+   ``` css
+
+   .demo-wrapper { max-width: 680px; margin: 40px auto; padding: 0 20px; font-family: system-ui, -apple-system, sans-serif; } .demo-card { background: #fff; border-radius: 16px; box-shadow: 0 4px 24px rgba(0, 0, 0, 0.08); padding: 32px; margin-bottom: 24px; } .demo-title { margin: 0 0 28px; font-size: 22px; font-weight: 600; color: #1a1a2e; text-align: center; } .form-row { margin-bottom: 18px; } .form-row:last-of-type { margin-bottom: 0; } .form-label { display: block; font-size: 14px; font-weight: 600; color: #6b7280; letter-spacing: 0.5px; margin-bottom: 8px; } .form-controls { display: flex; gap: 10px; } .form-input { flex: 1; height: 42px; padding: 0 14px; border: 1.5px solid #e5e7eb; border-radius: 10px; font-size: 15px; color: #1a1a2e; background: #fafafa; outline: none; transition: border-color 0.2s, box-shadow 0.2s; } .form-input:focus { border-color: #6366f1; box-shadow: 0 0 0 3px rgba(99, 102, 241, 0.15); background: #fff; } .form-input::placeholder { color: #c0c4cc; } .btn { height: 42px; padding: 0 20px; border: none; border-radius: 10px; font-size: 14px; font-weight: 600; cursor: pointer; white-space: nowrap; transition: transform 0.15s, box-shadow 0.2s, background 0.2s; } .btn:active { transform: scale(0.97); } .btn-primary { background: linear-gradient(135deg, #6366f1, #818cf8); color: #fff; box-shadow: 0 2px 8px rgba(99, 102, 241, 0.3); } .btn-primary:hover { background: linear-gradient(135deg, #4f46e5, #6366f1); box-shadow: 0 4px 14px rgba(99, 102, 241, 0.4); } .btn-success { background: linear-gradient(135deg, #10b981, #34d399); color: #fff; box-shadow: 0 2px 8px rgba(16, 185, 129, 0.3); } .btn-success:hover { background: linear-gradient(135deg, #059669, #10b981); box-shadow: 0 4px 14px rgba(16, 185, 129, 0.4); } .callkit-area { background: #fff; border-radius: 16px; box-shadow: 0 4px 24px rgba(0, 0, 0, 0.08); overflow: hidden; }
+   ```
+4. 调用 [TUICallKitAPI.init](https://cloud.tencent.com/document/product/647/81015#init) API 登录组件，需要在代码中**填写 **`SDKAppID、SecretKey`** 两个参数。**
+
+   ``` javascript
+   const SDKAppID = 0;        // TODO: Replace with your SDKAppID (Notice: SDKAppID is of type number）
+   const SDKSecretKey = '';   // TODO: Replace with your SDKSecretKey
+
+   const [callerUserID, setCallerUserID] = useState('');
+   const [calleeUserID, setCalleeUserID] = useState('');
+
+   //【2】Initialize the TUICallKit component
+   const init = async () => {
+     const { userSig } = GenerateTestUserSig.genTestUserSig({
+       userID: callerUserID,
+       SDKAppID,
+       SecretKey: SDKSecretKey,
+     });
+     await TUICallKitAPI.init({
+       userID: callerUserID,
+       userSig,
+       SDKAppID,
+     });
+     alert('TUICallKit init succeed');
+   }
+   ```
+   |**参数**|**类型**|**说明**|
+   |---------|---------|---------|
+   |userID|String|**用户的唯一标识符**，由您定义，只允许包含大小写英文字母(a-z A-Z)、数字(0-9)及下划线和连词符。|
+   |SDKAppID|Number|在 [Tencent RTC 控制台](https://console.cloud.tencent.com/trtc) 创建的音视频应用的唯一标识。|
+   |SDKSecretKey|String|在 [Tencent RTC 控制台](https://console.cloud.tencent.com/trtc) 创建的音视频应用的 SecretKey。|
+   |userSig|String|一种安全保护签名，用于对用户进行登录鉴权认证，确认用户是否真实，阻止恶意攻击者盗用您的云服务使用权。|
+
+   > **userSig 说明：**
+   >
+>   - **开发环境**：如果您正在本地跑通 Demo、开发调试，可以采用 `debug` 文件中的 `genTestUserSig`（参考步骤3.2）函数生成 userSig。该方法中 SDKSecretKey 很容易被反编译逆向破解，一旦您的密钥泄露，攻击者就可以盗用您的腾讯云流量。
+>   - **生产环境**：如果您的项目要发布上线，请采用 [服务端生成 UserSig](https://trtc.io/document/35166) 的方式。
+
+### 步骤3：设置昵称和头像（可选）
+
+首次登录的用户没有头像和昵称信息，您可以通过 [setSelfInfo](https://cloud.tencent.com/document/product/647/81015#setSelfInfo) 接口设置头像和昵称。
+``` typescript
+try {
+  await TUICallKitAPI.setSelfInfo({
+    nickName: "jack",
+    avatar: "http://xxx",
+  });
+} catch (error: any) {
+  alert(`[TUICallKit] Failed to call the setSelfInfo API. Reason: ${error}`);
+}
+```
+
+> **注意：**
+>
+
+> 因为用户隐私限制，非好友之间的通话，被叫的昵称和头像更新可能会有延迟，一次通话成功后就会顺利更新。
+>
+
+### 步骤4：发起通话
+
+拨打方可以通过调用 [calls](https://cloud.tencent.com/document/product/647/81015#calls) 函数，并指定通话类型和被叫方的 userID，来发起语音或视频通话。`calls` 接口同时支持一对一通话和多人通话。当 userIDList 中包含一个 userID 时，为一对一通话；当 userIDList 包含多个 userID 时，则为多人通话。
+1. 调用 [TUICallKitAPI.calls API](https://cloud.tencent.com/document/product/647/81015#calls) 拨打通话。
+
+   ``` javascript
+   //【3】Make a 1v1 video call
+   const call = async () => {
+     await TUICallKitAPI.calls({
+       userIDList: [calleeUserID],
+       type: CallMediaType.VIDEO,
+     });
+   };
+   ```
+2. 运行项目。
+
+   > **注意：**
+   >
+
+   > 本地环境请在 localhost 协议下访问，公网体验请在 HTTPS 协议下访问，具体参见 [网络访问协议说明](https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/tutorial-05-info-browser.html#h2-3)。
+   >
+
+3. 打开两个浏览器页面，输入不同的 userID(由您定义) 单击`step1. init`登录（主叫方和被叫方）。
+
+4. 两个 userID 都登录成功后，单击`step2. call `拨打通话，如果您有通话问题，参见 [常见问题](https://cloud.tencent.com/document/product/647/78769)。
+
+### 步骤5：接听通话
+
+接听端完成登录后，拨打端发起通话，接收端就可以收到通话邀请，同时伴随铃声。
+
+## 更多功能
+
+### AI 转录与翻译
+
+> **说明：**
+>
+
+> v4.4.5 版本及以上支持。
+>
+
+您可以通过调用 `enableAITranscriber` 开启/关闭 AI 转录与翻译功能。
+
+> **注意：**
+>
+> - 该功能默认为关闭状态。如需开启，请在发起通话前调用 `enableAITranscriber`(true)。
+> - AI 实时转录与翻译为增值服务。体验版赠送免费额度，可 免费体验。如需升级到正式版，可参考指引 开通正式版，计费相关详见 [计费说明](https://cloud.tencent.com/document/product/647/111976)。
+
+``` javascript
+TUICallKitAPI.enableAITranscriber(true)
+```
+
+### 开启悬浮窗功能
+
+您可以通过调用 [enableFloatWindow](https://cloud.tencent.com/document/product/647/81015#enableFloatWindow) 开启/关闭悬浮窗功能，在初始化 TUICallKit 组件时启用该功能，默认状态为关闭（false）。可通过点击通话界面左上角的悬浮窗按钮，将通话界面缩小为悬浮窗形式。
+
+方式一：调用 `enableFloatWindow(enable: boolean)` API 开启/关闭悬浮窗。
+``` javascript
+TUICallKitAPI.enableFloatWindow(true)
+```
+
+### 多人通话
+
+主叫方使用 `calls` 方法发起通话时，若被叫用户列表超过一人，则自动视为群组通话。其他成员可通过 `join` 方法加入该多人通话
+- **发起多人通话：**使用 `calls` 方法发起通话时，若被叫用户列表（`userIDList`）超过一人，则自动视为群组通话。
+
+``` typescript
+try {
+   const params = {
+     userIDList: ['user1', 'user2'],
+     type: TUICallType.VIDEO,
+   }
+  await TUICallKitAPI.calls(params);
+} catch (error: any) {
+  alert(`[TUICallKit] groupCall failed. Reason:${error}`);
+}
+```
+
+|参数|类型|说明|
+|---------|---------|---------|
+|userIDList|List<String>|目标用户的 userId 列表。|
+|type|CallMediaType|通话的媒体类型，例如视频通话、语音通话。|
+
+其它参数详见 [calls](https://cloud.tencent.com/document/product/647/81015#calls) 接口说明。
+
+- **加入多人通话：**可使用 `join` 方法加入指定的群组通话。
+
+``` typescript
+try {
+  await TUICallKitAPI.join({callId: 'xxx'});
+} catch (error: any) {
+  alert(`[TUICallKit] join failed. Reason: ${error}`);
+}
+```
+
+|参数|类型|说明|
+|---------|---------|---------|
+|callId|String|此次通话的唯一标识。|
+
+### 语言设置
+- **设置支持的语言**
+
+  - **支持的语言：**目前支持**简体中文、英文、日文。**
+
+  - **切换语言：**TUICallKit 会优先获取浏览器语言，如果是中文，英文或者日文中的一种，则以浏览器语言为主，否则使用英文。如果想切换语言，可以使用 setLanguage 接口。以设置语言为英文示例代码如下**。**
+
+``` javascript
+
+import { TUICallKitAPI } from '@trtc/calls-uikit-vue';
+TUICallKitAPI.setLanguage("zh-cn"); // "en" | "zh-cn" | "ja_JP"
+```
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| language | String | 设置的语言：<br>- "zh-cn"：中文简体。<br>- "en"：英文。<br>- "ja_JP"：日文。 |
+
+> **说明：**
+>
+
+>
+
+### 铃声设置
+
+您可通过以下方式设置默认铃声、来电静音模式。
+- **设置默认铃声（方式1）：**通过 [setCallingBell](https://cloud.tencent.com/document/product/647/78750#setCallingBell) 接口设置被叫端收到的来电铃声。
+
+   > **注意：**
+   >
+>   - 仅限传入本地 MP3 格式的文件地址，确保该文件是可以访问的。
+>   - 如需恢复默认铃声 filePath 传空即可。
+>   - 使用 ES6 import 方式引入铃声文件。
+
+   ``` typescript
+   import filePath from './static/ring.mp3';
+
+   try {
+     await TUICallKitAPI.setCallingBell(filePath?: string);
+   } catch (error: any) {
+     alert(`[TUICallKit] setCallingBell API failed. Reason: ${error}`);
+   }
+   ```
+- **设置默认铃声（方式2）：**如果您通过源码集成 TUICallKit 组件，通过替换铃声文件来达到替换铃声的目的。
+
+   |**文件名**|**用途**|
+   |---------|---------|
+   |phone_dialing.mp3|发起呼叫时的铃音|
+   |phone_ringing.mp3|接到呼叫时的铃音|
+
+- **来电静音模式：**您可以通过 enableMuteMode 设置静音模式。
+
+   ``` javascript
+   try {
+     await TUICallKitAPI.enableMuteMode(enable: boolean)；
+   } catch (error: any) {
+     alert(`[TUICallKit] enableMuteMode API failed. Reason: ${error}`);
+   }
+   ```
+
+## 自定义您的 UI
+
+### 替换图标按钮
+
+替换图标需要先源码引入，将组件拷贝到您的项目中（源码为 TypeScript 版本）。
+
+> **注意：**
+>
+
+> 替换图标适用于 **Vue + TypeScript** 项目且** CallKit** 版本号 ≥ 3.2.2，若您采用其他语言或者技术栈，请使用自实现 UI 方案。
+>
+
+1. **下载源码**
+
+【React】
+``` bash
+npm install @trtc/calls-uikit-react
+```
+
+2. **将源码拷贝到自己的项目中，以拷贝到 **`src/components/`** 目录为例：**
+
+【macOS + React】
+``` bash
+mkdir -p ./src/components/TUICallKit && cp -r ./node_modules/@trtc/calls-uikit-react/* ./src/components/TUICallKiteact
+```
+
+【Windows + React】
+``` plaintext
+xcopy .\node_modules\@trtc\calls-uikit-react  .\src\components\TUICallKit /i /e
+```
+
+3. **修改引入路径**
+
+   需要将 CallKit 改为从本地文件中引入，如下方代码。其他用法细节可参考 [TUICallKit 快速接入](https://cloud.tencent.com/document/product/647/78731)。
+
+   ``` javascript
+   import { TUICallKit, TUICallKitAPI, CallMediaType } from "./components/TUICallKit/src/index";
+   ```
+4.
+
+**解决源码拷贝可能导致的报错**
+
+【ESLint 报错】
+
+若 TUICallKit 与您项目的代码风格不一致导致报错，可将本组件目录屏蔽，如在项目根目录增加 `.eslintignore` 文件，如：
+``` text
+# .eslintignore
+src/components/TUICallKit
+```
+
+【TypeScript 报错】
+1. 如遇 Cannot find module '../package.json' 报错，是因为 TUICallKit 内引用了 JSON 文件，可在 tsconfig.json 中添加相关配置，示例：
+
+``` json
+{
+  "compilerOptions": {
+    "resolveJsonModule": true
+  }
+}
+```
+
+其他 TSConfig 问题请参见 [TSConfig Reference](https://www.typescriptlang.org/tsconfig)。
+2. 如遇 Uncaught SyntaxError: Invalid or unexpected token 报错，是因为 TUICallKit 使用了装饰器，可在 tsconfig.json 中添加相关配置，示例：
+
+``` json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true
+  }
+}
+```
+
+3. **修改 TUICallKit/Components/assets 文件夹下的图标组件**
+
+   > **注意：**
+   >
+
+   > 为了确保整个应用中的图标色调风格保持一致，请在替换时保持图标文件的名字不变。
+   >
+
+【桌面端】
+
+| 序号 | 资源路径 | 说明 |
+| --- | --- | --- |
+| 1 | /TUICallKit/Components/assets/button/camera-close.svg | 关闭摄像头图标 |
+| 2 | /TUICallKit/Components/assets/button/microphone-open.svg | 打开麦克风图标 |
+| 3 | /TUICallKit/Components/assets/button/speaker-open.svg | 打开扬声器图标 |
+| 4 | /TUICallKit/Components/assets/button/desktop/inviteUser.svg | 通话过程中邀请用户图标 |
+| 5 | /TUICallKit/Components/assets/button/hangup.svg | 挂断通话图标 |
+| 6 | /TUICallKit/Components/assets/button/desktop/minimize.svg | 悬浮窗切换图标 |
+| 7 | /TUICallKit/Components/assets/button/desktop/fullScreen.svg | 切全屏图标 |
+
+【移动端】
+
+| 序号 | 资源路径 | 说明 |
+| --- | --- | --- |
+| 1 | /TUICallKit/Components/assets/button/mobile/minimize.svg | 悬浮窗切换图标 |
+| 2 | /TUICallKit/Components/assets/button/hangup.svg | 挂断通话图标 |
+| 3 | /TUICallKit/Components/assets/button/accept.svg | 接听通话图标 |
+| 4 | /TUICallKit/Components/assets/button/microphone-open.svg | 打开麦克风图标 |
+| 5 | /TUICallKit/Components/assets/button/speaker-open.svg | 打开扬声器图标 |
+| 6 | /TUICallKit/Components/assets/button/camera-close.svg | 关闭摄像头图标 |
+| 7 | /TUICallKit/Components/assets/button/switchCamera.svg | 切前后摄像头图标 |
+
+### 隐藏按钮
+
+调用 [hideFeatureButton](https://cloud.tencent.com/document/product/647/81015#hideFeatureButton) 接口隐藏按钮，目前支持 Camera、Microphone、SwitchCamera、InviteUser，具体看枚举类型 [FeatureButton](https://cloud.tencent.com/document/product/647/81015#FeatureButton)。
+
+> **注意：**
+>
+
+> **v3.2.9+ 支持**。
+>
+
+以隐藏**摄像头按钮**为例。
+
+【React】
+``` javascript
+import { TUICallKitAPI, FeatureButton } from "@trtc/calls-uikit-react";
+
+TUICallKitAPI.hideFeatureButton(FeatureButton.Camera);
+```
+
+### 自定义通话背景图
+
+通话背景图会在语音通话或者视频通话关闭摄像头后出现，通过调用 [setLocalViewBackgroundImage](https://cloud.tencent.com/document/product/647/81015#setLocalViewBackgroundImage) 修改本地用户通话界面背景图，[setRemoteViewBackgroundImage](https://cloud.tencent.com/document/product/647/81015#setRemoteViewBackgroundImage) 修改远端用户通话界面背景图。
+
+> **注意：**
+>
+
+> **v3.2.9+ 支持**。
+>
+
+【React】
+``` javascript
+import { TUICallKitAPI } from "@trtc/calls-uikit-react";
+
+TUICallKitAPI.setLocalViewBackgroundImage('http://xxx.png');
+TUICallKitAPI.setRemoteViewBackgroundImage('remoteUserId', 'http://xxx.png');
+```
+
+### 设置布局
+
+> **注意：**
+>
+
+> **仅 1V1 视频通话可用，v3.3.0+ 支持**。
+>
+
+调用 [setLayoutMode](https://cloud.tencent.com/document/product/647/81015#setLayoutMode) 设置通话界面布局，目前仅支持 LocalInLargeView，RemoteInLargeView，具体看枚举类型 [LayoutMode](https://cloud.tencent.com/document/product/647/81015#LayoutMode)。
+1. LocalInLargeView layout，本地用户在大窗：
+
+2. RemoteInLargeView layout，远端用户在大窗：
+
+【React】
+``` javascript
+import { TUICallKitAPI, LayoutMode } from "@trtc/calls-uikit-react";
+
+TUICallKitAPI.setLayoutMode(LayoutMode.LocalInLargeView);
+```
+
+### 设置摄像头初始状态
+
+调用 [setCameraDefaultState](https://cloud.tencent.com/document/product/647/81015#setCameraDefaultState) 设置摄像头按钮初始状态，目前支持开启和关闭。
+
+以默认关闭摄像头为例：
+
+【React】
+``` javascript
+import { TUICallKitAPI } from "@trtc/calls-uikit-react";
+
+TUICallKitAPI.setCameraDefaultState(false);
+```
+
+## 常见问题
+
+如果您的接入和使用中遇到问题，请参见 [常见问题](https://cloud.tencent.com/document/product/647/78769)。
+
+## 交流与反馈