@tencent-rtc/mcp 1.7.3 → 1.7.5

package/resource/knowledge/callkit/preset/miniprogram/api.md

@@ -0,0 +1,293 @@
+TUICallKit is the **UI-included interface** for the audio/video calling component. Using the TUICallKit API, you can quickly implement a WeChat-like audio/video calling scenario with simple API calls. For detailed integration steps, see [Quick Integration of TUICallKit](https://cloud.tencent.com/document/product/647/78733).
+
+> **Note:**
+> - To provide better audio/video communication capabilities, the original @trtc/call-uikit-wechat package has been officially deprecated. Developers are advised to migrate to the new @trtc/calls-uikit-wx-uniapp and @trtc/calls-uikit-wx packages.
+> - The new packages include optimized API adjustments. Some legacy interfaces are no longer compatible, and cleaner, more stable new interfaces are provided.
+
+## API Overview
+
+| API | Description |
+|---------|---------|
+| [\<TUICallKit /\>](#TUICallKit) | TUICallKit call UI component. |
+| [init](#init) | Initialize TUICallKit |
+| [calls](#calls) | Initiate a single or multi-party call. |
+| [join](#join) | Actively join a call. |
+| [setSelfInfo](#setSelfInfo) | Set user avatar and nickname. |
+| [setCallingBell](#setCallingBell) | Set custom incoming call ringtone. |
+| [setLogLevel](#setLogLevel) | Set log level. |
+| [enableMuteMode](#enableMuteMode) | Enable/disable incoming call ringtone. |
+| [enableFloatWindow](#enableFloatWindow) | Enable/disable floating window. |
+| [hideFeatureButton](#hideFeatureButton) | Hide a feature button. |
+| [setLocalViewBackgroundImage](#setLocalViewBackgroundImage) | Set local user call background image. |
+| [setRemoteViewBackgroundImage](#setRemoteViewBackgroundImage) | Set remote user call background image. |
+| [setLayoutMode](#setLayoutMode) | Set call interface layout mode. |
+| [setCameraDefaultState](#setCameraDefaultState) | Set whether camera is on by default. |
+| [destroyed](#destroyed) | Destroy TUICallKit. |
+| [getTUICallEngineInstance](#getTUICallEngineInstance) | Get TUICallEngine instance. |
+
+## API Details
+
+[uni-app Mini Program]
+``` javascript
+import { TUICallKitAPI } from "@trtc/calls-uikit-wx-uniapp";
+```
+
+[WeChat Mini Program]
+``` javascript
+import { TUICallKitAPI } from "@trtc/calls-uikit-wx";
+```
+
+### init
+
+Initialize TUICallKit.
+``` javascript
+TUICallKitAPI.init({
+     sdkAppID: 0, // Replace with your SDKAppID
+     userID: 'jane', // Enter the current userID
+     userSig: 'xxxxxxxxxxxx',
+     tim: null, // If you don't need a TIM instance, you can omit this
+})
+```
+
+**Parameters:**
+
+| Parameter | Type | Description | Required |
+|---------|---------|---------|---------|
+| sdkAppID | Number | You can find the SDKAppID in **TRTC Console** > [Application Management](https://console.cloud.tencent.com/trtc/app) > **Application Info**. | Yes |
+| userID | String | Current user ID. String type, only allows letters (a-z, A-Z), digits (0-9), hyphens (-), and underscores (_). | Yes |
+| userSig | String | Tencent Cloud security signature. See [How to Calculate and Use UserSig](https://cloud.tencent.com/document/product/647/17275) for details. | Yes |
+| tim | ChatSDK | TIM instance. | No |
+
+Additional details on init parameters:
+- **userSig**: Encrypt information like sdkAppID and userID using the SecretKey obtained in Step 3 to generate userSig. It is an authentication ticket for Tencent Cloud to verify whether the current user is authorized to use TRTC services. See [How to Calculate and Use UserSig](https://cloud.tencent.com/document/product/647/17275) for more.
+
+- **tim**: You can pass an external TIM instance to CallKit via init. The tim parameter is for scenarios where a TIM instance already exists in your business, ensuring TIM instance uniqueness.
+
+### calls
+
+Initiate a 1v1 or multi-party call.
+``` javascript
+TUICallKitAPI.calls({
+    userIDList: ["jane", "mike", "tommy"],
+    type: 1,
+})
+```
+
+**Parameters:**
+| Parameter | Type | Description | Required |
+| --- | --- | --- | --- |
+| userIDList | Array\<String\> | Target user ID list, e.g., ["jane", "mike", "tommy"]. | Yes |
+| type | CallMediaType | Call media type. See CallMediaType for parameter values. | Yes |
+| chatGroupID | String | IM group ID when used with Chat. | Yes |
+| roomID | Number | Numeric room ID, range [1, 2147483647]. | No |
+| userData | String | Extension field: used to add extra information in the invitation signaling. | No |
+| timeout | Number | Call timeout in seconds. 0 means no timeout. Range: 10s – 600s. If 0 is passed, defaults to 30s.<br>The callee must be logged in within 30s for the timeout value to take effect. See "timeout field not taking effect" for details. | No |
+| [offlinePushInfo](#offlinePushInfo) | Object | Custom offline push information (optional). | No |
+
+### join
+
+Actively join a call.
+``` javascript
+TUICallKitAPI.join({callId: xx});
+```
+
+**Parameters:**
+
+| Parameter | Type | Description | Required |
+|---------|---------|---------|---------|
+| callId | String | Unique ID of this call. | Yes |
+
+### setSelfInfo
+
+Set user avatar and nickname.
+
+> **Note:**
+> **Modifying user info during a call will not immediately update the UI. Changes will take effect in the next call.**
+>
+
+``` javascript
+TUICallKitAPI.setSelfInfo({ nickName: "xxx", avatar: "http://xxx" });
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|---------|---------|---------|
+| nickName | String | Set nickname. |
+| avatar | String | Avatar URL. |
+
+### setCallingBell
+
+Set custom incoming call ringtone.
+
+Only local file paths are accepted. Ensure the file directory is accessible by the application.
+- Pass a local absolute path for the ringtone file.
+
+- To restore the default ringtone, pass an empty `filePath`.
+
+- Supported ringtone file formats:
+
+   | Format | iOS | Android |
+   |---------|---------|---------|
+   | m4a | √ | √ |
+   | mp3 | √ | √ |
+   | wav | √ | √ |
+   | aac | √ | √ |
+
+   ``` javascript
+   TUICallKitAPI.setCallingBell("filePath")
+   ```
+
+   **Parameters:**
+
+   | Parameter | Type | Description |
+   |---------|---------|---------|
+   | filePath | String | Ringtone file path. |
+
+### setLogLevel
+
+Set the log level. Logs below the specified level will not be output.
+``` javascript
+TUICallKitAPI.setLogLevel(level)
+```
+
+**Parameters:**
+| Parameter | Value | Description |
+| --- | --- | --- |
+| level | 0 | Normal level, verbose logs. Recommended during integration. |
+|  | 1 | Release level, SDK outputs key information only. Recommended for production. |
+|  | 2 | Warning level, SDK outputs only warnings and errors. |
+|  | 3 | Error level, SDK outputs only errors. |
+|  | 4 | No logs, SDK will not print any logs. |
+
+### enableMuteMode
+
+Enable/disable incoming call ringtone.
+- Default is `false`: a ringtone plays when receiving a call request.
+
+- If set to `true`: no ringtone plays when receiving a call request.
+
+   ``` javascript
+   try {
+     await TUICallKitAPI.enableMuteMode(enable: boolean)
+   } catch (error: any) {
+     console.error(`[TUICallKit] Failed to call the enableMuteMode API. Reason: ${error}`);
+   }
+   ```
+
+### enableFloatWindow
+
+Enable/disable the floating window feature. Default is `false` (the floating window button in the top-left corner of the call interface is hidden). When set to `true`, the button is displayed.
+``` javascript
+try {
+  await TUICallKitAPI.enableFloatWindow(enable: boolean)
+} catch (error: any) {
+  console.error(`[TUICallKit] Failed to call the enableFloatWindow API. Reason: ${error}`);
+}
+```
+
+### hideFeatureButton
+
+Hide a feature button. Currently supports hiding the camera, microphone, and front/rear camera switch buttons.
+``` typescript
+TUICallKitAPI.hideFeatureButton(buttonName: FeatureButton);
+```
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|---------|---------|---------|---------|
+| buttonName | [FeatureButton](#FeatureButton) | Yes | Button name. |
+
+### setLocalViewBackgroundImage
+
+Set the local user's call background image.
+``` typescript
+TUICallKitAPI.setLocalViewBackgroundImage(url: string);
+```
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| url | String | Yes | Image URL (supports local paths and network URLs).<br>**Note:**<br>If using a network URL, it must be added to the request valid domains. |
+
+### setRemoteViewBackgroundImage
+
+Set the remote user's call background image.
+``` typescript
+TUICallKitAPI.setRemoteViewBackgroundImage(userId: string, url: string);
+```
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| userId | String | Yes | Remote user's userId. Set to '*' to apply to all remote users. |
+| url | String | Yes | Image URL (supports local paths and network URLs).<br>**Note:**<br>If using a network URL, it must be added to the request valid domains. |
+
+### setLayoutMode
+
+Set the call interface layout mode.
+``` javascript
+import { TUICallKitAPI, LayoutMode } from "../../TUICallKit/src/index";
+TUICallKitAPI.setLayoutMode(LayoutMode.LocalInLargeView);
+```
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|---------|---------|---------|---------|
+| layoutMode | [LayoutMode](#LayoutMode) | Yes | User stream layout mode. |
+
+### setCameraDefaultState
+
+Set whether the camera is on by default.
+``` javascript
+TUICallKitAPI.setCameraDefaultState(true);
+```
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|---------|---------|---------|---------|
+| isOpen | boolean | Yes | Whether to enable the camera. |
+
+### destroyed
+
+Destroy TUICallKit.
+``` javascript
+TUICallKitAPI.destroyed()
+```
+
+### getTUICallEngineInstance
+
+Get the TUICallEngine instance.
+``` javascript
+TUICallKitAPI.getTUICallEngineInstance();
+```
+
+## TUICallKit Type Definitions
+
+### offlinePushInfo
+
+| Parameter | Type | Required | Description |
+|---------|---------|---------|---------|
+| offlinePushInfo.title | String | No | Offline push title (optional). |
+| offlinePushInfo.description | String | No | Offline push content (optional). |
+| offlinePushInfo.androidOPPOChannelID | String | No | OPPO channel ID for Android 8.0+ offline push (optional). |
+| offlinePushInfo.extension | String | No | Offline push pass-through content (optional) (tsignaling version ≥ 0.9.0). |
+
+### FeatureButton
+
+| FeatureButton Type | Description |
+|---------|---------|
+| FeatureButton.Camera | Camera button. |
+| FeatureButton.Microphone | Microphone button. |
+| FeatureButton.SwitchCamera | Switch front/rear camera button. |
+| FeatureButton.InviteUser | Invite user button. |
+
+### LayoutMode
+
+| LayoutMode Type | Description |
+|---------|---------|
+| LayoutMode.LocalInLargeView | Local user displayed in the large view. |
+| LayoutMode.RemoteInLargeView | Remote user displayed in the large view. |

package/resource/knowledge/callkit/preset/miniprogram/integration.md

@@ -0,0 +1,294 @@
+
+## Mini Program Demo Experience
+- To try the audio/video calling mini program directly, [click Demo Experience](https://cloud.tencent.com/document/product/647/17021) and scan the mini program QR code.
+
+- To run a new project from scratch, go directly to [WeChat Mini Program Demo Quick Start](https://github.com/tencentyun/TUICallKit/tree/main/MiniProgram).
+
+## Development Environment Requirements
+- WeChat App iOS minimum version: 7.0.9.
+
+- WeChat App Android minimum version: 7.0.8.
+
+- Mini Program base library minimum version: 2.10.0.
+
+   > **Warning:**
+   >
+   > - Since mini program test accounts do not have access to `<live-pusher>` and `<live-player>`, please use an **enterprise mini program account** to apply for the required permissions for development.
+   > - Since WeChat DevTools does not support native components (`<live-pusher>` and `<live-player>` tags), you need to run and test on a **real device**.
+   > - **WeChat Work mini programs are not supported**.
+
+## Mini Program Development Setup
+
+### Step 1: Register an Enterprise Mini Program
+
+### Step 2: Enable Real-Time Audio/Video APIs in the Mini Program Console
+
+- The live push/pull stream tag usage permission is currently only available for limited categories. [See supported categories here](https://developers.weixin.qq.com/miniprogram/dev/component/live-pusher.html#%E7%94%B3%E8%AF%B7%E5%BC%80%E9%80%9A).
+
+- Mini programs that meet the category requirements need to self-enable this component permission in [WeChat Official Accounts Platform](https://mp.weixin.qq.com/) > **Development** > **Development Management** > **API Settings**.
+
+- Log in to the mini program console to update the privacy policy, checking **Microphone** and **Camera**.
+
+### Step 3: Configure Domains in the Mini Program Console
+
+In [WeChat Official Accounts Platform](https://mp.weixin.qq.com/) > **Development** > **Development Management** > **Development Settings** > **Server Domains**, configure **request valid domains** and **socket valid domains**.
+
+- Add the following domains to **socket valid domains**:
+
+| Domain | Description | Required |
+| --- | --- | --- |
+| `wss://${SDKAppID}w4c.my-imcloud.com` | Since v3.4.6, the SDK supports dedicated domains for better service stability.<br>For example, if your SDKAppID is 1400xxxxxx, the dedicated domain is: `wss://1400xxxxxxw4c.my-imcloud.com` | Required |
+| `wss://wss.im.qcloud.com` | Web IM service domain | Required |
+| `wss://wss.tim.qq.com` | Web IM service domain | Required |
+| `wss://wssv6.im.qcloud.com` | Web IM service domain | Required |
+
+- Add the following domains to **request valid domains**:
+
+   | Domain | Description | Required |
+   |---------|---------|---------|
+   |`https://web.sdk.qcloud.com`|Web IM service domain|Required|
+   |`https://boce-cdn.my-imcloud.com`|Web IM service domain|Required|
+   |`https://api.im.qcloud.com`|Web IM service domain|Required|
+   |`https://events.im.qcloud.com`|Web IM service domain|Required|
+   |`https://webim.tim.qq.com`|Web IM service domain|Required|
+   |`https://wss.im.qcloud.com`|Web IM service domain|Required|
+   |`https://wss.tim.qq.com`|Web IM service domain|Required|
+
+- Add the following domains to **uploadFile valid domains**:
+
+| Domain | Description | Required |
+| --- | --- | --- |
+| `https://${SDKAppID}-cn.rich.my-imcloud.com` | **Since September 10, 2024, new applications are assigned dedicated COS domains by default.**<br>For example, if your SDKAppID is 1400xxxxxx, the COS dedicated domain is: `https://1400xxxxxx-cn.rich.my-imcloud.com` | Required |
+| `https://cn.rich.my-imcloud.com` | File upload domain | Required |
+| `https://cn.imrich.qcloud.com` | File upload domain | Required |
+| `https://cos.ap-shanghai.myqcloud.com` | File upload domain | Required |
+| `https://cos.ap-shanghai.tencentcos.cn` | File upload domain | Required |
+| `https://cos.ap-guangzhou.myqcloud.com` | File upload domain | Required |
+
+- Add the following domains to **downloadFile valid domains**:
+
+| Domain | Description | Required |
+| --- | --- | --- |
+| `https://${SDKAppID}-cn.rich.my-imcloud.com` | **Since September 10, 2024, new applications are assigned dedicated COS domains by default.**<br>For example, if your SDKAppID is 1400xxxxxx, the COS dedicated domain is: `https://1400xxxxxx-cn.rich.my-imcloud.com` | Required |
+| `https://cn.rich.my-imcloud.com` | File download domain | Required |
+| `https://cn.imrich.qcloud.com` | File download domain | Required |
+| `https://cos.ap-shanghai.myqcloud.com` | File download domain | Required |
+| `https://cos.ap-shanghai.tencentcos.cn` | File download domain | Required |
+| `https://cos.ap-guangzhou.myqcloud.com` | File download domain | Required |
+
+## TUICallKit Source Code Integration
+
+### Step 1: Activate the Service
+
+Before using Tencent Cloud audio/video services, you need to go to the console to activate the service for your application.
+
+### Step 2: Create a Mini Program Project
+1. In WeChat DevTools, create a mini program project and select **Do not use template**.
+
+   ``` json
+   {
+     "pages": [
+       "pages/index/index"
+     ],
+     "window": {
+       "navigationBarTextStyle": "black",
+       "navigationStyle": "custom"
+     },
+     "style": "v2",
+     "renderer": "webview"
+   }
+   ```
+
+3. Open a new terminal.
+
+4. Run `npm init -y` to generate the `package.json` file.
+
+   ``` javascript
+   npm init -y
+   ```
+
+### Step 3: Download and Import the TUICallKit Component
+1. Download the `TUICallKit` component.
+
+   ``` bash
+   npm i @trtc/calls-uikit-wx
+   ```
+
+[macOS]
+``` bash
+mkdir -p ./TUICallKit && cp -r node_modules/@trtc/calls-uikit-wx/ ./TUICallKit
+```
+
+[Windows]
+``` bash
+xcopy node_modules\@trtc\calls-uikit-wx\ .\TUICallKit /i /e
+```
+
+2. After running the above commands, a `TUICallKit` folder is generated in your directory containing the TUICallKit component.
+
+3. **Build npm.** Open **WeChat DevTools** and click **Tools > Build npm** to create the miniprogram_npm directory.
+
+### Step 4: Fill in SDKAPPID and SECRETKEY
+
+Modify the `SDKAPPID` and `SECRETKEY` in the `TUICallKit/debug/GenerateTestUserSig-es.js` file.
+
+### Step 5: Use the TUICallKit Component
+1. Modify the `app.json` file. Add the following code to register the global call monitoring page.
+
+   ``` json
+   {
+     "pages": [
+       "pages/index/index",
+       "TUICallKit/pages/globalCall/globalCall"
+     ],
+     "window": {
+       "navigationBarTextStyle": "black",
+       "navigationStyle": "custom"
+     },
+     "style": "v2"
+   }
+   ```
+2. Modify the files in the `pages/index` folder.
+
+[index.wxml]
+``` javascript
+<view class="container">
+  <view class="box">
+    <view class="input-box">
+      <input type="text" maxlength="20" placeholder="{{isLogin?'Enter callee userID':'Enter login userID' }}" value="{{userID}}" bindinput='bindInputUserID' placeholder-style="color:#BBBBBB;" />
+    </view>
+    <view class='login'>
+      <button class='loginBtn' bindtap="{{isLogin?'call':'login'}}">{{isLogin?'Call':'Login'}}</button>
+    </view>
+  </view>
+</view>
+```
+
+[index.js]
+``` javascript
+// Import TUICallKitAPI module to enable global call capability
+import { TUICallKitAPI } from "../../TUICallKit/TUICallService/index";
+// Import CallManager module to enable global incoming call monitoring
+import { CallManager } from "../../TUICallKit/TUICallService/serve/callManager";
+import * as GenerateTestUserSig from "../../TUICallKit/debug/GenerateTestUserSig-es.js";
+wx.CallManager = new CallManager();
+Page({
+  data: {
+    userID: "",
+    isLogin: false,
+  },
+
+  bindInputUserID(e) {
+    this.setData({
+      userID: e.detail.value,
+    });
+  },
+
+  async login() {
+    const userID = this.data.userID;
+    if (!userID) return;
+    const { userSig, SDKAppID } = GenerateTestUserSig.genTestUserSig({
+      userID: userID,
+    });
+    await wx.CallManager.init({
+      sdkAppID: SDKAppID,
+      userID: userID,
+      userSig: userSig,
+      globalCallPagePath: "TUICallKit/pages/globalCall/globalCall",
+    });
+    wx.showToast({
+      title: "Login successful",
+      icon: "error",
+    });
+    this.setData({
+      isLogin: true,
+      userID: "",
+    });
+  },
+
+  async call() {
+    await TUICallKitAPI.calls({
+      userIDList: [this.data.userID],
+      type: 2,
+    });
+  },
+});
+```
+
+[index.wxss]
+``` css
+.container {
+  width: 100vw;
+  height: 100vh;
+}
+
+.box{
+  flex: 1;
+  width: 100vw;
+  margin-top: -40px;
+  background: #ffffff;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+}
+
+input{
+  display: flex;
+  font-size: 20px;
+  width: 60vw;
+}
+
+.login {
+  display: flex;
+  width: 100vw;
+  text-align: center;
+  bottom: 5vh;
+  margin: 70rpx;
+}
+.login button{
+  width: 80%;
+  background-color: #006eff;
+  border-radius: 50px;
+  color: white;
+}
+```
+
+### Step 6: Build and Run
+1. In local settings, check "Do not verify valid domains, web-view (business domains), TLS version, and HTTPS certificates".
+
+   > **Warning:**
+   >
+   > **If this option is not checked, the following error will appear in the console.**
+   >
+   >
+   >
+
+2. Click **Clear Cache > Clear All** to avoid rendering issues caused by DevTools cache.
+
+3. Build the mini program.
+
+4. Expected result after quick integration.
+
+### Step 7: Make Your First Call
+- Click Preview, scan the QR code, and use the mini program on a real device.
+
+   > **Note:**
+   >
+   > The first time you use the mini program for calls, you need to grant camera and microphone permissions.
+   >
+
+## More Features
+
+### Enable Floating Window
+
+> **Note:**
+> Supported since v4.2.10+. Due to [live-player](https://developers.weixin.qq.com/miniprogram/dev/component/live-player.html#%E5%B0%8F%E7%AA%97%E7%89%B9%E6%80%A7%E8%AF%B4%E6%98%8E) limitations, this feature is only supported in video call scenarios.
+>
+
+You can call `enableFloatWindow` to enable/disable the floating window feature. Enable this feature when initializing the `TUICallKit` component. Default state is disabled (`false`). You can click the floating window button in the top-left corner of the call interface to minimize the call UI into a floating window.
+
+Call `enableFloatWindow(enable: boolean)` API to enable/disable floating window.
+``` javascript
+TUICallKitAPI.enableFloatWindow(true)
+```