@tencent-rtc/mcp 1.6.3 → 1.6.5

package/resource/integration/livekit/preset/live/ios/prepare-integration.md

@@ -0,0 +1,204 @@
+## Feature Overview
+
+**TUILiveKit** is a comprehensive live-streaming component. Once integrated, it allows you to quickly implement the following key functional modules for your Android application:
+
+|**Host Prepare Page**|**Host Streaming Page**|**Live Stream List**|**Audience Viewing Page**|
+|---------|---------|---------|---------|
+|||||
+
+## **Preparations**
+
+### Activate Service
+
+Before using **TUILiveKit**, please refer to Activate Service to get the TUILiveKit trial version or activate the paid version.
+
+### Environment Requirements
+- **Xcode**: Requires **Xcode 15** or a later version.
+
+- **iOS**: Supports devices running **iOS 14.0** or a later version.
+
+- **CocoaPods environment**: A CocoaPods environment must be installed. If you haven't installed it, please refer to the [CocoaPods installation guide](https://guides.cocoapods.org/using/getting-started.html), or follow these steps:
+
+  - **Install CocoaPods using gem**: execute the `sudo gem install cocoapods` command in the terminal to install.
+
+      > **Note:**
+      >
+      > During the `sudo gem install cocoapods` installation process, you may be prompted to enter your computer's password. Enter the administrator password as prompted.
+      >
+
+## Code Integration
+
+### Step 1. Import Components Via CocoaPods
+1. **Add Pod dependency:**
+
+  - **If your project already has a Podfile.**
+
+      Add the `pod 'TUILiveKit'` dependency in your project's `Podfile` file. For example:
+
+      ``` ruby
+        target 'YourProjectTarget' do
+          # Other existing Pod dependencies...
+          # Add pod 'TUILiveKit' dependency
+          pod 'TUILiveKit'
+
+        end
+      ```
+  - **If your project does not have a Podfile.**
+
+      Switch to your **.xcodeproj** directory using the `cd` command in the terminal, then execute pod init to create the **Podfile**. After creation, add the `pod 'TUILiveKit'` dependency to your **Podfile**. For example:
+
+      ``` bash
+      # If your project directory is /Users/yourusername/Projects/YourProject
+
+      # 1. cd to your .xcodeproj project directory
+      cd /Users/yourusername/Projects/YourProject
+
+      # 2. Execute pod init. This command will generate a Podfile in your project directory.
+      pod init
+
+      # 3. Add pod 'TUILiveKit' dependency in the generated Podfile file
+        target 'YourProjectTarget' do
+          # Add pod 'TUILiveKit' dependency
+          pod 'TUILiveKit'
+
+        end
+      ```
+2. **Install components**:
+
+   `cd` to the directory containing the **Podfile** in the terminal, then execute the following command to install the component.
+
+   ``` bash
+   pod install
+   ```
+
+### Step 2. Project Configuration (Device Permissions)
+
+To use the audio/video features, your application needs to obtain permissions for the microphone and camera. Please add the following two entries to your application's `Info.plist` file, and provide corresponding usage descriptions. These descriptions will be displayed to the user when the system requests permission:
+``` bash
+<key>NSCameraUsageDescription</key>
+<string>TUILiveKit needs camera access to enable video recording with picture</string>
+<key>NSMicrophoneUsageDescription</key>
+<string>TUILiveKit needs microphone permission to enable sound in recorded videos</string>
+```
+
+## Complete Login
+
+After code integration, the next step is to complete the login. All **TUILiveKit** features require a successful login to function properly, so ensure your parameters are configured correctly.
+
+> **Note:**
+>
+> In the example code, the login API is called directly. However, in a real-world application, it is highly recommended that you call the **TUILiveKit** login service only after your own user authentication and other internal login processes are complete. This prevents potential business logic confusion or data inconsistency caused by calling the login service too early, and it better aligns with your existing user management system.
+>
+
+【Swift】
+``` swift
+//
+//  AppDelegate.swift
+//
+
+// 1. Import AtomicXCore
+import AtomicXCore
+
+// 2. The example code completes login in didFinishLaunchingWithOptions. Recommendation for you: call the login service after completing your own login service.
+func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
+
+    // 3. Call the login API
+    LoginStore.shared.login(sdkAppID: 1400000001,                 // replace with the SDKAppID from the service console
+                            userID: "denny",                      // replace with your UserID
+                            userSig: "xxxxxxxxxxx") { [weak self] result in
+// You can calculate a UserSig in the console and fill it in this location
+      print("login success")
+
+        guard let self = self else { return }
+        switch result {
+        case .success():
+            print("login success")
+        case .failure(let err):
+            print("login failed. code: \(err.code), error:\(err.message)")
+        }
+    }
+
+    return true
+}
+```
+
+**Login API Parameter Description**
+| Parameter | Type | Description |
+| --- | --- | --- |
+| SDKAppID | Int | Get this from <a href="https://console.trtc.io/app">TRTC console > Application management</a>. |
+| UserID | String | The unique ID for the current user. Must contain only English letters, numbers, hyphens, and underscores. |
+| userSig | String | A ticket for Tencent Cloud authentication. Please note:<br>- <strong>Development Environment</strong>: You can use the local <code>GenerateTestUserSig.genTestSig</code> function to generate a UserSig or generate a temporary UserSig via the <a href="https://console.trtc.io/usersig">UserSig Generation Tool</a>.<br>- <strong>Production Environment</strong>: To prevent key leakage, you must use a server-side method to generate UserSig. For details, see Generating UserSig on the Server.<br>For more information, see <a href="https://www.tencentcloud.com/document/product/647/35166">How to Calculate and Use UserSig</a>. |
+
+## Handling Login Exceptions (Optional)
+
+`LoginStore` offers login status callbacks to help you handle exceptions, including "**Kicked Offline**" and "**Signature Expired"**:
+- **Kicked Offline**: If a user is kicked offline while logged in, the SDK triggers the onKickedOffline callback. Prompt the user in your UI and call LoginStore.shared.login to re-login.
+
+- **Signature Expired:** If the onUserSigExpired callback is triggered, the user's userSig has expired. If their login state is still valid on your backend, request a new userSig and call LoginStore.shared.login to refresh their login.
+
+【Swift】
+``` java
+// YourLoginService represents the business module responsible for login
+class YourLoginService: NSObject {
+    private var cancelableSet: Set<AnyCancellable> = []
+
+    // Listen to login status callback
+    func subscribeLoginStatus() {
+        LoginStore.shared.loginEventPublisher
+            .receive(on: RunLoop.main)
+            .sink { [weak self] loginEvent in
+                guard let self = self else { return }
+                switch loginEvent {
+                case .kickedOffline:   // User kicked offline callback
+                     // Your business code: UI prompt user, then log in again
+                    break
+                case .loginExpired:    // User signature expired callback
+                     // Your business code: If the current user is still logged in on your backend,
+                     // you can have your app request a new userSig from your backend and call LoginStore.shared.login to renew the login status.
+                   break
+                default:
+                    break
+                }
+            }
+            .store(in: &self.cancelableSet)
+    }
+}
+```
+
+## Next Steps
+
+Congratulations! You have successfully integrated the **TUILiveKit** component and completed the login. You can now implement features such as host streaming, viewer watching, and the live stream list. Please refer to the table below for integration guides:
+| <strong>Feature</strong> | <strong>Description</strong> | <strong>Integration Guide</strong> |
+| --- | --- | --- |
+| <strong>Video Live Streaming</strong> | Includes a full suite of features such as host broadcasting, audience viewing, interactive co-hosting, beauty filters, gifts, and bullet chat. | - Host Broadcasting<br>- Audience Viewing |
+| <strong>Voice Chat Room</strong> | Includes complete business logic such as mic seat management, background music (BGM), gift interactivity, and voice room control. | - Host Broadcasting<br>- Audience Viewing |
+| <strong>Live Stream List</strong> | Display the live stream list interface and features, including the live stream list and room information display. | - Live Stream List |
+
+## FAQs
+
+### After executing pod install, why can't I find the latest version of TUILiveKit locally?
+
+If you are unable to install the latest version of TUILiveKit, please follow these steps:
+1. In the directory where the **Podfile** is located, delete `Podfile.lock` and `Pods`. You can choose to delete them manually or execute the following command in the terminal:
+
+   ``` bash
+   // cd to the directory where Podfile is located
+
+   rm -rf Pods/
+   rm Podfile.lock
+   ```
+2. In the directory where Podfile is located, execute `pod install --repo-update`
+
+   ``` bash
+   // cd to the directory where Podfile is located
+
+   pod install --repo-update
+   ```
+
+### Do I need to call the login method every time I enter a room?
+
+No. You usually only need to complete one `TUILogin.login` call. We recommend associating `TUILogin.login` and `TUILogin.logout` with your own application's login business logic.
+
+### Is there a sample configuration for the Podfile that I can refer to?
+
+You can refer to the [GitHub TUILiveKit Example](https://github.com/Tencent-RTC/TUIKit_iOS/blob/main/application/Podfile) project `Podfile` sample file.

package/resource/integration/livekit/preset/live/vue/live-list-integration.md

@@ -37,7 +37,6 @@ Create a **live-list.vue** file in your project and add the following code to em
 
 > **Note:**
 >
-
 > You can copy the code below directly into your project, or check the [Live Stream List](https://github.com/Tencent-RTC/TUILiveKit/blob/main/Web/web-vite-vue3/src/TUILiveKit/LiveListView.vue) for the full source code.
 >
 
@@ -84,7 +83,6 @@ onMounted(async () => {
 
 > **Note:**
 >
-
 > To enable navigation from the Live Stream List to a specific live room, see the Specify Live Room section below.
 >
 
@@ -96,7 +94,6 @@ After running the following command, open your browser and visit your local addr
 
 > **Tip:**
 >
-
 > Once the command completes, enter your local address in the browser (for example, `http://localhost:5173/live-list`; your port number may differ based on your project setup) to view the Live Stream List page.
 >
 

package/resource/integration/livekit/preset/live/vue/live-player-desk-integration.md

@@ -44,7 +44,6 @@ Create a `live-player.vue` file in your project. Copy and paste the following co
 
 > **Note：**
 >
-
 > You can use the code below directly, or refer to [Audience Viewing](https://github.com/Tencent-RTC/TUILiveKit/blob/main/Web/web-vite-vue3/src/TUILiveKit/component/LivePlayer/LivePlayerPC.vue) for the full source.
 >
 
@@ -137,7 +136,6 @@ Open your terminal, navigate to your project directory, and run the following co
 
 > **Note：**
 >
-
 > After the command runs successfully, enter your local access URL in your browser (for example, `http://localhost:5173/live-player`; the port may vary based on your setup) to access the viewer page.
 >
 
@@ -158,7 +156,6 @@ npm run dev
 
    > **Tips：**
    >
-
    > Use different **userID** for hosting and viewing. If the same user ID logs in on multiple devices, the later login will force the earlier device offline (**kick offline**).
    >
 
@@ -172,7 +169,6 @@ To enable navigation from the Live Stream List or homepage to the live room, con
 
 > **Note：**
 >
-
 > In the code below, `live-player.vue` refers to the sample file created in Step 3.
 >
 
@@ -289,7 +285,6 @@ export { useCustomizedAutoPlayDialog };
 
 > **Note：**
 >
-
 > Make sure to install the required `@tencentcloud/tuiroom-engine-js` package.
 >
 

package/resource/integration/livekit/preset/live/vue/live-player-h5-integration.md

@@ -44,7 +44,6 @@ Create a **live-player.vue** file in your project. Copy the following code to in
 
 > **Note:**
 >
-
 > You can copy the code below directly into your project, or visit [Audience Viewing](https://github.com/Tencent-RTC/TUILiveKit/blob/main/Web/web-vite-vue3/src/TUILiveKit/component/LivePlayer/LivePlayerH5.vue) for more detailed source code.
 >
 
@@ -138,7 +137,6 @@ Open your terminal, navigate to your project directory, and run the following co
 
 > **Note:**
 >
-
 > After running the command, enter the local access address in your browser’s address bar (refer to your project configuration, for example `http://localhost:5173/live-player`; the actual port may vary) to view the viewer page.
 >
 
@@ -159,7 +157,6 @@ npm run dev
 
    > **Important:**
    >
-
    > Use different **User IDs** for hosting and viewing. Otherwise, the device that logs in later will forcibly log out the device that logged in first (i.e., "kicked offline").
    >
 
@@ -169,7 +166,6 @@ Refer to Step 3 in the quick integration above. Enter the corresponding `liveId`
 
 > **Note:**
 >
-
 > To update your personal information, use the `setSelfInfo` method in the sample code from Step 3.
 >
 
@@ -179,7 +175,6 @@ To enable navigation from the live stream list (or homepage) to the live room, c
 
 > **Note:**
 >
-
 > The `live-player.vue` file in the following code sample corresponds to the sample file created in Step 3.
 >
 
@@ -295,7 +290,6 @@ export { useCustomizedAutoPlayDialog };
 
 > **Note:**
 >
-
 > Install the required `@tencentcloud/tuiroom-engine-js` package.
 >
 

package/resource/integration/livekit/preset/live/vue/live-pusher-integration.md

@@ -47,7 +47,6 @@ Create a `live-pusher.vue` file in your project. Copy the code below into your n
 
 > **Note：**
 >
-
 > You can copy the code below directly into your project, or visit the [Live Start Page](https://github.com/Tencent-RTC/TUILiveKit/blob/main/Web/web-vite-vue3/src/TUILiveKit/LivePusherView.vue) for the full source code.
 >
 
@@ -158,6 +157,8 @@ onMounted(async () => {
 <style scoped>.custom-live-pusher,.left-panel{flex-direction:column;display:flex}.custom-live-pusher,.live-title{color:var(--text-color-primary)}.live-controls,.tools-section,.top-controls{backdrop-filter:blur(10px)}*{box-sizing:border-box;margin:0;padding:0}:global(::before){box-sizing:border-box;margin:0;padding:0}.layout-label,.template-options{margin-bottom:16px}:global(body){line-height:1.6;color:var(--text-color-primary);background:var(--bg-color-default)}.custom-live-pusher{height:100vh;width:100vw;background:linear-gradient(135deg,var(--bg-color-default) 0,var(--bg-color-function) 100%);overflow:hidden}.top-controls{display:flex;justify-content:space-between;align-items:center;padding:12px 20px;background:var(--bg-color-operate);border-bottom:1px solid var(--stroke-color-primary);z-index:100;min-height:60px}.live-title{font-size:18px;font-weight:600;text-shadow:0 2px 4px var(--shadow-color)}.audience-count{font-size:14px;color:var(--text-color-error);background:var(--uikit-color-red-1);padding:6px 12px;border-radius:20px;border:1px solid var(--uikit-color-red-3)}.live-controls,.tools-section{background:var(--bg-color-operate)}.main-content{display:flex;flex:1;height:calc(100vh - 60px);gap:16px;padding:16px;overflow:hidden}.left-panel{width:320px;gap:16px;flex-shrink:0}.panel-title{font-size:16px;font-weight:600;color:var(--text-color-primary);margin-bottom:12px;text-align:left}.audience-section,.message-section,.scene-section{display:flex;flex-direction:column;background:var(--bg-color-operate);border-radius:12px;border:1px solid var(--stroke-color-primary);padding:16px;overflow:hidden}.scene-section{flex:1;min-height:0}.message-section{flex:1;min-height:0}.message-section :deep(input),.message-section :deep(textarea){text-align:left}.tools-section{border-radius:12px;padding:16px;border:1px solid var(--stroke-color-primary)}.center-panel{display:flex;flex-direction:column;flex:1;gap:16px;min-width:0}.stream-section{display:flex;flex-direction:column;flex:1;min-height:0;background:var(--bg-color-operate);border-radius:12px;border:1px solid var(--stroke-color-primary);overflow:hidden}.stream-header{display:flex;justify-content:space-between;align-items:center;padding:22px;border-bottom:1px solid var(--stroke-color-primary)}.stream-title{display:flex;align-items:center;gap:8px;font-size:18px;font-weight:500;color:var(--text-color-primary)}.stream-audience{font-size:14px;color:var(--text-color-primary)}.live-controls{display:flex;justify-content:space-between;align-items:center;padding:16px;border-radius:12px;border:1px solid var(--stroke-color-primary);gap:16px}.live-controls button{padding:18px 20px}.right-panel{display:flex;flex-direction:column;width:320px;gap:16px;flex-shrink:0}.center-panel>.live-controls,.left-panel>*,.right-panel>*{background:var(--bg-color-operate);border-radius:12px;border:1px solid var(--stroke-color-primary);overflow:hidden}.left-panel>*{padding:16px}.left-panel>.panel-title,.scene-section>.panel-title,.audience-section>.panel-title,.message-section>.panel-title{padding:0;background:transparent;border:none;border-radius:0}.custom-icon-container,.device-setting{padding:8px 12px;background:var(--bg-color-function)}.stream-section :deep(>*:last-child){flex:1;min-height:300px}.bottom-panel,.device-setting{align-items:center;display:flex}.custom-icon-container:hover,.option-card:hover{border-color:var(--stroke-color-primary);background:var(--list-color-hover)}.bottom-panel{gap:16px;flex:1}.device-setting{gap:8px;border-radius:8px;border:1px solid var(--stroke-color-secondary)}.device-icon{cursor:pointer;color:var(--text-color-primary);transition:color .2s}.device-icon:hover{color:var(--text-color-link)}.device-slider{width:80px}.custom-icon-container{display:flex;align-items:center;gap:6px;border-radius:8px;border:1px solid var(--stroke-color-secondary);cursor:pointer;transition:.2s;position:relative}.custom-icon-container.disabled{opacity:.5;cursor:not-allowed}.custom-icon-container.disabled:hover{background:var(--bg-color-function);border-color:var(--stroke-color-secondary)}.custom-icon{width:16px;height:16px;display:inline-block;background-size:contain;background-repeat:no-repeat;background-position:center}.custom-text{font-size:12px;color:var(--text-color-secondary);white-space:nowrap}.unread-count{position:absolute;top:-4px;right:-4px;background:var(--text-color-error);color:var(--text-color-button);border-radius:10px;padding:2px 6px;font-size:10px;font-weight:600;min-width:16px;text-align:center;line-height:1}.layout-label,.option-info h4{color:var(--text-color-primary)}.layout-dialog{max-width:600px}.layout-label{font-size:16px;font-weight:600}.options-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(120px,1fr));gap:12px}.option-card{padding:16px;background:var(--bg-color-function);border:2px solid var(--stroke-color-secondary);border-radius:8px;cursor:pointer;transition:.2s;text-align:center}.option-card.active{border-color:var(--text-color-link);background:var(--bg-color-operate)}.option-info h4{margin:8px 0 0;font-size:12px}.option-icon{width:32px;height:32px;margin:0 auto;color:var(--text-color-secondary)}.co-guest-dialog{max-width:500px}.co-guest-panel{min-height:300px}</style>
 ```
 
+### Core API Parameter Descriptions
+
 ##### **createLive**
 
 Creates a new live room and sets its basic information.
@@ -188,7 +189,6 @@ Start your first live stream.
 
 > **Note：**
 >
-
 > After running the above command, open your browser and enter the local address (for example, `http://localhost:5173/live-pusher`; the port may vary by project) to view the live start page.
 >
 
@@ -201,20 +201,17 @@ Start your first live stream.
 
     Integrate our Audience Viewing (Web Desktop Browser) or Audience Viewing (H5 Mobile Browser) page to watch the live stream.
 
-   > **Important Tip:****：**
+   > **Important Tip:：**
    >
-
-   > Use different **userID **for streaming and viewing: The host and audience must use **different** userID. If the same **userID** is used, the second device to log in will force the first device offline.
+   > Use different **userID** for streaming and viewing: The host and audience must use **different** userID. If the same **userID** is used, the second device to log in will force the first device offline.
    >
 
 ## Advanced Feature Integration
 
 > **Note：**
 >
-
 > All advanced features below are extensions based on the `live-pusher.vue` sample file created in Step 3.
 >
-
 > Depending on your requirements, add the following code snippets to the appropriate sections of `live-pusher.vue` (either in the template or script) to enable each feature.
 >
 
@@ -623,7 +620,6 @@ function handleCancel() {
 
 > **Note：**
 >
-
 > You must set the streaming direction **before starting the live stream**; you cannot switch directions during a live session.
 >
 
@@ -737,8 +733,7 @@ You can also customize the **audience viewing page** UI as needed. In addition t
 
 |**Category**|**Feature**|**Description**|**Component Customization Guide**|
 |---------|---------|---------|---------|
-|**Asset Management**|Customize asset management area display|**Supports:** - **Adjust icon size, color, or replace icons.**|Media Source Configuration Panel|
-|**Online Audience**|Customize audience info display|**Supports:** - **Show/hide audience level.** - **Customize font and color of audience info.** - **Replace icon style as needed.**|Video Source Editing Canvas|
+|**Online Audience**|Customize audience info display|**Supports:** - **Show/hide audience level.** - **Customize font and color of audience info.** - **Replace icon style as needed.**|Adjust Live Video Widget|
 |**Message List**|Customize live comments area display|**Supports:** - **Show/hide chat input area.** - **Customize chat bubble style, audience level, etc.**|Live Comments Component|
 
 ## Next Steps

package/resource/integration/roomkit/preset/vue/integration.md

@@ -67,7 +67,6 @@ Authentication is required to access all TUIRoomKit features. Call conference.lo
 
 > **Note:**
 >
-
 > Make sure to use the generated UserSig in your configuration. In production, generate UserSig on your server and have the client request a dynamic UserSig from your business server for authentication as needed. See [How to calculate UserSig for production](https://trtc.io/document/35166).
 >
 
@@ -299,7 +298,6 @@ const enterDualMeeting = async (bizOrderId: string) => {
 
 > **Note:**
 >
-
 > The `conference.createAndJoinRoom` API handles: "If the room does not exist, create it (become host); if it exists, join it (become participant)", resolving state conflicts under high concurrency.
 >
 
@@ -320,7 +318,6 @@ await conference.leaveRoom();
 
 > **Note:**
 >
-
 > When the host leaves the room or closes the web page, the room is not automatically ended. Other participants can continue using TUIRoomKit features. The system will automatically reclaim room resources 6 hours after the scheduled end time, provided the room is empty.
 >
 
@@ -335,7 +332,6 @@ await conference.endRoom();
 
 > **Note:**
 >
-
 > `endRoom()` must be called by the host after successfully Entered Room. Calling as a non-host or before Enter Room will result in an error.
 >
 

package/resource/knowledge/callkit/best-practice/web/callengine-invitation.md

@@ -0,0 +1,80 @@
+---
+product: 'Call'
+tech_stack: 'callengine'
+framework: 'web'
+doc_kind: 'best_practice'
+title: 'TUICallEngine call invitation handling and signaling (Web)'
+keywords: ['ON_CALL_RECEIVED', 'call invitation', '@trtc/call-engine-lite-js', 'TUICallEngine.calls', 'userData', 'callMediaType', 'accept', 'reject', 'TIM.EVENT.MESSAGE_RECEIVED', 'custom signaling message']
+---
+
+# TUICallEngine Web: call invitation reception and signaling notes
+
+Applicable package: **`@trtc/call-engine-lite-js`** (TUICallEngine Web SDK).
+
+## 1) How do I receive an incoming call invitation?
+
+**At the application layer, listen to `TUICallEvent.ON_CALL_RECEIVED` instead of parsing TRTC signaling or IM custom messages yourself.**
+
+```javascript
+import { TUICallEngine, TUICallEvent } from '@trtc/call-engine-lite-js';
+
+const tuiCallEngine = TUICallEngine.createInstance({ SDKAppID: xxx, tim: timInstance });
+await tuiCallEngine.login({ userID, userSig });
+
+tuiCallEngine.on(TUICallEvent.ON_CALL_RECEIVED, (event) => {
+  console.log('Incoming call', event);
+  // Show your incoming-call UI, then call accept() or reject()
+});
+```
+
+### `ON_CALL_RECEIVED` event fields
+
+| Field | Type | Description |
+|---------|---------|---------|
+| callerId | String | The inviter (caller) user ID. |
+| calleeIdList | Array<String> | Other invited users in the same invitation. |
+| isFromGroup | Boolean | Whether this invitation is from a group call. |
+| inviteData | Object | Invitation payload object. |
+| inviteID | String | Invitation ID for this invitation session. |
+| userData | String | Extension string passed through invitation signaling. |
+| callId | String | Unique call ID of this session. |
+| roomID | Number | Audio/video room ID used by this call. |
+| callMediaType | Number | Call media type (audio or video). |
+| callRole | String | Role enum (caller or callee). |
+
+## 2) Which parameters are used when sending an invitation with `calls`?
+
+The caller starts an invitation via **`TUICallEngine.calls()`**:
+
+```javascript
+await tuiCallEngine.calls({
+  userIDList: ['user_bob'],
+  type: 2,                    // 1 = audio, 2 = video (CallMediaType)
+  userData: '{"ext":"info"}', // Optional string extension
+  timeout: 30,                // Seconds, default is 30
+  roomID: 123456,             // Numeric room ID, range [1, 2147483647]
+  strRoomID: '',              // String room ID
+  chatGroupID: '',            // Required for multi-user calls in a Chat group
+  offlinePushInfo: { /* ... */ },
+});
+```
+
+## 3) In Chat-integrated audio/video calls, how do I interpret custom message fields for call status rendering?
+
+| **Question** | **Rule** |
+|---------|---------|
+| How to detect “call initiated” | `actionType = 1` and `cmd = 'videoCall'` or `'audioCall'` |
+| How to detect “call answered” | `actionType = 3` |
+| How to detect “call ended” and get call duration | `actionType = 1` and `cmd = 'hangup'`; read duration from `call_end` (seconds) |
+| How to detect “call canceled” | `actionType = 2` |
+| How to detect “call rejected” | `actionType = 4` |
+| How to detect “rejected due to callee busy” | `actionType = 4` and `cmd = 'line_busy'` |
+| How callee detects “timeout with no answer” | `actionType = 5` |
+
+## 4) Best-practice summary
+
+1. **Only** listen to `TUICallEvent.ON_CALL_RECEIVED`, then respond with `accept()` or `reject()`.
+2. **Do not** parse call invitations from `TIM.EVENT.MESSAGE_RECEIVED` manually.
+3. Use **`userData` (string)** for extension data: caller writes it, callee reads it from event payload.
+4. **`businessID` and low-level payload format** are internal SDK details; do not invent undocumented structures.
+5. In **`@trtc/call-engine-lite-js` 4.x+**, pass custom content via `userData`; there is **no `customData` field**.

package/resource/knowledge/callkit/best-practice/web/callengine-log-control.md

@@ -0,0 +1,24 @@
+---
+product: 'Call'
+tech_stack: 'callengine'
+framework: 'web'
+doc_kind: 'best_practice'
+title: 'TUICallEngine Web log level control with setLogLevel'
+keywords: ['setLogLevel', 'console logs', 'disable logs', 'log level']
+---
+
+## TUICallEngine log level control
+
+Web TUICallEngine provides `setLogLevel` to control browser console output.
+
+### Log levels
+
+- `0`: verbose level (more logs, useful during integration)
+- `1`: key level (default)
+- `2`: warning level (warnings + errors)
+- `3`: error level (errors only)
+- `4`: silent level (no logs)
+
+### Reference
+
+- [TUICallEngine setLogLevel](https://web.sdk.qcloud.com/component/trtccalling/doc/TUICallEngine/web/en/TUICallEngine.html#setLogLevel)

package/resource/knowledge/callkit/best-practice/web/callkit-call-vs-calls.md

@@ -0,0 +1,116 @@
+---
+product: 'Call'
+tech_stack: 'callkit'
+framework: 'web'
+doc_kind: 'best_practice'
+title: 'TUICallKit Web Initiating Audio/Video Calls: call vs calls, Parameter Format and Examples'
+keywords: ['TUICallKit initiating audio/video calls', 'difference between call and calls methods', 'how to pass the userIDList parameter', 'what do type parameter values 1 and 2 represent', 'TUICallKit vue', 'TUICallKit React']
+---
+
+## Best Practices (Conclusion First)
+1. Web TUICallKit **v4.x must use `calls`** to initiate one-to-one/multi-party calls. `call` and `groupCall` apply only to versions before v4.0.0 and are no longer supported starting from v4.0.0.
+2. You must complete `init` before initiating a call; otherwise, the call may fail or the state may become abnormal.
+3. It is recommended to use the `CallMediaType` enum constants for `type`. Using numeric literals (1/2) as the primary approach is not recommended.
+4. `userIDList` must be an array (pass a single-element array even for one-to-one calls). Pass `chatGroupID` only when you need to integrate with a Chat group.
+
+### Initialization Example (v4.x, React)
+``` javascript
+import { TUICallKitAPI } from "@trtc/calls-uikit-react";
+
+TUICallKitAPI.init({ SDKAppID, userID, userSig });
+```
+
+### Legacy Initialization Example (before v4.0.0)
+``` javascript
+import { TUICallKitServer } from "@tencentcloud/call-uikit-react";
+
+TUICallKitServer.init({ SDKAppID, userID, userSig });
+```
+
+## Common Misconceptions (Anti-patterns)
+- Continuing to call `call` / `groupCall` in v4.x.
+- Writing a one-to-one call using the `userID` field instead of `userIDList`.
+- Mixing `roomID` and `strRoomID` (the two are mutually exclusive and not interoperable).
+- Using numeric literals for `type` long-term instead of the `CallMediaType` enum constants.
+
+## Usage Example of the v4.x calls API
+Initiate a one-to-one or multi-party call.
+``` javascript
+try {
+  await TUICallKitAPI.calls({
+    userIDList: ['jack', 'tom'],
+    type: CallMediaType.VIDEO_CALL
+  });
+} catch (error: any) {
+  console.error(`[TUICallKit] Failed to call the groupCall API. Reason:${error}`);
+}
+```
+
+The parameters are shown in the table below:
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| userIDList | Array<String> | Yes | The list of users being called. |
+| type | CallMediaType| Yes | The media type of the call.<br>Backward compatible with older versions: audio call (type = 1), video call (type = 2). |
+| chatGroupID | String | Yes | The group ID of the Chat group when used together with Chat. |
+| roomID | Number | No | Numeric room ID, in the range [1, 2147483647]. |
+| strRoomID | String | No | String room ID. <strong>Supported in v3.3.1+</strong><br>1. roomID and strRoomID are mutually exclusive. If you choose strRoomID, roomID must be set to 0. If both are provided, the SDK gives priority to roomID.<br>2. Do not mix roomID and strRoomID, because they are not interoperable. For example, the number 123 and the string "123" are two completely different rooms. |
+| timeout | Number | No | Call timeout duration. Default: 30s, unit: seconds. Range: 10s ~ 600s. If 0 is passed, it defaults to 30s. |
+| userData | String | No | A custom extension field when initiating a call. The called user receives this parameter in the ON_CALL_RECEIVED event. |
+| <a href="https://cloud.tencent.com/document/product/647/81015#offlinePushInfo">offlinePushInfo</a> | Object | No | Custom offline message push parameters. |
+
+### CallMediaType Call Types
+|CallMediaType Type|Description|
+|---------|---------|
+|CallMediaType.AUDIO|Audio call.|
+|CallMediaType.VIDEO|Video call.|
+
+## Usage Examples of the `call` and `groupCall` APIs in Lower Versions (v2.x/v3.x)
+
+### call: Initiate a One-to-One Call
+``` javascript
+import { TUICallKitServer, TUICallType } from '@tencentcloud/call-uikit-react';
+try {
+  await TUICallKitServer.call({
+    userID: 'mike', // username being called
+    type: TUICallType.VIDEO_CALL,
+  });
+} catch (error: any) {
+  console.error(`[TUICallKit] Call failed. Reason: ${error}`);
+}
+```
+
+The parameters are shown in the table below:
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| userID | String | Yes | The user ID being called. |
+| type | TUICallType | Yes | The media type of the call.<br>Backward compatible with older versions: audio call (type = 1), video call (type = 2). |
+| roomID | Number | No | Numeric room ID, in the range [1, 2147483647]. |
+| strRoomID | String | No | String room ID. <strong>Supported in v3.3.1+</strong><br>1. roomID and strRoomID are mutually exclusive. If you choose strRoomID, roomID must be set to 0. If both are provided, the SDK gives priority to roomID.<br>2. Do not mix roomID and strRoomID, because they are not interoperable. For example, the number 123 and the string "123" are two completely different rooms. |
+| timeout | Number | No | Call timeout duration. Default: 30s, unit: seconds. Range: 10s ~ 600s. If 0 is passed, it defaults to 30s. |
+| userData | String | No | A custom extension field when initiating a call. The called user receives this parameter in the ON_CALL_RECEIVED event. |
+| offlinePushInfo | Object | No | Custom offline message push parameters. |
+
+### groupCall: Initiate a Multi-party Call
+``` javascript
+try {
+  await TUICallKitServer.groupCall({
+    userIDList: ['jack', 'tom'],
+    groupID: "xxx",
+    type: TUICallType.VIDEO_CALL
+  });
+} catch (error: any) {
+  console.error(`[TUICallKit] Failed to call the groupCall API. Reason:${error}`);
+}
+```
+
+The parameters are shown in the table below:
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| userIDList| Array<String> | Yes | The user IDs being called. |
+| type | TUICallType | Yes | The media type of the call.<br>Backward compatible with older versions: audio call (type = 1), video call (type = 2). |
+| groupID | String | Yes | The call group ID. See the documentation for how to create a groupID. |
+| roomID | Number | No | Numeric room ID, in the range [1, 2147483647]. |
+| strRoomID | String | No | String room ID. <strong>Supported in v3.3.1+</strong><br>1. roomID and strRoomID are mutually exclusive. If you choose strRoomID, roomID must be set to 0. If both are provided, the SDK gives priority to roomID.<br>2. Do not mix roomID and strRoomID, because they are not interoperable. For example, the number 123 and the string "123" are two completely different rooms. |
+| timeout | Number | No | Call timeout duration. Default: 30s, unit: seconds. Range: 10s ~ 600s. If 0 is passed, it defaults to 30s. |
+| userData | String | No | A custom extension field when initiating a call. The called user receives this parameter in the ON_CALL_RECEIVED event. |
+| offlinePushInfo | Object | No | Custom offline message push parameters. |