@tencent-rtc/mcp 1.7.3 → 1.7.4

package/resource/knowledge/callkit/core-sdk/miniprogram/call-event.md

@@ -0,0 +1,315 @@
+TUICallEvent API is the event interface for the audio/video calling component.
+
+> **Note:**
+> - To provide better audio/video communication capabilities, the original [tuicall-engine-wx](https://www.npmjs.com/package/tuicall-engine-wx) package has been officially deprecated. Developers are advised to migrate to the new [@trtc/call-engine-lite-wx](https://www.npmjs.com/package/@trtc/call-engine-lite-wx) package.
+> - The new package includes optimized API adjustments. Some legacy interfaces are no longer compatible, and cleaner, more stable new interfaces are provided.
+
+## TUICallEvent Overview
+
+| Event Name | Description |
+|---------|---------|
+| [ON_CALL_RECEIVED](#ON_CALL_RECEIVED) | Call request received event. |
+| [USER_ACCEPT](#USER_ACCEPT) | User accepted the call. **Deprecated in v4.x.x.** |
+| [USER_ENTER](#USER_ENTER) | User entered the call. |
+| [USER_LEAVE](#USER_LEAVE) | User left the call. |
+| [USER_UPDATE](#USER_UPDATE) | User updated. |
+| [REJECT](#REJECT) | User rejected the call. |
+| [NO_RESP](#NO_RESP) | User did not respond. |
+| [LINE_BUSY](#LINE_BUSY) | User is busy. |
+| [ON_CALL_NOT_CONNECTED](#ON_CALL_CANCELED) | Call was not established. All participants will receive this event. |
+| [ON_CALL_BEGIN](#ON_CALL_BEGIN) | Call connected event. |
+| [ON_CALL_END](#CALL_END) | Call ended. |
+| [KICKED_OUT](#KICKED_OUT) | Kicked offline. |
+| [ERROR](#ERROR) | Error information. |
+| [ON_USER_NETWORK_QUALITY_CHANGED](#ON_USER_NETWORK_QUALITY_CHANGED) | Network quality event for all users. |
+| [USER_VIDEO_AVAILABLE](#USER_VIDEO_AVAILABLE) | Event indicating whether a user has a video stream. |
+| [USER_AUDIO_AVAILABLE](#USER_AUDIO_AVAILABLE) | Event indicating whether a user has an audio stream. |
+
+## TUICallEvent Details
+``` javascript
+ import TUICallEngine, { TUICallEvent } from '@trtc/call-engine-lite-wx';
+```
+
+### ON_CALL_RECEIVED
+
+A new incoming call request event. The callee receives this event. You can listen to it to decide whether to show the call answer UI.
+``` javascript
+let handleOnCallReceived = function(event) {
+    console.log(event)
+};
+tuiCallEngine.on(TUICallEvent.ON_CALL_RECEIVED, handleOnCallReceived, this);
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|---------|---------|---------|
+| sponsor | String | The inviter. |
+| userIDList | Array\<String\> | Other users also being invited. |
+| isFromGroup | Boolean | Whether this is a group call. |
+| inviteData | Object | Call data. |
+| inviteID | String | Invitation ID, identifies a single invitation. |
+| userData | String | Extension field: extra information in the invitation signaling. |
+| callId | String | Unique ID of this call. |
+| roomID | Number | Audio/video room ID for this call. |
+| callMediaType | Number | Call media type: video call or voice call. |
+| callRole | String | Role, enum: caller or callee. |
+
+### USER_ACCEPT
+
+> **Note:**
+> **This event is deprecated in v4.x.x.**
+>
+
+When a user accepts the call, other users receive this event.
+``` javascript
+let handleUserAccept = function(event) {
+    console.log('User accepted the call')
+}
+tuiCallEngine.on(TUICallEvent.USER_ACCEPT, this.handleUserAccept, this);
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|---------|---------|---------|
+| userID | String | The user ID who accepted. |
+| userList | Array | Information about users who have not yet accepted **(will be deprecated)**. |
+
+### USER_ENTER
+
+When a user agrees to enter the call, other users receive this event.
+``` javascript
+let handleUserEnter = function(event) {
+    console.log('User entered the call')
+}
+tuiCallEngine.on(TUICallEvent.USER_ENTER, this.handleUserEnter, this);
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|---------|---------|---------|
+| userID | String | The user ID who entered the room. |
+| playerList | Array | Stream information of users in the room. |
+
+### USER_LEAVE
+
+When a user leaves the call, other users in the call receive this event.
+``` javascript
+let handleUserLeave = function(event) {
+    console.log('User left the call')
+}
+tuiCallEngine.on(TUICallEvent.USER_LEAVE, this.handleUserLeave, this);
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|---------|---------|---------|
+| userID | String | The user ID who left the room. |
+| playerList | Array | Stream information of users in the room. |
+
+### USER_UPDATE
+
+User updated.
+``` javascript
+let handleUserUpdate = function(event) {
+    console.log('User updated')
+}
+tuiCallEngine.on(TUICallEvent.USER_UPDATE, this.handleUserUpdate, this)
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|---------|---------|---------|
+| pusher | String | Updated local push stream information. |
+| playerList | Array | Updated remote users' stream information. |
+
+### REJECT
+
+Call rejected event. In a 1v1 call, only the caller receives the reject event. In a group call, all invitees can receive this event.
+``` javascript
+let handleInviteeReject = function(event) {
+    console.log('User rejected the call')
+}
+tuiCallEngine.on(TUICallEvent.REJECT, this.handleInviteeReject, this);
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|---------|---------|---------|
+| userID | String | The user ID who rejected the call. |
+| invitee | String | The user ID who rejected the call **(will be deprecated)**. |
+| inviteID | String | Invitation ID, identifies a single invitation. |
+| reason | String | "reject" indicates rejection. |
+
+### NO_RESP
+
+Invited user did not respond.
+- In a C2C call, only the initiator receives the no-response callback. For example, if A invites B and C, and B doesn't respond, A receives this callback but C does not.
+
+- In an IM group call, all invitees can receive this callback. For example, if A invites B and C, and B doesn't respond, both A and C receive this callback.
+
+   ``` javascript
+   let handleNoResponse = function(event) {
+       console.log('User did not respond')
+   }
+   tuiCallEngine.on(TUICallEvent.NO_RESP, this.handleNoResponse, this);
+   ```
+
+   **Parameters:**
+
+   | Parameter | Type | Description |
+   |---------|---------|---------|
+   | groupID | String | Group ID, unique identifier. |
+   | sponsor | String | The initiator's user ID. |
+   | userIDList | Array\<String\> | List of users who timed out without responding. |
+   | inviteID | String | Invitation ID, identifies a single invitation. |
+
+### LINE_BUSY
+
+User is busy.
+``` javascript
+let handleLineBusy = function(event) {
+    console.log('User is busy')
+}
+tuiCallEngine.on(TUICallEvent.LINE_BUSY, this.handleLineBusy, this);
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|---------|---------|---------|
+| userID | String | The busy user's ID. |
+| inviteID | String | Invitation ID, identifies a single invitation. |
+| reason | String | "line busy" indicates the user is busy. |
+
+### ON_CALL_NOT_CONNECTED
+
+**This event is thrown when the call is not established.**
+``` javascript
+let handleOnCallCanceled = function(event) {
+  console.log(event.userID);
+};
+tuiCallEngine.on(TUICallEvent.ON_CALL_CANCELED, handleOnCallCanceled, this);
+```
+
+**Parameters:**
+| Parameter | Type | Description |
+| --- | --- | --- |
+| userID | String | The user ID associated with the call cancellation. |
+| callId | String | Unique ID of this call. |
+| roomID | Number | Audio/video room ID for this call. |
+| callMediaType | Number | Call media type: video call or voice call. |
+| callRole | String | Role, enum: caller or callee. |
+| reason | Number | Reason the call was not established:<br>- 0 - Unknown.<br>- 1 - Hung up.<br>- 2 - Rejected.<br>- 3 - No response.<br>- 4 - Offline.<br>- 5 - Busy.<br>- 6 - Call cancelled.<br>- 7 - Accepted on another device.<br>- 8 - Rejected on another device.<br>- 9 - Ended by server. |
+
+### ON_CALL_BEGIN
+
+Indicates the call has been connected. Both the caller and callee can receive this event. You can listen to this event to start cloud recording, content moderation, etc.
+``` javascript
+let handleOnCallBegin = function(event) {
+    console.log(event)
+};
+tuiCallEngine.on(TUICallEvent.ON_CALL_BEGIN, handleOnCallBegin, this);
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|---------|---------|---------|
+| callId | String | Unique ID of this call. |
+| roomID | Number | Audio/video room ID for this call. |
+| callMediaType | Number | Call media type: video call or voice call. |
+| callRole | String | Role: caller or callee. |
+
+### ON_CALL_END
+
+Indicates the call has ended. Both the caller and callee can receive this event. You can listen to this event to display call duration, call type, or to stop cloud recording.
+``` javascript
+let handleCallingEnd = function(event) {
+    console.log('Call ended')
+}
+tuiCallEngine.on(TUICallEvent.ON_CALL_END, this.handleCallingEnd, this);
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|---------|---------|---------|
+| roomID | Number | Audio/video room ID for this call. Currently only numeric room IDs are supported; string room IDs will be supported in future versions. |
+| callMediaType | Number | Call media type: video call or voice call. |
+| callRole | String | Role, enum: caller ('inviter'), callee ('invitee'), unknown (''). |
+| totalTime | Number | Duration of this call in seconds. |
+| userID | String | The userID that caused the call to end. |
+| callId | String | Unique ID of this call. |
+
+### KICKED_OUT
+
+Kicked offline.
+``` javascript
+let handleKickedOut = function(event) {
+    console.log('Kicked offline')
+}
+tuiCallEngine.on(TUICallEvent.KICKED_OUT, this.handleKickedOut, this);
+```
+
+### ERROR
+
+Listen for SDK error information.
+``` javascript
+let handleError = function(event) {
+    console.log('Error information')
+}
+tuiCallEngine.on(TUICallEvent.ERROR, this.handleError, this);
+```
+
+### ON_USER_NETWORK_QUALITY_CHANGED
+
+Network quality event for all users.
+``` javascript
+let handleOnUserNetworkQualityChange = function(event) {
+  console.log(event.networkQualityList);
+};
+tuiCallEngine.on(TUICallEvent.ON_USER_NETWORK_QUALITY_CHANGED, this.handleOnUserNetworkQualityChange, this);
+```
+
+**Parameters:**
+| Parameter | Type | Description |
+| --- | --- | --- |
+| networkQualityList | Array\<Object\> | Network status. You can get the current network quality for each user by userID. Example: `networkQualityList: [{ userId: quality }]`.<br>**Network quality levels:**<br>- quality = 0: Network status unknown.<br>- quality = 1: Excellent network.<br>- quality = 2: Good network.<br>- quality = 3: Average network.<br>- quality = 4: Poor network.<br>- quality = 5: Very poor network.<br>- quality = 6: Network disconnected. |
+
+### USER_VIDEO_AVAILABLE
+
+During a video call, when a user enables/disables their camera, other users in the call receive this event. For example: A and B are in a video call, when A enables/disables their camera, B receives this event.
+``` javascript
+let handleUserVideoChange = function(event) {
+  console.log(event.userID, event.isVideoAvailable);
+};
+tuiCallEngine.on(TUICallEvent.USER_VIDEO_AVAILABLE, handleUserVideoChange);
+```
+
+**Parameters:**
+| Parameter | Type | Description |
+| --- | --- | --- |
+| userID | String | The user ID who enabled/disabled their camera. |
+| isVideoAvailable | Boolean | - true: user enabled camera.<br>- false: user disabled camera. |
+
+### USER_AUDIO_AVAILABLE
+
+During an audio/video call, when a user enables/disables their microphone, other users in the call receive this event. For example: A and B are in a call, when A enables/disables their microphone, B receives this event.
+``` javascript
+let handleUserAudioChange = function(event) {
+  console.log(event.userID, event.isAudioAvailable);
+};
+tuiCallEngine.on(TUICallEvent.USER_AUDIO_AVAILABLE, handleUserAudioChange);
+```
+
+**Parameters:**
+| Parameter | Type | Description |
+| --- | --- | --- |
+| userID | String | The user ID who enabled/disabled their microphone. |
+| isAudioAvailable | Boolean | - true: user enabled microphone.<br>- false: user disabled microphone. |

package/resource/knowledge/callkit/faq/uniapp-miniprogram.md

@@ -0,0 +1,204 @@
+## How to switch the logged-in userId?
+
+First call `destroyed` to clean up the instance and log out, then call `init` to reinitialize and log in.
+
+## Common issues and solutions for Vue2 and Vue3 mini program package size
+
+### Is code compression enabled?
+
+Using the [TUICallKit-Vue2 demo](https://github.com/tencentyun/TUICallKit/tree/main/uni-app/TUICallKit-Miniprogram/TUICallKit-Vue2) as an example, the following comparison shows the effect of checking **Compress code at runtime** (**851KB -> 454KB, reduced by 50%**):
+
+Steps: In HBuilder, go to **Run** > **Run to Mini Program Simulator** > check **Compress code at runtime**.
+
+[≤ v1.4.4]
+
+### How to prevent dependency packages from being bundled into the main package's `common/vendor.js`?
+
+When using **Build npm** in **WeChat DevTools**, we want HBuilder to avoid bundling dependencies from `node_modules` into the main package's `common/vendor.js` (**this causes duplicate dependencies and increases the main package size**).
+
+[Vue2]
+
+It is recommended to configure this via `vue.config.js`.
+- The optional `vue.config.js` config file should be placed in the project root directory.
+
+- `vue.config.js` is typically used to configure `webpack` and other build options. When HBuilder uses Vue2 to develop mini programs, `vue.config.js` is automatically loaded during build and packaging.
+
+Using the [TUICallKit-Vue2 demo](https://github.com/tencentyun/TUICallKit/tree/main/uni-app/TUICallKit-Miniprogram/TUICallKit-Vue2) as an example, the following comparison shows the effect of excluding dependencies from the main package's `common/vendor.js` (**805KB -> 256KB, reduced by 68%**):
+
+Steps:
+1. Import package dependencies in pages using `require`:
+
+``` javascript
+// Page imports MUST use require, NOT import
+const TIM = require('tim-wx-sdk');
+```
+2. Configure `vue.config.js` as follows:
+
+``` javascript
+// vue.config.js configuration
+module.exports = {
+  configureWebpack: {
+      externals: {
+          'tim-wx-sdk': 'commonjs tim-wx-sdk', // ~550KB
+      },
+  }
+}
+```
+
+> **Note:**
+> **Page dependency imports MUST use require, NOT import!**
+>
+> Reason: When using `import`, HBuilder compiles the import statements during mini program packaging, which prevents using `tim-wx-sdk` from `node_modules`. The `require` approach is not compiled.
+>
+
+### How to build npm?
+1. Based on communication with uni-app technical staff, HBuilder currently does not support a **Build npm** feature like **WeChat DevTools**. They have no plans to support it.
+
+To use **WeChat DevTools > Tools > Build npm**, you must create `package.json` and run `npm install` in the **WeChat DevTools terminal** first. Only then can you **Build npm**:
+
+``` bash
+npm init -y && npm install xx
+```
+
+### How to use `copy-webpack-plugin` to improve efficiency?
+
+In section [3. How to build npm](#e999cfb9-07ef-4a7c-b32c-acf55caaac6b) above, you need to create `package.json` in the WeChat DevTools terminal and install dependencies. Using `copy-webpack-plugin` can reduce this step and improve efficiency.
+
+Using the [TUICallKit-Vue2 demo](https://github.com/tencentyun/TUICallKit/tree/main/uni-app/TUICallKit-Miniprogram/TUICallKit-Vue2) as an example:
+
+Steps:
+1. Install `copy-webpack-plugin`:
+
+   > **Note:**
+   >
+   > **The latest version of copy-webpack-plugin is not compatible. v5.0.0 is recommended (lock the version)**
+   >
+
+``` javascript
+npm install -D copy-webpack-plugin@5.0.0
+```
+2. Use the `copy-webpack-plugin` plugin in `vue.config.js`:
+
+``` javascript
+// vue.config.js configuration
+const path = require('path');
+const CopyWebpackPlugin = require('copy-webpack-plugin');
+module.exports = {
+  configureWebpack: {
+      plugins: [
+          new CopyWebpackPlugin([
+              {
+                  from: path.join(__dirname, '/node_modules/@tencentcloud/call-uikit-wechat'),
+                  to: path.join(__dirname, '/unpackage/dist/dev/mp-weixin/node_modules/@tencentcloud/call-uikit-wechat')
+              },
+              {
+                  from: path.join(__dirname, '/node_modules/trtc-wx-sdk'),
+                  to: path.join(__dirname, '/unpackage/dist/dev/mp-weixin/node_modules/trtc-wx-sdk')
+              },
+              {
+                  from: path.join(__dirname, '/node_modules/tim-wx-sdk'),
+                  to: path.join(__dirname, '/unpackage/dist/dev/mp-weixin/node_modules/tim-wx-sdk')
+              },
+              {
+                  from: path.join(__dirname, '/node_modules/tsignaling-wx'),
+                  to: path.join(__dirname, '/unpackage/dist/dev/mp-weixin/node_modules/tsignaling-wx')
+              },
+              {
+                  from: path.join(__dirname, '/node_modules/tuicall-engine-wx'),
+                  to: path.join(__dirname, '/unpackage/dist/dev/mp-weixin/node_modules/tuicall-engine-wx')
+              },
+              {
+                  from: path.join(__dirname, '/package.json'),
+                  to: path.join(__dirname, '/unpackage/dist/dev/mp-weixin/package.json')
+              }
+          ])
+      ]
+  }
+}
+```
+
+[Vue3]
+
+No `vite.config.js` configuration is needed. Just use `require` to import:
+``` javascript
+// Page imports MUST use require, NOT import
+const TIM = require('tim-wx-sdk');
+```
+
+For reference: [TUICallKit-Vue3 demo](https://github.com/tencentyun/TUICallKit/tree/main/uni-app/TUICallKit-Miniprogram/TUICallKit-Vue3).
+
+### How to build npm?
+1. Based on communication with uni-app technical staff, HBuilder currently does not support a **Build npm** feature like **WeChat DevTools**. They have no plans to support it.
+
+To use **WeChat DevTools > Tools > Build npm**, you must create `package.json` and run `npm install` in the **WeChat DevTools terminal** first:
+
+``` javascript
+npm init -y && npm install tuicall-engine-wx@1.5.6
+```
+
+## Vue2 uni-app packaged WeChat mini program — no ringtone sound?
+
+This is because in Vue2, uni-app packaging encodes ringtone files as base64, which is not supported by the ringtone playback API.
+
+Follow these steps to resolve:
+- Step 1: In your project's `TUICallKit` source code, modify the ringtone import method.
+
+   ``` javascript
+   // Replace ringtone file import with the following code
+   import CALLER_BELL from '../assets/phone_dialing.mp3';
+   import CALLEE_BELL from '../assets/phone_ringing.mp3';
+   console.debug(CALLEE_BELL, CALLER_BELL);
+   let DEFAULT_CALLER_BELL_FILEPATH = '/assets/phone_dialing.mp3';
+   let DEFAULT_CALLEE_BELL_FILEPATH = '/assets/phone_ringing.mp3';
+   ```
+
+- Step 2: Modify the `vue.config.js` file in your project.
+
+   ``` javascript
+   // Inside chainWebpack(config)
+   config.module
+         .rule('mp3')
+         .test(/\.mp3$/)
+         .use('file-loader')
+         .loader('file-loader')
+         .options({
+           esModule: false,
+           name: 'assets/[name].[ext]'
+         })
+         .end();
+   ```
+
+## What are SDKAppID and SecretKey?
+- **SDKAppID**: The IM application ID, used for business isolation. Different SDKAppIDs cannot communicate with each other.
+
+- **SecretKey**: The IM application secret key. Must be used together with SDKAppID to generate the authentication ticket UserSig for legitimate use of IM services.
+
+## What is UserSig and how to generate it?
+- UserSig is the password for logging into Instant Messaging (IM). It is essentially ciphertext obtained by encrypting information such as the UserID.
+
+- The recommended approach is to integrate the UserSig calculation code on your server side and provide a project-facing API. When UserSig is needed, your project requests a dynamic UserSig from the business server. For more details, see [Server-side UserSig Generation](https://cloud.tencent.com/document/product/269/32688#GeneratingdynamicUserSig).
+
+## How to handle TUICallKit TypeScript validation errors?
+
+[.eslintignore]
+``` plaintext
+TUICallKit
+```
+
+[tsconfig.json]
+``` json
+{
+  "compilerOptions": {
+      "noImplicitAny": true
+   }
+}
+```
+
+## How to disable beauty filters?
+- Web: Beauty filters are disabled by default.
+
+- Mini Program: Call the [setBeautyLevel API](https://cloud.tencent.com/document/product/647/78761#setBeautyLevel) with parameter 0 to disable the default beauty filter.
+
+   ``` javascript
+   TUICallKitServer.getTUICallEngineInstance().setBeautyLevel(0);
+   ```