@tencent-rtc/mcp 1.4.6 → 1.6.0-beta.1

package/resource/knowledge/roomkit/core-sdk/vue/call-user-to-room.md

@@ -0,0 +1,221 @@
+The in-room calling feature allows a user inside a meeting (the inviter) to send a real-time join invitation to other users outside the room (the invitees). This feature is implemented based on `Atomicx State Hooks` and helps developers quickly build interactive scenarios with active invitation capabilities.
+
+## Use Cases
+- **Collaborative work:** During a remote meeting, if a cross-department decision is involved, you can call in external experts with one click to quickly join the meeting, shortening the communication chain.
+
+- **Live teaching:** If a teacher notices during a class that some students are absent, they can directly invite them to join the class.
+
+- **Internet-based medical consultation:** During case analysis, a primary physician can use the calling feature to invite a senior physician into the virtual consultation room for a multi-party consultation, or a physician can call a patient in the waiting room for a consultation.
+
+## Prerequisites
+
+Before integrating the feature, make sure the following conditions are met:
+- **Inviter (User A):** The user has completed login authentication via `useLoginState` (see the Integration Overview) and is already in a room as the room owner or a member (see the Room Lifecycle).
+
+- **Invitee (User B):** The user has completed login authentication via `useLoginState` (see the Integration Overview) so that they can receive signaling events.
+
+- **Environment dependency:** The project has correctly installed and imported `tuikit-atomicx-vue3`.
+
+## Implementing the In-Room Calling Feature
+
+The core flow for implementing in-room calling is as follows:
+
+In-room calling sequence diagram
+
+### Step 1: Initiate the Call (Inviter)
+
+The inviter calls the [callUserToRoom](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#callUserToRoom) interface to initiate the invitation. Make sure the inviter is currently in a room (that is, [currentRoom](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#currentRoom) is not empty); otherwise, the call cannot be initiated.
+``` typescript
+import { useRoomState } from 'tuikit-atomicx-vue3/room';
+
+const { currentRoom, callUserToRoom } = useRoomState();
+
+const inviteUser = async () => {
+  // In-room calling must be associated with an existing roomId, so the user's in-room status must be verified first
+  if (!currentRoom.value) {
+    console.warn('Please enter a room before initiating an invitation');
+    return;
+  }
+
+  try {
+    const resultMap = await callUserToRoom({
+      roomId: currentRoom.value.roomId, // The room ID that the invitee will join
+      userIdList: ['user1', 'user2'],    // Array of target user IDs, supports single or multiple users
+      timeout: 60,                        // Invitation valid duration (seconds); after timeout, both parties trigger onCallTimeout
+      // extensionInfo can be used to pass custom business data, such as invitation type, additional messages, etc.
+      extensionInfo: JSON.stringify({ type: 'emergency', priority: 'high' })
+    });
+
+    // resultMap returns the status corresponding to each userId, such as Success, AlreadyInRoom, or AlreadyInCalling
+    console.log('Invitation sent, detailed status map:', resultMap);
+  } catch (error) {
+    console.error('Failed to send the call request; please check the network or login status:', error);
+  }
+};
+```
+
+### Step 2: Listen for Call Events (Invitee)
+
+The invitee needs to listen for the `onCallReceived` event. It is recommended to implement this in a persistent component such as `App.vue` to ensure the user can respond no matter which page they are on.
+``` typescript
+import { ref, onMounted, onUnmounted } from 'vue';
+import { useRoomState, RoomEvent } from 'tuikit-atomicx-vue3/room';
+
+const {
+  subscribeEvent,
+  unsubscribeEvent,
+  acceptCall,
+  rejectCall,
+  joinRoom,
+  currentRoom
+} = useRoomState();
+
+const showInviteDialog = ref(false); // Controls the visibility of the UI dialog
+const currentCallInfo = ref(null);   // Caches the received invitation context
+
+const handleCallReceived = async ({ roomInfo, call, extensionInfo }) => {
+  // Conflict handling: if the user is already in a meeting, based on the business strategy you should usually reject the new invitation directly to avoid interference
+  if (currentRoom.value?.roomId) {
+    await rejectCall({ roomId: roomInfo.roomId });
+    return;
+  }
+
+  // Record the invitation details, used to display the inviter's name or business pass-through data in the UI
+  currentCallInfo.value = { roomInfo, call };
+  showInviteDialog.value = true;
+};
+
+// Logic for accepting the invitation
+const onUserAccept = async () => {
+  if (!currentCallInfo.value) return;
+  const { roomId } = currentCallInfo.value.roomInfo;
+
+  try {
+    // Key step A: Respond to the signaling. Notify the inviter that the call has been accepted so they can update the UI (for example, show "The other party has answered")
+    await acceptCall({ roomId });
+
+    // Key step B: Join the room. Only by calling joinRoom will the audio/video publish-subscribe pipeline actually be started
+    await joinRoom({ roomId });
+  } catch (error) {
+    console.error('Failed to join the room after accepting the call:', error);
+  } finally {
+    closeDialog();
+  }
+};
+
+// Logic for rejecting the invitation
+const onUserReject = async () => {
+  if (currentCallInfo.value) {
+    // Notify the inviter of the rejection; the inviter will receive the onCallRejected event
+    await rejectCall({ roomId: currentCallInfo.value.roomInfo.roomId });
+  }
+  closeDialog();
+};
+
+const closeDialog = () => {
+  showInviteDialog.value = false;
+  currentCallInfo.value = null;
+};
+
+// Full lifecycle event management: ensure listeners are added when the component is mounted and removed when it is destroyed, to prevent event overflow
+onMounted(() => {
+  subscribeEvent(RoomEvent.onCallReceived, handleCallReceived);
+
+  // Listen for the various exception/synchronization events that end the invitation, to ensure the UI dialog can close in time
+  subscribeEvent(RoomEvent.onCallCancelled, closeDialog); // The inviter cancelled the call
+  subscribeEvent(RoomEvent.onCallTimeout, closeDialog);   // The call timed out without a response
+  subscribeEvent(RoomEvent.onCallHandledByOtherDevice, closeDialog); // The user handled the call on another device
+});
+
+onUnmounted(() => {
+  // Remove all listeners to avoid handleCallReceived continuing to run after the component is destroyed, which would cause memory leaks or errors
+  unsubscribeEvent(RoomEvent.onCallReceived, handleCallReceived);
+  unsubscribeEvent(RoomEvent.onCallCancelled, closeDialog);
+  unsubscribeEvent(RoomEvent.onCallTimeout, closeDialog);
+  unsubscribeEvent(RoomEvent.onCallHandledByOtherDevice, closeDialog);
+});
+```
+
+## Practical Tutorial: Improving the Call Answer Rate
+
+To achieve a higher call answer rate in your business, beyond implementing the basic functionality, it is recommended to refer to the following strategies to optimize the user experience:
+
+### 1. Enhance Call Awareness (Avoid Users Missing Calls)
+
+Due to the characteristics of the Web platform, a muted browser or a page running in the background may cause the user to miss a call.
+- **Visual reminder**: Use the [Page Visibility API](https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API) to detect the page visibility state. If the page is in the background, you can implement a blinking title bar reminder by cyclically modifying `document.title` (for example: "[New Invitation] UserA is inviting you to join the meeting...") to attract the user's attention.
+
+- **Auditory reminder**: Play a high-priority prompt ringtone when the `onCallReceived` event is triggered. Note: You must follow the browser's [autoplay policy](https://developer.mozilla.org/zh-CN/docs/Web/Media/Guides/Autoplay). Most browsers restrict automatic audio playback in the absence of user interaction (such as a click, touch, or key press).
+
+### 2. Enrich the Invitation Context (Increase Willingness to Answer)
+
+Invitations that lack a clear intent are easily rejected by users. It is recommended to make full use of the `extensionInfo` field to pass key business information to increase the user's willingness to answer.
+- **Pass business context**: Use `extensionInfo` to pass through business fields such as `reason` (for example: "Urgent project review") and `level` (for example: "P0 incident troubleshooting") to inform the user of the urgency and importance of the call.
+
+### 3. Multi-Channel Reach as a Fallback (Ensure Message Delivery)
+
+Limited by the Web platform mechanism, the browser process being terminated will make it impossible to receive real-time signaling. It is recommended to adopt the following alternatives to ensure delivery:
+- **Browser system notifications**: Guide the user to authorize the [Web Notification API](https://developer.mozilla.org/en-US/docs/Web/API/Notification). As long as the browser process is not closed (including when minimized or in a background tab), an operating-system-level pop-up notification can be triggered to effectively remind the user.
+
+- **Multi-channel reach**: It is recommended to combine this with your business backend logic. When the user is detected to be offline or does not respond within the timeout, send a join link through external channels such as **SMS**, **email**, or **WeCom** to achieve comprehensive reach.
+
+### 4. Intelligent Retry Mechanism (Solving "Join Failure After Accepting the Invitation")
+
+In a weak network or other unstable environment, the `joinRoom` call after the user clicks accept may occasionally fail.
+- **Automatic retry**: It is recommended to introduce a mechanism of 2-3 automatic retries in the exception handling logic (`catch`) of `onUserAccept` (an exponential backoff strategy is recommended) to maximize the likelihood that the user successfully joins the meeting after clicking "Accept".
+
+## Development Notes
+1. **Accepting an invitation does not equal joining the room**
+
+   `acceptCall` is only a reply at the signaling level (notifying the other party that the call has been answered). The user must call `await joinRoom({ roomId })` manually immediately after calling `acceptCall` to actually enter the audio/video room.
+
+2. **Lifecycle management**
+
+   Be sure to call `unsubscribeEvent` during the component destruction phase (`onUnmounted`). If the listeners are not cleaned up, when the user switches pages, the listeners from the old page will remain in memory, causing multiple windows to pop up for a single invitation or logic to be executed repeatedly.
+
+3. **Timeout setting**
+
+   If the `timeout` parameter is not set, in certain network exceptions or program crash scenarios, the invitation may remain in a pending state for a long time, making it impossible to call the user again. It is recommended to set it to 30-60 seconds.
+
+## FAQ
+1. **How can I include custom parameters when calling (such as "Urgent meeting from XX")?**
+
+   Use the `extensionInfo` parameter of `callUserToRoom` to pass a JSON string. The invitee can parse this string from the `extensionInfo` field of the `onCallReceived` event to obtain the business information.
+
+2. **If the invitee is offline, will they receive the invitation after coming online?**
+
+   No. The invitation event is a transient signaling action, and the SDK currently does not resend call notifications received while offline.
+
+3. **Can I cancel an invitation that has already been sent?**
+
+   Yes. Call `cancelCall({ roomId, userIdList })` to revoke it. At this point, the invitee will receive the `onCallCancelled` event, and you need to listen for this event to close the invitee's UI dialog.
+
+4. **What should I do if joining the room fails after accepting?**
+
+   Check whether `TUIRoomEngine` is logged in, retry `joinRoom({ roomId })`, and catch errors to prompt the user; if necessary, provide a "Retry" button in the UI.
+
+5. **How to indicate that the other party is busy or already in another room?**
+
+   If `AlreadyInRoom` / `AlreadyInCalling` appears in the `resultMap` return value of `callUserToRoom`, you should prompt "The other party is busy / already in a meeting" in the inviter's UI and decide whether to retry later.
+
+6. **The dialog does not close after a timeout/cancellation?**
+
+   Make sure to listen for `onCallTimeout`, `onCallCancelled`, and `onCallHandledByOtherDevice`, and uniformly close the dialog and clean up the current invitation data in the callbacks.
+
+7. **How to handle multiple devices ringing simultaneously?**
+
+   After accepting/rejecting on any device, the other devices will receive `onCallHandledByOtherDevice`, and you need to close the dialogs on the other devices to avoid duplicate handling.
+
+8. **How should extensionInfo be defined?**
+
+   It is recommended to use a JSON string with agreed-upon fields (for example, `type`, `priority`, `from`), parse it in `handleCallReceived`, and display a friendly message (for example, "Urgent meeting from XX").
+
+## **Example Project**
+
+Tencent Cloud provides the example project [atomicx-vite-vue3-ts](https://github.com/Tencent-RTC/TUIRoomKit/tree/main/Web/example/atomicx-vite-vue3-ts) on GitHub, which you can refer to in order to implement the complete RoomKit functionality.
+
+## API Documentation
+
+|**State/Component**|**Description**|**API Documentation**|
+|---------|---------|---------|
+|**useRoomState**|Room state management (creation, joining, scheduling, etc.)|[API Documentation](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#module-RoomState)|

package/resource/{doc/roomkit/vue/features → knowledge/roomkit/core-sdk/vue}/device-detection.md

@@ -1,30 +1,30 @@
-This document will guide you on how to provide device preview and testing functionality before users join a room. Through the pre-room testing interfaces provided by Atomicx, you can guide users to check and adjust their audio/video device status, ensuring they enter the multi-party audio/video room in the best condition.
+This document guides you through providing device preview and testing capabilities before a user joins a room. Using the pre-join testing APIs provided by Atomicx, you can guide users to check and adjust the status of their audio and video devices, ensuring they enter a multi-party audio/video room in the best possible state.
 
-## Feature Introduction
+## Feature Overview
 
-Device preview is an important part of ensuring the smooth operation of audio/video rooms. Atomicx provides a dedicated set of testing interfaces specifically for pre-room scenarios, with core capabilities including:
-- **Video Preview**: Start the camera without streaming to verify picture clarity and lighting.
+Device preview is a crucial step in ensuring the smooth operation of an audio/video room. Atomicx provides a dedicated set of testing APIs specifically for the pre-join scenario. Its core capabilities include:
+- **Video preview**: Start the camera without publishing a stream to verify image clarity and lighting.
 
-- **Microphone Detection**: Confirm microphone capture is working properly through real-time volume feedback.
+- **Microphone detection**: Confirm that microphone capture is working properly through real-time volume feedback.
 
-- **Speaker Calibration**: Confirm output device and volume settings by playing test audio.
+- **Speaker calibration**: Confirm the output device and its volume settings by playing a test sound.
 
 ## Prerequisites
-- User has completed login authentication through [useLoginState](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-LoginState), please refer to Integration Overview.
+- The user has completed login authentication via [useLoginState](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#module-LoginState). See the Integration Overview for details.
 
-## Implementing Device Detection Features
+## Implementing Device Detection
 
 ### Step 1: Camera Test
 
-Use the [startCameraTest](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#startCameraTest) method to start camera testing. This method is only used for local preview and does not generate network traffic.
+Use the [startCameraTest](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#startCameraTest) method to start the camera test. This method is used for local preview only and does not generate any network traffic.
 
-**Code Example:**
+**Code example:**
 ``` typescript
 <template>
   <div class="preview-container">
     <!-- Camera preview area -->
     <div id="camera-preview" class="camera-preview">
-      <!-- Loading status -->
+      <!-- Loading state -->
       <div v-if="isCameraTestLoading" class="loading-overlay">
         <div class="loading-spinner" />
         <span>Starting camera...</span>
@@ -33,7 +33,7 @@ Use the [startCameraTest](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.
 
     <!-- Camera selection -->
     <div class="camera-selector">
-      <label>Select Camera</label>
+      <label>Select camera</label>
       <select
         :value="currentCamera?.deviceId"
         @change="handleCameraChange"
@@ -51,12 +51,12 @@ Use the [startCameraTest](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.
 
     <!-- Control buttons -->
     <div class="control-buttons">
-      <button @click="getCameraList">Get Camera List</button>
+      <button @click="getCameraList">Get camera list</button>
       <button
         @click="toggleCameraTest"
         :disabled="isCameraTestLoading"
       >
-        {{ isCameraTesting ? 'Stop Preview' : 'Start Preview' }}
+        {{ isCameraTesting ? 'Stop preview' : 'Start preview' }}
       </button>
     </div>
   </div>
@@ -117,15 +117,15 @@ const handleCameraChange = async (event: Event) => {
 
 ### Step 2: Microphone Test
 
-Start microphone testing through [startMicrophoneTest](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#startMicrophoneTest), and use [testingMicVolume](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#testingMicVolume) to implement real-time volume bar fluctuation in the UI.
+Use [startMicrophoneTest](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#startMicrophoneTest) to start the microphone test, and use [testingMicVolume](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#testingMicVolume) to drive the real-time fluctuation of the UI volume bar.
 
-**Code Example:**
+**Code example:**
 ``` typescript
 <template>
   <div class="microphone-test">
     <!-- Volume display -->
     <div class="volume-display">
-      <div class="volume-label">Microphone Volume</div>
+      <div class="volume-label">Microphone volume</div>
       <div class="volume-bar-container">
         <div
           class="volume-bar"
@@ -138,7 +138,7 @@ Start microphone testing through [startMicrophoneTest](https://web.sdk.qcloud.co
 
     <!-- Microphone selection -->
     <div class="microphone-selector">
-      <label>Select Microphone</label>
+      <label>Select microphone</label>
       <select
         :value="currentMicrophone?.deviceId"
         @change="handleMicrophoneChange"
@@ -159,18 +159,18 @@ Start microphone testing through [startMicrophoneTest](https://web.sdk.qcloud.co
       <button
         @click="getMicrophoneList"
       >
-        Get Devices
+        Get devices
       </button>
       <button
         @click="toggleMicrophoneTest"
       >
-        {{ isMicrophoneTesting ? 'Stop Test' : 'Start Test' }}
+        {{ isMicrophoneTesting ? 'Stop test' : 'Start test' }}
       </button>
     </div>
 
     <!-- Test tip -->
     <div v-if="isMicrophoneTesting" class="test-tip">
-      <span>Please speak into the microphone to see volume changes</span>
+      <span>Please speak into the microphone and observe the volume change</span>
     </div>
   </div>
 </template>
@@ -202,14 +202,14 @@ const volumeClass = computed(() => {
   return 'volume-high';
 });
 
-// Cleanup: stop testing
+// Cleanup: stop the test
 onUnmounted(() => {
   if (isMicrophoneTesting.value) {
     stopMicrophoneTest();
   }
 });
 
-// Toggle microphone test
+// Toggle the microphone test
 const toggleMicrophoneTest = async () => {
   if (isMicrophoneTesting.value) {
     await stopMicrophoneTest();
@@ -222,7 +222,7 @@ const toggleMicrophoneTest = async () => {
   }
 };
 
-// Switch microphone device
+// Switch the microphone device
 const handleMicrophoneChange = async (event: Event) => {
   const deviceId = (event.target as HTMLSelectElement).value;
   try {
@@ -240,15 +240,15 @@ const handleMicrophoneChange = async (event: Event) => {
 
 ### Step 3: Speaker Test
 
-Use the [startSpeakerTest](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#startSpeakerTest) method to play a specified audio file to confirm whether the speaker is working properly.
+Use the [startSpeakerTest](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#startSpeakerTest) method to play a specified audio file to confirm whether the speaker is working properly.
 
-**Code Example:**
+**Code example:**
 ``` typescript
 <template>
   <div class="speaker-test">
     <!-- Speaker selection -->
     <div class="speaker-selector">
-      <label>Select Speaker</label>
+      <label>Select speaker</label>
       <select
         :value="currentSpeaker?.deviceId"
         @change="handleSpeakerChange"
@@ -266,24 +266,24 @@ Use the [startSpeakerTest](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index
 
     <!-- Control buttons -->
     <div class="control-buttons">
-      <button @click="getSpeakerList">Get Speaker List</button>
+      <button @click="getSpeakerList">Get speaker list</button>
       <button
         @click="toggleSpeakerTest"
         :disabled="isSpeakerTesting"
       >
-        {{ isSpeakerTesting ? 'Playing...' : 'Play Test Audio' }}
+        {{ isSpeakerTesting ? 'Playing...' : 'Play test audio' }}
       </button>
       <button
         v-if="isSpeakerTesting"
         @click="stopSpeakerTest"
       >
-        Stop Playback
+        Stop playback
       </button>
     </div>
 
     <!-- Test tip -->
     <div v-if="isSpeakerTesting" class="test-tip">
-      <span>Playing test audio, please confirm if you can hear the sound</span>
+      <span>Playing test audio. Please confirm whether you can hear the sound</span>
     </div>
   </div>
 </template>
@@ -303,17 +303,17 @@ const {
 } = useDeviceState();
 
 // Test audio file path
-// Note: This URL is for development testing only. For production environments, please use your own audio file. It is recommended to use a 3-5 second MP3 format audio file
+// Note: This URL is for development and testing only. In production, please use your own audio file. A 3-5 second MP3 file is recommended.
 const testAudioPath = 'https://web.sdk.qcloud.com/trtc/electron/download/resources/media/TestSpeaker.mp3';
 
-// Cleanup: stop testing
+// Cleanup: stop the test
 onUnmounted(() => {
   if (isSpeakerTesting.value) {
     stopSpeakerTest();
   }
 });
 
-// Toggle speaker test
+// Toggle the speaker test
 const toggleSpeakerTest = async () => {
   if (isSpeakerTesting.value) {
     await stopSpeakerTest();
@@ -326,7 +326,7 @@ const toggleSpeakerTest = async () => {
   }
 };
 
-// Switch speaker device
+// Switch the speaker device
 const handleSpeakerChange = async (event: Event) => {
   const deviceId = (event.target as HTMLSelectElement).value;
   try {
@@ -342,29 +342,30 @@ const handleSpeakerChange = async (event: Event) => {
 </style>
 ```
 
-## API Documentation
-| **State/Component** | **Feature Description** | **API Documentation** |
-| --- | --- | --- |
-| **useDeviceState** | Contains audio/video device status, audio/video device list and operation interfaces. | [API Documentation](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-DeviceState) |
+## API Reference
+
+|**State/Component**|**Description**|**API Reference**|
+|---------|---------|---------|
+|**useDeviceState**|Contains audio/video device status, the audio/video device list, and operation APIs.|[API Reference](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#module-DeviceState)|
 
 ## FAQ
 
 ### Why is there no image in the camera preview?
 
-Possible reasons include:
-- **Permission denied:** Check if the browser allows camera permissions.
+Possible causes include:
+- **Permission denied:** Check whether the browser allows camera access.
 
-- **Device occupied:** Close other applications using the camera.
+- **Device in use:** Close other applications that are using the camera.
 
-- **Device not connected:** Check if the camera is properly connected.
+- **Device not connected:** Check whether the camera is properly connected.
 
-- **Browser not supported:** Use modern browsers such as Chrome, Edge, etc.
+- **Browser not supported:** Use a modern browser such as Chrome or Edge.
 
-### Microphone test volume is always 0?
+### Why does the volume stay at 0 during the microphone test?
 
-Possible reasons include:
-- **Microphone permission not granted:** Check browser permission settings.
+Possible causes include:
+- **Microphone permission not granted:** Check the browser permission settings.
 
-- **Microphone is muted:** Check system microphone settings.
+- **Microphone muted:** Check the system microphone settings.
 
 - **Wrong device selected:** Switch to the correct microphone device.