@tencent-rtc/mcp 1.7.2 → 1.7.4

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

@@ -0,0 +1,243 @@
+This guide walks you through quickly integrating the TUICallKit component into a uni-app project and running on **Android** and **iOS** platforms. You can complete the following key steps in about 10 minutes and get a fully functional audio/video calling interface.
+
+## Prerequisites
+
+### Development Environment Requirements
+- It is recommended to use **HBuilderX 4.31** or later for development.
+- iOS: iOS 13.0 or later.
+- Android: Android 5.0 (SDK API Level 21) or later.
+- The mini program dev tool does not support native components (i.e., `<live-pusher>` and `<live-player>` tags). You need to run and test on a **real device**.
+- For running on a real device, first install the [uni-app native runtime app](https://nativesupport.dcloud.net.cn/AppDocs/usesdk/appkey.html#%E7%AC%AC%E4%B8%80%E6%AD%A5-%E7%94%B3%E8%AF%B7appkey) base, or make a custom base.
+
+### 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.
+
+## TUICallKit Source Code Integration
+
+### Step 1: Create a uni-app Project
+
+Create a uni-app project in HBuilderX.
+1. Open HBuilderX editor.
+2. Create a project via **File** > **New** > **Project**. Set the project name, select the default template, and click Create.
+
+### Step 2: Download and Import the TUICallKit Component
+1. Download the `TUICallKit` component to your local project directory.
+
+   ``` bash
+   npm i @tencentcloud/call-uikit-uniapp
+   ```
+
+   > **Note:**
+   >
+   > Run the npm command in the root directory of your uni-app project.
+   >
+
+2. Copy the `TUICallKit` folder (from `node_modules/@tencentcloud/call-uikit-uniapp/`) to your project root directory.
+
+### Step 3: Import Required Native Plugins
+
+To use TUICallKit on Android and iOS platforms, you need to import the required native plugins.
+
+1. In [DCloud Plugin Market](https://ext.dcloud.net.cn/), search for and purchase the following native plugins:
+   - [Tencent Cloud Native Chat Plugin](https://ext.dcloud.net.cn/plugin?id=7571)
+   - [Tencent Cloud Native Audio/Video Call Plugin](https://ext.dcloud.net.cn/plugin?id=7096)
+
+2. After purchase, go to the HBuilderX project, click **manifest.json** > **App Native Plugin Configuration** > **Cloud Plugin** > **Select Cloud Plugin**, and select the two plugins purchased above.
+
+   > **Note:**
+   >
+   > After purchasing native plugins, you must make a **custom debug base** to use the native plugin capabilities. The standard base does not include special native plugins.
+   >
+
+### 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 `pages.json` file to set the page to full-screen mode.
+
+   ``` json
+   {
+     "pages": [
+       {
+         "path": "pages/index/index",
+         "style": {
+           "navigationStyle": "custom",
+           "app-plus": {
+             "titleNView": false
+           }
+         }
+       }
+     ]
+   }
+   ```
+
+2. Open the `pages/index/index.vue` file and add the following code.
+
+   ``` html
+   <template>
+     <view class="container">
+       <TUICallKit ref="TUICallKit" />
+       <view class="input-box">
+         <input
+           type="text"
+           maxlength="20"
+           :placeholder="isLogin ? 'Enter callee userID' : 'Enter login userID'"
+           :value="userID"
+           @input="bindInputUserID"
+         />
+       </view>
+       <view class="btn-box">
+         <button @tap="isLogin ? call() : login()">
+           {{ isLogin ? 'Call' : 'Login' }}
+         </button>
+       </view>
+     </view>
+   </template>
+
+   <script>
+   import TUICallKit from '../../TUICallKit/TUICallKit.vue';
+   import * as GenerateTestUserSig from '../../TUICallKit/debug/GenerateTestUserSig-es.js';
+
+   export default {
+     components: { TUICallKit },
+     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,
+         });
+         try {
+           await this.$refs.TUICallKit.init({
+             sdkAppID: SDKAppID,
+             userID,
+             userSig,
+           });
+           uni.showToast({ title: 'Login successful' });
+           this.isLogin = true;
+           this.userID = '';
+         } catch (error) {
+           uni.showToast({ title: 'Login failed', icon: 'error' });
+         }
+       },
+       async call() {
+         try {
+           await this.$refs.TUICallKit.calls({
+             userIDList: [this.userID],
+             type: 2,
+           });
+         } catch (error) {
+           uni.showToast({ title: 'Call failed', icon: 'error' });
+         }
+       },
+     },
+   };
+   </script>
+
+   <style>
+   .container {
+     display: flex;
+     flex-direction: column;
+     align-items: center;
+     justify-content: center;
+     height: 100vh;
+   }
+   .input-box {
+     width: 80%;
+     margin-bottom: 20px;
+   }
+   .btn-box {
+     width: 80%;
+   }
+   button {
+     background-color: #006eff;
+     color: white;
+     border-radius: 25px;
+   }
+   </style>
+   ```
+3. You must use **Vue 2** for compilation. Currently, **Vue 3** is not supported.
+
+### Step 6: Build and Run
+1. Make a custom base (for real-device testing):
+   - In HBuilderX, click **Run** > **Run to Phone or Simulator** > **Make Custom Debug Base**.
+   - Wait for the build to complete and the custom base to be installed on the device.
+
+2. Run on a real device:
+   - Click **Run** > **Run to Phone or Simulator** and select your connected device.
+   - Select **Use Custom Base** for debugging.
+
+3. Expected result after quick integration.
+
+### Step 7: Make Your First Call
+- Prepare two devices. Device A logs in with user "userA" and Device B logs in with user "userB".
+- Device A enters "userB" as the callee and clicks the Call button. Device B will see an incoming call UI.
+- Device B clicks the accept button to start the audio/video call.
+
+   > **Note:**
+   >
+   > The first time you run the app, you need to grant camera and microphone permissions.
+   >
+
+## More Features
+
+### Set Nickname and Avatar
+
+Call the `setSelfInfo` API to set the current user's nickname and avatar:
+
+``` javascript
+this.$refs.TUICallKit.setSelfInfo({
+  nickName: 'Tom',
+  avatar: 'https://...'
+})
+```
+
+### Set Custom Ringtone
+
+Call the `setCallingBell` API to set a custom incoming call ringtone:
+
+``` javascript
+this.$refs.TUICallKit.setCallingBell('/static/bell.mp3')
+```
+
+> **Note:**
+> Only local file paths are accepted. The ringtone setting is device-bound and persists across user switches. Pass an empty string to restore the default ringtone.
+
+### Enable Mute Mode
+
+Call the `enableMuteMode` API to enable mute mode (no ringtone on incoming calls):
+
+``` javascript
+this.$refs.TUICallKit.enableMuteMode(true)
+```
+
+### Enable Floating Window
+
+Call the `enableFloatWindow` API to enable the floating window feature:
+
+``` javascript
+this.$refs.TUICallKit.enableFloatWindow(true)
+```
+
+## FAQ
+
+### Why does the call UI not appear after running?
+1. Ensure you are running on a **real device** rather than a simulator. Native components like `<live-pusher>` and `<live-player>` are not supported in simulators.
+2. Ensure you have made a **custom debug base** that includes the required native plugins.
+3. Check that camera and microphone permissions have been granted.
+
+### What should I do if the native plugin is not found?
+1. Verify that you have purchased the plugins from the DCloud Plugin Market.
+2. Ensure the plugins are selected in **manifest.json** > **App Native Plugin Configuration**.
+3. Rebuild the custom debug base after adding plugins.

package/resource/knowledge/chat/best-practice/common/web-sdk-log-level.md

@@ -0,0 +1,76 @@
+---
+title: Web Chat SDK Disabling/Adjusting Local Browser Log Output (setLogLevel)
+product: chat
+frameworks: [web, miniprogram]
+scope: platform_common
+tags: [setLogLevel, log, log level, disable log, local log, browser log, console log, release, production, create, initialization log]
+version_range: ">=3.0.0"
+---
+
+# Web Chat SDK Disabling/Adjusting Local Browser Log Output (setLogLevel)
+
+## 1. Key Conclusions
+
+- Use `chat.setLogLevel(level)` to control the SDK's local log output level. Setting `level` to `4` disables all SDK log printing.
+- `setLogLevel` must be called **after** the `chat` instance is created via `create`.
+- `setLogLevel` only affects logs produced **after** the call succeeds; initialization logs printed before the call cannot be suppressed. This is expected behavior by design.
+- For production, it is recommended to set the level to `1` (release) so that only critical information is printed, rather than setting it to `4` to disable all logs, in order to retain the diagnostic clues needed for troubleshooting.
+
+## 2. Field/Capability Reference
+
+| Field/Capability | Purpose | Notes |
+|---|---|---|
+| `chat.setLogLevel(level)` | Sets the local log level | Must be called after the instance is created via `create` |
+| `level = 0` | Normal level | Verbose output; recommended during integration and debugging |
+| `level = 1` | Release level | Prints only critical information; recommended for production |
+| `level = 2` | Warning level | Prints only warning- and error-level logs |
+| `level = 3` | Error level | Prints only error-level logs |
+| `level = 4` | No-log level | Prints no logs (fully disabled) |
+
+## 3. Mechanism/Sequence
+
+`create` creates the `chat` instance -> the SDK prints initialization logs (these logs are not controlled by `setLogLevel`) -> call `chat.setLogLevel(level)` -> from the moment the call succeeds, log output is filtered according to the configured level.
+
+## 4. Standard Usage
+
+1. Call `create` to create the `chat` instance.
+2. Immediately call `chat.setLogLevel(level)` with the target level (pass `4` to disable all logs; pass `1` to keep critical information in production).
+3. To use different levels across environments, set the corresponding `level` after initialization based on your environment variables.
+
+``` javascript
+// Set the log level immediately after creating the instance
+const chat = TencentCloudChat.create({ SDKAppID });
+
+// Disable all local SDK logs
+chat.setLogLevel(4);
+
+// Or: keep only critical information in production
+// chat.setLogLevel(1);
+```
+
+## 5. Result Verification
+
+- After setting `level = 4`, no SDK logs appear in the browser console for output produced after the `setLogLevel` call succeeds.
+- After setting `level = 1`, only critical information is printed; warning and normal logs are filtered out.
+- Initialization logs between `create` and `setLogLevel` still appear. This is expected behavior.
+
+## 6. Common Pitfalls
+
+- Pitfall 1: Expecting `setLogLevel(4)` to also clear initialization logs (logs printed before the call cannot be suppressed).
+- Pitfall 2: Calling `setLogLevel` before `create` (it only takes effect when called after the instance is created).
+- Pitfall 3: Setting `4` directly in production to disable all logs, leaving no logs to investigate online issues (use `1` to retain critical information).
+
+## 7. Problem Definition (Retrieval Aid, Minimal)
+
+How to disable or adjust local (console) browser log output for the Web/Mini Program Chat SDK.
+
+## 8. Synonymous Phrasing Coverage (Retrieval Recall, Minimal)
+
+- How do I disable local browser logs in the web IM SDK?
+- What does each `chat.setLogLevel` level mean?
+- How should I set the IM SDK log level in production?
+- Why are initialization logs still printed after I called setLogLevel?
+
+## 9. References (Optional)
+
+- Web Chat SDK setLogLevel API reference: `https://web.sdk.qcloud.com/im/doc/v3/en/SDK.html#setLogLevel`

package/resource/knowledge/chat/best-practice/miniprogram/desktop-wechat-miniprogram-error.md

@@ -0,0 +1,79 @@
+---
+title: IM SDK Errors When Running in Desktop WeChat Mini Program (tencent_cloud_im_csig_flutter_for_web_25F_cy is undefined / WebSocket is not a constructor) and the Upgrade Fix
+product: chat
+frameworks: [miniprogram]
+scope: platform_specific
+tags: [desktop WeChat, mac WeChat 4.x, windows WeChat 3.9.x, uniapp mini program, WeChat native mini program, WebSocket is not a constructor, tencent_cloud_im_csig, cannot read properties of undefined, tim-wx-sdk, "@tencentcloud/chat", "@tencentcloud/lite-chat", v2, v3, v4, version upgrade, compatibility]
+version_range: ">=3.5.7"
+---
+
+# IM SDK Errors When Running in Desktop WeChat Mini Program (csig undefined / WebSocket is not a constructor) and the Upgrade Fix
+
+## 1. Key Conclusions
+
+- The root cause is that the underlying API attributes of desktop WeChat (mac 4.x / windows 3.9.x) mini programs have changed, causing the IM SDK to misidentify its runtime environment.
+- The two errors are different symptoms of the same root cause: a WeChat mini program packaged with uniapp reports `cannot read properties of undefined (reading 'tencent_cloud_im_csig_flutter_for_web_25F_cy')`; a WeChat native mini program reports `TypeError: WebSocket is not a constructor`.
+- This issue has been handled for compatibility in both IM SDK v3 (`3.5.7`) and v4 (`4.2.4`). Upgrading to the latest release of the corresponding major version fixes it.
+- v2/v3/v4 interfaces are backward compatible and allow smooth migration, but v3 and v4 each contain breaking changes. Assess that there is no risk to your business before upgrading.
+
+## 2. Field/Capability Reference
+
+| Field/Capability | Purpose | Notes |
+|---|---|---|
+| `tim-wx-sdk` | v2 package name | Legacy version; upgrading to the latest v4 is recommended |
+| `@tencentcloud/chat` | v3 package name | Issue fixed (`>=3.5.7`); v3 no longer receives new features |
+| `@tencentcloud/lite-chat` | v4 package name | Issue fixed (`>=4.2.4`); recommended version |
+| Missing `tencent_cloud_im_csig...` attribute | uniapp mini program error signal | Undefined due to changed underlying API attributes in desktop WeChat |
+| `WebSocket is not a constructor` | Native mini program error signal | Desktop WeChat runtime misidentified; constructor unavailable |
+
+## 3. Mechanism/Sequence
+
+Desktop WeChat is upgraded (mac 4.x / windows 3.9.x) -> the underlying mini program API attributes change -> the IM SDK misidentifies its runtime environment -> a uniapp-packaged mini program hits undefined when reading the `tencent_cloud_im_csig...` attribute (reporting `cannot read properties of undefined`) or a native mini program fails to construct `WebSocket` (reporting `WebSocket is not a constructor`) -> after upgrading to v3 (`>=3.5.7`) or v4 (`>=4.2.4`) with compatibility handling, the SDK correctly identifies the desktop WeChat runtime and the error disappears.
+
+## 4. Standard Usage
+
+1. Confirm your current IM SDK version and package name: v2 (`tim-wx-sdk`) / v3 (`@tencentcloud/chat`) / v4 (`@tencentcloud/lite-chat`).
+2. Choose the upgrade target based on your current version:
+   - Currently v4 (`@tencentcloud/lite-chat`): upgrade to the latest v4 release.
+   - Currently v3 (`@tencentcloud/chat`): upgrade to the latest v3 release (v3 no longer receives new features), or upgrade to the latest v4 release.
+   - Currently v2 (`tim-wx-sdk`): upgrade to the latest v4 release.
+3. Before upgrading, read the corresponding migration guide and assess the impact of breaking changes on your business:
+   - v3 breaking changes: `https://web.sdk.qcloud.com/im/doc/v3/en/tutorial-07-breakingchanges.html`
+   - v2 to v3 guide: `https://web.sdk.qcloud.com/im/doc/v3/en/tutorial-05-integration.html`
+   - v4 breaking changes: `https://web.sdk.qcloud.com/im/doc/v3/en/tutorial-04-comparison-v4.html`
+   - v3 to v4 guide: `https://web.sdk.qcloud.com/im/doc/v3/en/tutorial-03-integration-v4.html`
+4. Complete the upgrade and verify via regression: rerun the uniapp mini program and the WeChat native mini program on desktop WeChat (mac 4.x / windows 3.9.x) and confirm the errors no longer occur.
+
+## 5. Result Verification
+
+- After upgrading to v3 (`>=3.5.7`) or v4 (`>=4.2.4`), the uniapp mini program on desktop WeChat no longer reports `cannot read properties of undefined (reading 'tencent_cloud_im_csig...')`.
+- The WeChat native mini program no longer reports `TypeError: WebSocket is not a constructor`.
+- The IM SDK initializes and establishes a connection normally in the desktop WeChat runtime.
+
+## 6. Common Pitfalls
+
+- Pitfall 1: Assuming it is a uniapp packaging configuration or business code bug (it is actually an SDK environment-identification issue caused by changed underlying desktop WeChat API attributes).
+- Pitfall 2: Considering it resolved after verifying only on mobile WeChat (the issue only appears on desktop WeChat mac 4.x / windows 3.9.x).
+- Pitfall 3: Upgrading across versions without reading breaking changes (v3 and v4 each have breaking changes; assess business impact first).
+- Pitfall 4: Confusing package names (v3 is `@tencentcloud/chat`, v4 is `@tencentcloud/lite-chat`, v2 is `tim-wx-sdk`).
+
+## 7. Problem Definition (Retrieval Aid, Minimal)
+
+When running the IM SDK in a uniapp-packaged WeChat mini program or a WeChat native mini program on desktop WeChat (mac 4.x / windows 3.9.x), it reports the csig attribute as undefined or `WebSocket is not a constructor`.
+
+## 8. Synonymous Phrasing Coverage (Retrieval Recall, Minimal)
+
+- What should I do when the desktop WeChat mini program IM SDK reports WebSocket is not a constructor?
+- Why does a uniapp mini program report tencent_cloud_im_csig undefined on mac/windows WeChat?
+- IM initialization fails when running a mini program on Windows 3.9 / Mac 4.x WeChat?
+- Which version should the IM SDK be upgraded to in order to fix desktop WeChat compatibility?
+- How to resolve the missing native WebSocket constructor in the AppService logic layer of the PC WeChat mini program?
+- On PC, tim-im app-service.js reports WebSocket is not a constructor?
+- The mini program logic layer has no native WebSocket constructor / the WebSocket constructor is unavailable?
+
+## 9. References (Optional)
+
+- v3 breaking changes: `https://web.sdk.qcloud.com/im/doc/v3/en/tutorial-07-breakingchanges.html`
+- v2 to v3 guide: `https://web.sdk.qcloud.com/im/doc/v3/en/tutorial-05-integration.html`
+- v4 breaking changes: `https://web.sdk.qcloud.com/im/doc/v3/en/tutorial-04-comparison-v4.html`
+- v3 to v4 guide: `https://web.sdk.qcloud.com/im/doc/v3/en/tutorial-03-integration-v4.html`