@tencent-rtc/mcp 1.7.3 → 1.7.5

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

@@ -0,0 +1,224 @@
+This guide walks you through quickly integrating the TUICallKit component using uni-app for packaging and running on the **WeChat Mini Program** platform. You can complete the following key steps in about 10 minutes and get a fully functional audio/video calling interface.
+
+## Prerequisites
+
+### Development Environment Requirements
+- Before development, please read [WeChat Mini Program Development Overview](https://developers.weixin.qq.com/miniprogram/dev/framework/).
+- Supported since **TUICallKit v4.2.6+**.
+- 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**.
+
+### Activate the Service
+Before using Tencent Cloud audio/video services, you need to go to the console to activate the service for your application. For detailed steps, see [Activate Service](https://cloud.tencent.com/document/product/1640/81130). After activation, note down the `SDKAppID` and `SDKSecretKey` — you will need them in the subsequent login step.
+
+## 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: Create a uni-app Project
+
+In HBuilderX, create a uni-app project. Select the default template.
+
+### Step 2: 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. Copy the `TUICallKit` folder to the root directory of your uni-app project.
+
+### Step 3: Fill in SDKAPPID and SECRETKEY
+
+Modify the `SDKAPPID` and `SECRETKEY` in the `TUICallKit/debug/GenerateTestUserSig-es.js` file.
+
+### Step 4: Use the TUICallKit Component
+1. Modify the `pages.json` file. Add the following code to register the global call monitoring page.
+
+   ``` json
+   {
+     "pages": [
+       {
+         "path": "pages/index/index",
+         "style": {
+           "navigationStyle": "custom"
+         }
+       },
+       {
+         "path": "TUICallKit/pages/globalCall/globalCall",
+         "style": {
+           "navigationStyle": "custom"
+         }
+       }
+     ],
+     "globalStyle": {
+       "navigationBarTextStyle": "black",
+       "navigationBarTitleText": "TUICallKit",
+       "navigationBarBackgroundColor": "#F8F8F8",
+       "backgroundColor": "#F8F8F8"
+     }
+   }
+   ```
+2. Create a `wxcomponents` folder in the project root directory.
+
+3. Copy the `TUICallKit/component` folder to `wxcomponents/TUICallKit`.
+
+4. Modify `pages/index/index.vue`.
+
+   ``` html
+   <template>
+     <view class="container">
+       <input
+         type="text"
+         maxlength="20"
+         :placeholder="isLogin ? 'Enter callee userID' : 'Enter login userID'"
+         :value="userID"
+         @input="bindInputUserID"
+       />
+       <button @tap="isLogin ? call() : login()">
+         {{ isLogin ? 'Call' : 'Login' }}
+       </button>
+     </view>
+   </template>
+
+   <script>
+   import { TUICallKitAPI } from '../../TUICallKit/TUICallService/index';
+   import { CallManager } from '../../TUICallKit/TUICallService/serve/callManager';
+   import * as GenerateTestUserSig from '../../TUICallKit/debug/GenerateTestUserSig-es.js';
+   wx.CallManager = new CallManager();
+
+   export default {
+     data() {
+       return {
+         userID: '',
+         isLogin: false,
+       };
+     },
+     methods: {
+       bindInputUserID(e) {
+         this.userID = e.detail.value;
+       },
+       async login() {
+         const userID = this.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',
+         });
+         uni.showToast({ title: 'Login successful' });
+         this.isLogin = true;
+         this.userID = '';
+       },
+       async call() {
+         await TUICallKitAPI.calls({
+           userIDList: [this.userID],
+           type: 2,
+         });
+       },
+     },
+   };
+   </script>
+   ```
+5. You must use **Vue 2** for compilation. Currently, **Vue 3** is not supported.
+
+### Step 5: Build and Run
+1. In HBuilderX, click **Run > Run to Mini Program Simulator > WeChat DevTools**. This will automatically open WeChat DevTools.
+
+2. In WeChat DevTools local settings, check "Do not verify valid domains, web-view (business domains), TLS version, and HTTPS certificates".
+
+3. Click **Clear Cache > Clear All** to avoid rendering issues caused by DevTools cache.
+
+4. Build the mini program.
+
+5. Expected result after quick integration.
+
+### Step 6: 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.
+   >
+
+## FAQ
+
+### What should I do if the uni-app project imports successfully but pages are blank?
+1. Due to WeChat DevTools caching, click **Clear Cache > Clear All** and rebuild.
+2. Check if `wxcomponents/TUICallKit` is correctly placed and contains the component files.
+3. Verify `pages.json` includes the `globalCall` page registration.

package/resource/knowledge/callkit/preset/uni-app/api.md

@@ -0,0 +1,339 @@
+## API Overview
+
+### TUICallKit (with UI)
+
+TUICallKit is the **audio/video calling component with a UI interface**. Using this API is like adding a WeChat-like audio/video calling scenario to your app.
+
+| API | Description |
+| --- | --- |
+| init | Initialize TUICallKit |
+| calls | Initiate 1v1 / group call |
+| setSelfInfo | Set user nickname and avatar |
+| setCallingBell | Set custom ringtone |
+| enableMuteMode | Enable/disable mute mode |
+| enableFloatWindow | Enable/disable floating window |
+
+### TUICallEngine (No UI)
+
+TUICallEngine is the underlying engine **without a UI interface**, suitable for custom audio/video calling scenarios.
+
+| API | Description |
+| --- | --- |
+| createInstance | Create a TUICallEngine instance (static method) |
+| destroyInstance | Destroy a TUICallEngine instance (static method) |
+| on | Register an event listener |
+| off | Unregister an event listener |
+| login | Login |
+| logout | Logout |
+| setSelfInfo | Set user nickname and avatar |
+| calls | Initiate 1v1 / group call |
+| groupCall | Initiate a group call |
+| accept | Accept a call |
+| reject | Reject a call |
+| hangup | Hang up a call |
+| switchCallMediaType | Switch call media type (e.g., voice to video) |
+| openCamera | Enable camera |
+| closeCamera | Disable camera |
+| switchCamera | Switch between front/rear camera |
+| openMicrophone | Enable microphone |
+| closeMicrophone | Disable microphone |
+| setMicMute | Set microphone mute state |
+| setVideoQuality | Set video encoding quality |
+
+## API Details
+
+### TUICallKit API Details
+
+#### init
+
+Initialize TUICallKit. This must be called before using any other TUICallKit features.
+
+``` javascript
+import TUICallKit from '../../TUICallKit/TUICallKit.vue';
+
+// Call via ref
+this.$refs.TUICallKit.init({
+  sdkAppID: 0,       // Replace with your SDKAppID
+  userID: 'userID',  // Replace with your userID
+  userSig: 'userSig' // Replace with your userSig
+})
+```
+
+Parameter details:
+| Parameter | Type | Required | Default | Description |
+|---------|---------|---------|---------|---------|
+| sdkAppID | Number | Yes | - | SDKAppID |
+| userID | String | Yes | - | User ID |
+| userSig | String | Yes | - | UserSig |
+
+#### calls
+
+Initiate a 1v1 or group call. When `userIDList` contains a single user, it is a 1v1 call; when it contains multiple users, it is a group call.
+
+``` javascript
+this.$refs.TUICallKit.calls({
+  userIDList: ['mike'],
+  type: 2
+})
+```
+
+Parameter details:
+| Parameter | Type | Required | Default | Description |
+|---------|---------|---------|---------|---------|
+| userIDList | Array | Yes | - | List of callee userIDs. For 1v1 calls, pass one userID; for group calls, pass multiple userIDs |
+| type | Number | Yes | - | Call media type: 1 for voice, 2 for video |
+| groupID | String | No | - | IM group ID. When calling in a group chat, this field must be passed |
+| timeout | Number | No | 30 | Timeout in seconds, 0 means no timeout |
+| roomID | Number | No | - | Numeric room ID, range [1, 2147483647] |
+| strRoomID | String | No | - | String room ID, length up to 64 bytes. `roomID` and `strRoomID` are mutually exclusive; if `strRoomID` is specified, `roomID` must be 0 |
+| offlinePushInfo | Object | No | - | Custom offline push information |
+| offlinePushInfo.title | String | No | - | Offline push title |
+| offlinePushInfo.description | String | No | - | Offline push description |
+| offlinePushInfo.androidOPPOChannelID | String | No | - | OPPO channel ID for offline push |
+| offlinePushInfo.extension | String | No | - | Offline push extension field |
+| data | String | No | - | Custom data passed to the callee |
+
+#### setSelfInfo
+
+Set user nickname and avatar.
+
+``` javascript
+this.$refs.TUICallKit.setSelfInfo({
+  nickName: 'Tom',
+  avatar: 'https://...'
+})
+```
+
+Parameter details:
+| Parameter | Type | Required | Default | Description |
+|---------|---------|---------|---------|---------|
+| nickName | String | No | - | User nickname |
+| avatar | String | No | - | User avatar URL |
+
+#### setCallingBell
+
+Set a custom ringtone for incoming calls.
+
+``` javascript
+this.$refs.TUICallKit.setCallingBell(filePath)
+```
+
+Parameter details:
+| Parameter | Type | Required | Default | Description |
+|---------|---------|---------|---------|---------|
+| filePath | String | Yes | - | Path to the ringtone file. Only local file paths are accepted. The setting is device-bound and persists across user switches. Pass an empty string to restore the default ringtone. |
+
+#### enableMuteMode
+
+Enable/disable mute mode for incoming calls.
+
+``` javascript
+this.$refs.TUICallKit.enableMuteMode(true)
+```
+
+Parameter details:
+| Parameter | Type | Required | Default | Description |
+|---------|---------|---------|---------|---------|
+| enable | Boolean | Yes | false | true to enable mute mode (no ringtone on incoming calls), false to disable |
+
+#### enableFloatWindow
+
+Enable/disable the floating window feature.
+
+``` javascript
+this.$refs.TUICallKit.enableFloatWindow(true)
+```
+
+Parameter details:
+| Parameter | Type | Required | Default | Description |
+|---------|---------|---------|---------|---------|
+| enable | Boolean | Yes | false | true to enable floating window, false to disable |
+
+### TUICallEngine API Details
+
+#### createInstance
+
+Create a TUICallEngine instance.
+
+``` javascript
+import { TUICallEngine } from '../../TUICallKit/TUICallService/index';
+const tuiCallEngine = TUICallEngine.createInstance();
+```
+
+#### destroyInstance
+
+Destroy the TUICallEngine instance to release resources.
+
+``` javascript
+TUICallEngine.destroyInstance();
+```
+
+#### on
+
+Register an event listener.
+
+``` javascript
+tuiCallEngine.on(event, callback)
+```
+
+#### off
+
+Unregister an event listener.
+
+``` javascript
+tuiCallEngine.off(event, callback)
+```
+
+#### login
+
+Login. All features require login first.
+
+``` javascript
+tuiCallEngine.login({ SDKAppID, userID, userSig })
+```
+
+Parameter details:
+| Parameter | Type | Required | Default | Description |
+|---------|---------|---------|---------|---------|
+| SDKAppID | Number | Yes | - | SDKAppID |
+| userID | String | Yes | - | User ID |
+| userSig | String | Yes | - | UserSig |
+
+#### logout
+
+Logout.
+
+``` javascript
+tuiCallEngine.logout()
+```
+
+#### setSelfInfo
+
+Set user nickname and avatar.
+
+``` javascript
+tuiCallEngine.setSelfInfo({ nickName, avatar })
+```
+
+#### calls
+
+Initiate a call (supports both 1v1 and group calls).
+
+``` javascript
+tuiCallEngine.calls({
+  userIDList: ['mike'],
+  type: 2
+})
+```
+
+Parameter details:
+| Parameter | Type | Required | Default | Description |
+|---------|---------|---------|---------|---------|
+| userIDList | Array | Yes | - | List of callee userIDs |
+| type | Number | Yes | - | Call media type: 1 for voice, 2 for video |
+| groupID | String | No | - | IM group ID |
+| timeout | Number | No | 30 | Timeout in seconds |
+| roomID | Number | No | - | Numeric room ID |
+| strRoomID | String | No | - | String room ID |
+| offlinePushInfo | Object | No | - | Offline push information |
+| data | String | No | - | Custom data |
+
+#### groupCall
+
+Initiate a group call.
+
+``` javascript
+tuiCallEngine.groupCall({
+  userIDList: ['mike', 'tom'],
+  type: 2,
+  groupID: 'xxx'
+})
+```
+
+#### accept
+
+Accept a call.
+
+``` javascript
+tuiCallEngine.accept()
+```
+
+#### reject
+
+Reject a call.
+
+``` javascript
+tuiCallEngine.reject()
+```
+
+#### hangup
+
+Hang up a call.
+
+``` javascript
+tuiCallEngine.hangup()
+```
+
+#### switchCallMediaType
+
+Switch between voice and video call types. Only supported in 1v1 calls.
+
+``` javascript
+tuiCallEngine.switchCallMediaType({ newMediaType: 1 })
+```
+
+#### openCamera
+
+Enable the camera.
+
+``` javascript
+tuiCallEngine.openCamera()
+```
+
+#### closeCamera
+
+Disable the camera.
+
+``` javascript
+tuiCallEngine.closeCamera()
+```
+
+#### switchCamera
+
+Switch between front and rear cameras.
+
+``` javascript
+tuiCallEngine.switchCamera({ cameraId: 'front' })
+```
+
+#### openMicrophone
+
+Enable the microphone.
+
+``` javascript
+tuiCallEngine.openMicrophone()
+```
+
+#### closeMicrophone
+
+Disable the microphone.
+
+``` javascript
+tuiCallEngine.closeMicrophone()
+```
+
+#### setMicMute
+
+Set microphone mute state.
+
+``` javascript
+tuiCallEngine.setMicMute({ isMute: true })
+```
+
+#### setVideoQuality
+
+Set video encoding quality.
+
+``` javascript
+tuiCallEngine.setVideoQuality(quality)
+```