@tencent-rtc/mcp 1.4.7 → 1.6.0

package/resource/doc/callkit/core-sdk/uni-app/answer-call.md

@@ -1,950 +0,0 @@
-This document helps you build a call-enabled **App** quickly by using the **AtomicXCore SDK** components — **DeviceState**, **CallState**, and the core widget **CallCoreView**.
-
-## Preparation
-
-### Step 1: Activate the Service
-
-Follow the **Activate the Service** guide to obtain either a trial or paid version of the SDK.
-
-### Step 2: Import AtomicXCore into the Current Project
-
-1. **Install the component:** Open the [AtomicXCore SDK](https://ext.dcloud.net.cn/plugin?name=tuikit-atomic-x) marketplace page; click **Download Plugin and Import to HBuilderX**, select the target project, and click **Confirm**. Alternatively, download the source from the [Tencent-RTC/TUIKit_uni-app](https://github.com/Tencent-RTC/TUIKit_uni-app) repo and copy the `App/uni_modules/tuikit-atomic-x` directory into your project's `uni_modules/` folder.
-
-2. **Configure project permissions:** Under `app-plus > distribute` in your project's `manifest.json`, make sure the following permissions are declared.
-
-   **Android (`Android` node):** Add the following entries to the `permissions` array:
-
-   ```json
-   "<uses-permission android:name=\"android.permission.RECORD_AUDIO\" />",
-   "<uses-permission android:name=\"android.permission.CAMERA\"/>"
-   ```
-
-   **iOS (`iOS` node):** Add the following entries to the `privacyDescription` object:
-
-   ```json
-   "NSCameraUsageDescription" : "The app needs camera access to make calls",
-   "NSMicrophoneUsageDescription" : "The app needs microphone access to make calls"
-   ```
-
-   Add `audio` to the `UIBackgroundModes` array to support background audio playback:
-
-   ```json
-   "UIBackgroundModes" : [ "audio" ]
-   ```
-
-### Step 3: Implement the Login Logic
-
-In your project, call the `login` method of `LoginState` to complete the login. **This is the prerequisite for using every feature of AtomicXCore.**
-
-> **Important:**
->
-> We recommend calling the `login` method of `LoginState` after your app's own user account has successfully logged in, so that the login flow stays clear and consistent.
-
-```typescript
-import { useLoginState } from "@/uni_modules/tuikit-atomic-x/state/LoginState";
-
-const { login } = useLoginState();
-
-const handleLogin = () => {
-    login({
-      sdkAppID: 1400000001,  // Replace with your SDKAppID
-      userID: "test_001",    // Replace with your UserID
-      userSig: "xxxxxxxxxx"  // Use a temporary UserSig during development; when the MCP Server is configured with sdkAppID and sdkSecretKey, the tool can issue it for you
-    })
-}
-```
-
-**Login parameter details:**
-
-| **Parameter** | **Type** | **Description** |
-| --- | --- | --- |
-| `sdkAppID` | number | Obtain from the console; usually a 10-digit integer starting with `140` or `160`. |
-| `userID` | string | Unique user ID, up to **32 bytes**, with **no special characters**; use letters and digits. Avoid simple IDs like `1` or `123` to reduce multi-device conflicts. |
-| `userSig` | string | Authentication token. For development, generate a temporary `userSig` locally with `genTestUserSig` (see <https://github.com/Tencent-RTC/TUIKit_uni-app/blob/main/App/debug/GenerateTestUserSig.js>). When the **Tencent RTC MCP Server** is configured with `sdkAppID` and `sdkSecretKey`, the tool can auto-issue a `userSig` for you. **In production**, the business server must sign the UserSig with the secret key — never store or distribute the SecretKey on the client. |
-
-## Implement Call Answering
-
-### Step 1: Create the Call Page
-
-You need a dedicated call page that is launched when a call starts. Implementation:
-
-1. **Create the call page:** Add a new page to host the call UI and handle navigation when an incoming call arrives.
-
-2. **Mount CallCoreView on the call page:** `CallCoreView` is the core call-view component. It automatically observes `CallState` and renders the call UI, and it supports layout switching, avatar and icon customization, and other UI customizations.
-
-```vue
-<call-core-view style="height: 50px; width: 50px;"></call-core-view>
-```
-
-> **Note:**
->
-> `CallCoreView` is a native component and does not need an explicit `import` in the file. Just place it on the page.
-
-**CallCoreView feature overview:**
-
-| **Feature** | **Description** | **Reference** |
-| --- | --- | --- |
-| **Set layout mode** | Supports flexible layout switching. If not set, the layout adapts automatically based on the number of participants. | Switch Layout Modes |
-| **Set avatar** | Supports custom avatars for specific users by passing avatar resource paths. | Customize Default Avatar |
-| **Set volume-level icons** | Supports custom volume-level indicator icons for different levels. | Customize Volume Level Icons |
-| **Set network-quality icons** | Supports custom network-quality indicator icons based on real-time network status. | Customize Network Quality Icons |
-| **Set loading animation** | In group calls, supports a GIF animation to indicate users in the waiting state. | Customize Loading Animation |
-
-### Step 2: Add Call Control Buttons
-
-You can build your own buttons on top of the APIs provided by **DeviceState** and **CallState**.
-
-- **DeviceState:** Microphone (toggle/volume), camera (toggle/switch/quality), screen sharing, and real-time device-state listening. Bind methods to button taps and watch the device state to refresh the button UI in real time.
-- **CallState:** Core call actions such as answer, hang up, and reject. Bind methods to button taps and watch the call state so that the button display stays in sync with the current call stage.
-- **Icon resources:** Button icons are available on GitHub. They are designed by our team for TUICallKit, are copyright-free, and can be used directly.
-
-| **Resource** | **Description** | **Download** |
-| --- | --- | --- |
-| `accept.png` | Answer button icon. | [GitHub](https://github.com/Tencent-RTC/TUIKit_uni-app/blob/main/App/uni_modules/tuikit-atomic-x/static/icon/accept.png) |
-| `hangup.png` | Hang up / reject button icon. | [GitHub](https://github.com/Tencent-RTC/TUIKit_uni-app/blob/main/App/uni_modules/tuikit-atomic-x/static/icon/hangup.png) |
-| `camera-off.png` | Camera off. | [GitHub](https://github.com/Tencent-RTC/TUIKit_uni-app/blob/main/App/uni_modules/tuikit-atomic-x/static/icon/camera-off.png) |
-| `camera-on.png` | Camera on. | [GitHub](https://github.com/Tencent-RTC/TUIKit_uni-app/blob/main/App/uni_modules/tuikit-atomic-x/static/icon/camera-on.png) |
-| `mic-off.png` | Microphone off. | [GitHub](https://github.com/Tencent-RTC/TUIKit_uni-app/blob/main/App/uni_modules/tuikit-atomic-x/static/icon/mic-off.png) |
-| `mic-on.png` | Microphone on. | [GitHub](https://github.com/Tencent-RTC/TUIKit_uni-app/blob/main/App/uni_modules/tuikit-atomic-x/static/icon/mic-on.png) |
-| `handsfree-off.png` | Speaker off. | [GitHub](https://github.com/Tencent-RTC/TUIKit_uni-app/blob/main/App/uni_modules/tuikit-atomic-x/static/icon/handsfree-off.png) |
-| `handsfree-on.png` | Speaker on. | [GitHub](https://github.com/Tencent-RTC/TUIKit_uni-app/blob/main/App/uni_modules/tuikit-atomic-x/static/icon/handsfree-on.png) |
-
-**The following example shows how to add the Answer and Reject buttons:**
-
-1. **Add the Answer button:** Bind the tap event to the `accept` method.
-
-```vue
-<template>
-  <view class="btn" @tap="handleAccept">
-    <image class="btn-img" :src="ACCEPT_SRC"></image>
-    <text class="btn-text">Answer</text>
-  </view>
-</template>
-
-<script setup lang="ts">
-  import ACCEPT_SRC from "../../../static/icon/accept.png"; // Replace with the actual icon path in your project
-  import { useCallState } from '@/uni_modules/tuikit-atomic-x/state/CallState';
-
-  const { accept } = useCallState();
-
-  const handleAccept = () => {
-    accept();
-  };
-</script>
-
-<style scoped>
-  .btn {
-    width: 60px;
-    margin: 10px 20px;
-  }
-  .btn-img {
-    width: 60px;
-    height: 60px;
-    border-radius: 140px;
-  }
-  .btn-text {
-    font-size: 12px;
-    color: #d5e0f2;
-    font-weight: 400;
-    text-align: center;
-    margin-top: 10px;
-  }
-</style>
-```
-
-2. **Add the Reject button:** Bind the tap event to the `reject` method.
-
-```vue
-<template>
-  <view class="btn" @tap="handleReject">
-    <image class="btn-img" :src="REJECT_SRC"></image>
-    <text class="btn-text">Reject</text>
-  </view>
-</template>
-
-<script setup lang="ts">
-  import REJECT_SRC from "../../../static/icon/hangup.png"; // Replace with the actual icon path in your project
-  import { useCallState } from '@/uni_modules/tuikit-atomic-x/state/CallState';
-
-  const { reject } = useCallState();
-
-  const handleReject = () => {
-    reject();
-  };
-</script>
-
-<style scoped>
-  .btn {
-    margin: 10px 20px;
-  }
-  .btn-img {
-    width: 60px;
-    height: 60px;
-    border-radius: 140px;
-  }
-  .btn-text {
-    font-size: 12px;
-    color: #d5e0f2;
-    font-weight: 400;
-    text-align: center;
-    margin-top: 10px;
-  }
-</style>
-```
-
-3. **Dismiss the UI when the caller cancels or you reject:** Both cases fire the `onCallEnded` event. Subscribe to it and dismiss the call UI when the call terminates.
-
-```typescript
-import { useCallState } from '@/uni_modules/tuikit-atomic-x/state/CallState';
-import { useDeviceState } from '@/uni_modules/tuikit-atomic-x/state/DeviceState';
-
-const { addCallListener } = useCallState();
-const { closeLocalCamera, closeLocalMicrophone } = useDeviceState();
-
-/**
- * Initialize the call service (minimal example: handle only the call-end event and navigate back).
- * It is recommended to invoke this on app startup.
- */
-export function initCallService() {
-  addCallListener('onCallEnded', (event: string) => {
-    let res: any;
-    try {
-      res = JSON.parse(event);
-    } catch (error) {
-      console.error('[CallService] onCallEnded parse error:', error);
-      return;
-    }
-    console.log('[CallService] onCallEnded, reason:', res.reason);
-
-    // Close local devices
-    closeLocalCamera();
-    closeLocalMicrophone();
-
-    // Navigate back
-    const pages = getCurrentPages();
-    if (pages.length > 1) {
-      uni.navigateBack({ delta: 1 });
-    } else {
-      uni.redirectTo({ url: '/pages/index/index' }); // Example path; replace with the actual path in your project
-    }
-  });
-}
-```
-
-### Step 3: Launch the Call UI on an Incoming Call
-
-Subscribe to the incoming-call event (`onCallReceived`) in your project, and launch the call page when a call arrives. Implementation:
-
-1. **Listen for the incoming-call event:** Subscribe to `onCallReceived`.
-2. **Launch the call page:** Navigate to the call page when the event fires.
-
-```typescript
-import { useCallState } from '@/uni_modules/tuikit-atomic-x/state/CallState';
-
-const { addCallListener } = useCallState();
-
-// Call page route
-const CALL_PAGE = '/uni_modules/tuikit-atomic-x/pages/call'; // Replace with the actual path created in Step 1
-
-// Recommended to invoke on app startup
-export function initCallService() {
-  addCallListener('onCallReceived', (event: string) => {
-    uni.navigateTo({
-      url: CALL_PAGE
-    });
-  });
-}
-```
-
-### Step 4: Play Incoming-Call Ringtone
-
-Subscribe to the incoming-call event (`onCallReceived`) and play a ringtone when a call arrives. Implementation:
-
-1. **Listen for the incoming-call event:** Subscribe to `onCallReceived`.
-2. **Play the ringtone:** Play a ringtone when the event fires; stop it when the call is connected or ended.
-
-```typescript
-import { watch } from 'vue';
-import { useCallState } from '@/uni_modules/tuikit-atomic-x/state/CallState';
-
-const { addCallListener, selfInfo } = useCallState();
-
-/**
- * Create or get the audio playback instance (singleton).
- */
-function ensureAudioContext() {
-  if (!uni.$innerAudioContext) {
-    const ctx = uni.createInnerAudioContext();
-    ctx.onError((err: any) => {
-      console.error('[CallService] innerAudioContext onError:', err?.errCode, err?.errMsg || err);
-    });
-    uni.$innerAudioContext = ctx;
-  }
-  return uni.$innerAudioContext;
-}
-
-/**
- * Play the ringtone.
- * @param src - Path to the ringtone file.
- */
-function playRingtone(src: string) {
-  const ctx = ensureAudioContext();
-  try {
-    ctx.stop();
-  } catch (_e) {}
-  ctx.src = src;
-  ctx.loop = true;
-  ctx.autoplay = true;
-  setTimeout(() => {
-    try {
-      ctx.play();
-    } catch (e) {
-      console.warn('[CallService] playRingtone play() error:', e);
-    }
-  }, 50);
-}
-
-/**
- * Stop the ringtone.
- */
-function stopRingtone() {
-  if (uni.$innerAudioContext) {
-    try {
-      uni.$innerAudioContext.loop = false;
-      uni.$innerAudioContext.stop();
-    } catch (e) {
-      console.warn('[CallService] stopRingtone error:', e);
-    }
-  }
-}
-
-export { playRingtone, stopRingtone };
-
-// Invoke on app startup
-export function initCallService() {
-  ensureAudioContext();
-
-  // Watch the call state: stop the ringtone when the call is connected (status === 2) or ended (status === 0)
-  watch(() => selfInfo.value, (newVal) => {
-    if (newVal?.status === 2 || newVal?.status === 0) {
-      stopRingtone();
-    }
-  }, { immediate: true, deep: true });
-
-  // Play the ringtone when an incoming call arrives
-  addCallListener('onCallReceived', () => {
-    playRingtone('/static/audio/ring.mp3');
-  });
-
-  // Stop the ringtone when the call ends
-  addCallListener('onCallEnded', () => {
-    stopRingtone();
-  });
-}
-```
-
-### Step 5: Open Media Devices on Incoming Call
-
-When an incoming call arrives, the `onCallReceived` event carries the media type. For a smoother user experience, pre-open the corresponding media devices when launching the call UI. Implementation:
-
-1. **Listen for the incoming-call event:** Subscribe to `onCallReceived`.
-2. **Open devices based on the media type:** For audio calls, open the microphone only; for video calls, open both microphone and camera.
-
-```typescript
-import { useCallState } from '@/uni_modules/tuikit-atomic-x/state/CallState';
-import { useDeviceState } from '@/uni_modules/tuikit-atomic-x/state/DeviceState';
-
-const { addCallListener } = useCallState();
-const { openLocalCamera, openLocalMicrophone } = useDeviceState();
-
-// Call page route
-const CALL_PAGE = '/uni_modules/tuikit-atomic-x/pages/call'; // Replace with the actual path created in Step 1
-
-// Invoke on app startup
-export function initCallService() {
-  addCallListener('onCallReceived', (event: string) => {
-    let res: any;
-    try {
-      res = JSON.parse(event);
-    } catch (error) {
-      console.error('[CallService] onCallReceived parse error:', error);
-      return;
-    }
-
-    // Open the camera for video calls
-    if (res.mediaType === 1) {
-      openLocalCamera({ isFront: true });
-    }
-
-    // Open the microphone
-    openLocalMicrophone();
-
-    // Navigate to the call page
-    uni.navigateTo({
-      url: CALL_PAGE
-    });
-  });
-}
-```
-
-### Demo Result
-
-After completing the steps above, the "answer a call" feature is now ready to use.
-
-## Customize the UI
-
-`CallCoreView` provides extensive UI customization. You can freely replace avatars and indicator icons. For fast integration, download icons directly from **GitHub**. They are designed by our team for TUICallKit and are copyright-free.
-
-### Customize Volume Level Icons
-
-Set the `volumeLevelIcons` property of `CallCoreView` to assign icons for each volume level.
-
-**Sample code for `volumeLevelIcons`:**
-
-```vue
-<template>
-  <view class="call-view-container">
-    <view :style="{ height: systemInfo?.windowHeight + 'px', width: systemInfo?.safeArea?.width + 'px' }">
-      <call-core-view
-        :style="{ height: systemInfo?.windowHeight + 'px', width: systemInfo?.safeArea?.width + 'px' }"
-        :volumeLevelIcons="volumeLevelIcons"
-      ></call-core-view>
-    </view>
-  </view>
-</template>
-
-<script setup>
-  import { ref, onMounted } from 'vue';
-
-  const systemInfo = ref({});
-
-  /**
-   * Convert a `/static/` relative path into a local absolute path usable by the native layer.
-   */
-  function toAbsolutePath(relativePath) {
-    if (plus && plus.io && plus.io.convertLocalFileSystemURL) {
-      return plus.io.convertLocalFileSystemURL(relativePath);
-    }
-    return relativePath;
-  }
-
-  /**
-   * Batch-convert every value in the object into an absolute path.
-   */
-  function convertIconPaths(iconMap) {
-    const result = {};
-    Object.keys(iconMap).forEach(key => {
-      result[key] = toAbsolutePath(iconMap[key]);
-    });
-    return result;
-  }
-
-  // Volume-level icons: key is the level name, value is the local absolute path.
-  const volumeLevelIcons = ref(convertIconPaths({
-    "Mute": "/static/images/callview-self-mute.png", // Replace with the actual icon path in your project
-    "Low":  "/static/images/callview-network.png"    // Replace with the actual icon path in your project
-  }));
-
-  onMounted(() => {
-    uni.getSystemInfo({
-      success: (res) => {
-        systemInfo.value = res;
-      }
-    });
-  });
-</script>
-
-<style>
-  .call-view-container {
-    background: rgba(15, 16, 20, 0.5);
-    overflow: hidden;
-  }
-</style>
-```
-
-> **Note:**
->
-> Parameters that uni-app passes to the native layer only support local paths, so the relative path must be converted to an absolute local path.
-
-**Property details:**
-
-| **Parameter** | **Type** | **Required** | **Description** |
-| --- | --- | --- | --- |
-| `icons` | \[String: String\] | Yes | Mapping between volume levels and icon resources. Keys (`VolumeLevel`): `Mute` (microphone muted), `Low` (0-25], `Medium` (25-50], `High` (50-75], `Peak` (75-100]. Values (`String`): icon resource paths for each level. |
-
-**Volume-level icons:**
-
-| **Description** | **Download** |
-| --- | --- |
-| Volume indicator icon. Recommended for `Low` or `Medium` — displayed when the user's volume exceeds the configured level. | [GitHub](https://github.com/Tencent-RTC/TUIKit_uni-app/blob/main/App/static/images/callview-network.png) |
-| Mute icon. Recommended for `Mute` — displayed when the user is muted. | [GitHub](https://github.com/Tencent-RTC/TUIKit_uni-app/blob/main/App/static/images/callview-self-mute.png) |
-
-### Customize Network Quality Icons
-
-Set the `networkQualityIcons` property of `CallCoreView` to assign icons for each network-quality state.
-
-**Sample code for `networkQualityIcons`:**
-
-```vue
-<template>
-  <view class="call-view-container">
-    <view :style="{ height: systemInfo?.windowHeight + 'px', width: systemInfo?.safeArea?.width + 'px' }">
-      <call-core-view
-        :style="{ height: systemInfo?.windowHeight + 'px', width: systemInfo?.safeArea?.width + 'px' }"
-        :networkQualityIcons="networkQualityIcons"
-      ></call-core-view>
-    </view>
-  </view>
-</template>
-
-<script setup>
-  import { ref, onMounted } from 'vue';
-
-  const systemInfo = ref({});
-
-  /**
-   * Convert a `/static/` relative path into a local absolute path usable by the native layer.
-   */
-  function toAbsolutePath(relativePath) {
-    if (plus && plus.io && plus.io.convertLocalFileSystemURL) {
-      return plus.io.convertLocalFileSystemURL(relativePath);
-    }
-    return relativePath;
-  }
-
-  /**
-   * Batch-convert every value in the object into an absolute path.
-   */
-  function convertIconPaths(iconMap) {
-    const result = {};
-    Object.keys(iconMap).forEach(key => {
-      result[key] = toAbsolutePath(iconMap[key]);
-    });
-    return result;
-  }
-
-  const networkQualityIcons = ref(convertIconPaths({
-    "BAD":      "/static/images/callview-network-bad.png", // Replace with the actual icon path in your project
-    "VERY_BAD": "/static/images/callview-network-bad.png"  // Replace with the actual icon path in your project
-  }));
-
-  onMounted(() => {
-    uni.getSystemInfo({
-      success: (res) => {
-        systemInfo.value = res;
-      }
-    });
-  });
-</script>
-
-<style>
-  .call-view-container {
-    background: rgba(15, 16, 20, 0.5);
-    overflow: hidden;
-  }
-</style>
-```
-
-**`networkQualityIcons` parameter details:**
-
-| **Parameter** | **Type** | **Required** | **Description** |
-| --- | --- | --- | --- |
-| `icons` | \[String: String\] | Yes | Mapping between network-quality levels and icon resources. Keys (`String`): `UNKNOWN`, `EXCELLENT`, `GOOD`, `POOR`, `BAD`, `VERY_BAD`, `DOWN`. Values (`String`): icon resource paths for each state. |
-
-**Poor-network indicator icon:**
-
-| **Description** | **Download** |
-| --- | --- |
-| Poor-network indicator icon. Recommended for `BAD`, `VERY_BAD`, or `DOWN` — displayed when the network condition is poor. | [GitHub](https://github.com/Tencent-RTC/TUIKit_uni-app/blob/main/App/static/images/callview-network-bad.png) |
-
-### Customize Default Avatar
-
-Set the `participantAvatars` property of `CallCoreView` to assign user avatars. We recommend watching the reactive `allParticipants` data (all participants in the call): set and display each user's avatar when it is available; show a default avatar (placeholder) when the user has no avatar or loading fails.
-
-**Sample code for `participantAvatars`:**
-
-```vue
-<template>
-  <view class="call-view-container">
-    <view :style="{ height: systemInfo?.windowHeight + 'px', width: systemInfo?.safeArea?.width + 'px' }">
-      <call-core-view
-        :style="{ height: systemInfo?.windowHeight + 'px', width: systemInfo?.safeArea?.width + 'px' }"
-        :participantAvatars="participantAvatars"
-      ></call-core-view>
-    </view>
-  </view>
-</template>
-
-<script setup>
-  import { ref, watch, onMounted } from 'vue';
-  import { useCallState } from '@/uni_modules/tuikit-atomic-x/state/CallState';
-
-  const { allParticipants } = useCallState();
-  const systemInfo = ref({});
-  const participantAvatars = ref({});
-  const avatarCache = {};
-  const DEFAULT_AVATAR_URL = "https://liteav.sdk.qcloud.com/app/res/picture/voiceroom/avatar/user_avatar1.png";
-
-  let defaultAvatarLocalPath = "";
-  let defaultAvatarReady = false;
-
-  /**
-   * Convert a relative path into a local absolute path usable by the native layer.
-   */
-  function toAbsolutePath(relativePath) {
-    if (plus && plus.io && plus.io.convertLocalFileSystemURL) {
-      return plus.io.convertLocalFileSystemURL(relativePath);
-    }
-    return relativePath;
-  }
-
-  /**
-   * Download and cache an avatar; return the local absolute path.
-   */
-  function downloadAvatar(url) {
-    if (avatarCache[url]) {
-      return Promise.resolve(avatarCache[url]);
-    }
-    return new Promise((resolve) => {
-      uni.downloadFile({
-        url,
-        success: (res) => {
-          if (res.statusCode === 200) {
-            const absolutePath = toAbsolutePath(res.tempFilePath);
-            avatarCache[url] = absolutePath;
-            resolve(absolutePath);
-          } else {
-            resolve(defaultAvatarLocalPath || "");
-          }
-        },
-        fail: () => {
-          resolve(defaultAvatarLocalPath || "");
-        }
-      });
-    });
-  }
-
-  // Pre-download the default avatar
-  const defaultAvatarPromise = downloadAvatar(DEFAULT_AVATAR_URL).then(localPath => {
-    defaultAvatarLocalPath = localPath;
-    defaultAvatarReady = true;
-
-    // Once the default avatar is ready, refresh participant avatars once
-    if (allParticipants.value && allParticipants.value.length > 0) {
-      updateParticipantAvatars(allParticipants.value);
-    }
-  });
-
-  /**
-   * Download avatars for the given participant list and build a { userId: localPath } map.
-   */
-  async function updateParticipantAvatars(participants) {
-    if (!participants || participants.length === 0) {
-      participantAvatars.value = {};
-      return;
-    }
-
-    if (!defaultAvatarReady && defaultAvatarPromise) {
-      await defaultAvatarPromise;
-    }
-
-    const avatarMap = {};
-    const tasks = [];
-    participants.forEach(participant => {
-      if (participant.id && participant.avatarURL) {
-        tasks.push(
-          downloadAvatar(participant.avatarURL).then(localPath => {
-            avatarMap[participant.id] = localPath;
-          })
-        );
-      } else if (participant.id) {
-        avatarMap[participant.id] = defaultAvatarLocalPath || "";
-      }
-    });
-    await Promise.all(tasks);
-    participantAvatars.value = avatarMap;
-  }
-
-  // Watch participants and update the avatar map
-  watch(() => allParticipants.value, async (newVal) => {
-    if (!newVal) return;
-    await updateParticipantAvatars(newVal);
-  }, { immediate: true, deep: true });
-
-  onMounted(() => {
-    uni.getSystemInfo({
-      success: (res) => {
-        systemInfo.value = res;
-      }
-    });
-  });
-</script>
-
-<style>
-  .call-view-container {
-    background: rgba(15, 16, 20, 0.5);
-    overflow: hidden;
-  }
-</style>
-```
-
-**`participantAvatars` parameter details:**
-
-| **Parameter** | **Type** | **Required** | **Description** |
-| --- | --- | --- | --- |
-| `avatars` | \[String: String\] | Yes | User-avatar map. Key: the user's `userID`. Value: the absolute local path of that user's avatar resource. |
-
-**Default avatar resource:**
-
-| **Description** | **Download** |
-| --- | --- |
-| Default avatar. Recommended as a placeholder when the user's avatar fails to load or is not set. | [GitHub](https://github.com/Tencent-RTC/TUIKit_iOS/tree/main/atomic_x/Resources/AtomicX.xcassets/icon/call/default_participant_icon.imageset) |
-
-### Customize Loading Animation
-
-Set the `waitingAnimation` property of `CallCoreView` to display a waiting animation for users in the waiting state for a better experience.
-
-**Sample code for `waitingAnimation`:**
-
-```vue
-<template>
-  <view class="call-view-container">
-    <view :style="{ height: systemInfo?.windowHeight + 'px', width: systemInfo?.safeArea?.width + 'px' }">
-      <call-core-view
-        :style="{ height: systemInfo?.windowHeight + 'px', width: systemInfo?.safeArea?.width + 'px' }"
-        :waitingAnimation="waitingAnimation"
-      ></call-core-view>
-    </view>
-  </view>
-</template>
-
-<script setup>
-  import { ref, onMounted } from 'vue';
-
-  const systemInfo = ref({});
-
-  /**
-   * Convert a `/static/` relative path into a local absolute path usable by the native layer.
-   */
-  function toAbsolutePath(relativePath) {
-    if (plus && plus.io && plus.io.convertLocalFileSystemURL) {
-      return plus.io.convertLocalFileSystemURL(relativePath);
-    }
-    return relativePath;
-  }
-
-  // Waiting animation GIF: pass a local absolute path to the native component for rendering
-  const waitingAnimation = ref(toAbsolutePath("/static/images/callview-loading.gif")); // Replace with the actual icon path in your project
-
-  onMounted(() => {
-    uni.getSystemInfo({
-      success: (res) => {
-        systemInfo.value = res;
-      }
-    });
-  });
-</script>
-
-<style>
-  .call-view-container {
-    background: rgba(15, 16, 20, 0.5);
-    overflow: hidden;
-  }
-</style>
-```
-
-**`waitingAnimation` parameter details:**
-
-| **Parameter** | **Type** | **Required** | **Description** |
-| --- | --- | --- | --- |
-| `path` | String | Yes | Absolute path of the GIF image resource. |
-
-**Waiting animation:**
-
-| **Description** | **Download** |
-| --- | --- |
-| User waiting animation. Recommended for group calls — displayed when the user's status is `waiting`. | [GitHub](https://github.com/Tencent-RTC/TUIKit_uni-app/blob/main/App/static/images/callview-loading.gif) |
-
-### Add Call Duration Indicator
-
-The call duration is exposed in real time through the `duration` field of the reactive `activeCall` data. To display it:
-
-1. **Bind the call duration to the UI:** Bind the `activeCall.duration` field to the UI. The field is reactive and drives UI refresh automatically — no manual timer is required.
-
-```vue
-<template>
-  <view v-if="isConnected" class="call-timer">
-    <text class="timer-text">{{ formattedTime }}</text>
-  </view>
-</template>
-
-<script setup lang="ts">
-  import { computed } from 'vue';
-  import { useCallState } from '@/uni_modules/tuikit-atomic-x/state/CallState';
-
-  const { selfInfo, activeCall } = useCallState();
-
-  const isConnected = computed(() => {
-    return selfInfo.value?.status === 2;
-  });
-
-  const formattedTime = computed(() => {
-    const duration = activeCall.value?.duration ?? 0;
-    const hours = Math.floor(duration / 3600);
-    const minutes = Math.floor((duration % 3600) / 60);
-    const seconds = duration % 60;
-    const pad = (n: number) => n.toString().padStart(2, '0');
-    if (hours > 0) {
-      return `${pad(hours)}:${pad(minutes)}:${pad(seconds)}`;
-    }
-    return `${pad(minutes)}:${pad(seconds)}`;
-  });
-</script>
-
-<style scoped>
-  .call-timer {
-    display: flex;
-    align-items: center;
-    justify-content: center;
-  }
-  .timer-text {
-    font-size: 28rpx;
-    color: #FFFFFF;
-    font-weight: 400;
-  }
-</style>
-```
-
-## More Features
-
-### Customize User Avatar / Nickname
-
-Before the call starts, you can use `setSelfInfo` to set your own nickname and avatar.
-
-**Sample code for `setSelfInfo`:**
-
-```typescript
-import { useLoginState } from "@/uni_modules/tuikit-atomic-x/state/LoginState";
-
-const { setSelfInfo } = useLoginState();
-
-/**
- * Set the personal info (nickname, avatar, etc.) of the currently logged-in user.
- */
-export const setSelfUserInfo = (userID: string, nickname: string, avatarURL: string): void => {
-  setSelfInfo({
-    userProfile: {
-      userID,
-      nickname,
-      avatarURL,
-    },
-    success: () => {
-      console.log('User info set successfully');
-    },
-    fail: (errCode: number, errMsg: string) => {
-      console.error('Failed to set user info:', errCode, errMsg);
-    },
-  });
-};
-```
-
-**`setSelfInfo` parameter details:**
-
-| **Parameter** | **Type** | **Required** | **Description** |
-| --- | --- | --- | --- |
-| `userProfile` | UserProfile | Yes | User info struct: `userID` (the user's ID), `avatarURL` (avatar URL), `nickname` (nickname). See `UserProfile` for more fields. |
-
-### Switch Layout Modes
-
-`CallCoreView` ships with three built-in layout modes. Set the `layoutTemplate` property to choose one. If not specified, `CallCoreView` adapts automatically based on the number of participants: 1-on-1 defaults to `Float` mode; multi-party calls switch to `Grid` mode. The layout modes are:
-
-| **Mode** | **Layout** | **Interaction** |
-| --- | --- | --- |
-| **Float** | Full-screen self-view while waiting; after connecting, full-screen remote view with a floating self-view. | The floating window can be dragged; tap it to swap with the main view. |
-| **Grid** | All participants are tiled in a grid layout — suitable for 2+ users. Tap to enlarge a single view. | Tap a participant's view to enlarge it. |
-| **PIP** | 1v1 always shows the remote view; multi-party uses the active-speaker strategy and full-screen the current speaker. | While waiting, the self-view is shown; after connecting, the call duration is displayed. |
-
-**Sample code for `layoutTemplate`:**
-
-```vue
-<template>
-  <view class="call-view-container">
-    <view :style="{ height: systemInfo?.windowHeight + 'px', width: systemInfo?.safeArea?.width + 'px' }">
-      <call-core-view
-        :style="{ height: systemInfo?.windowHeight + 'px', width: systemInfo?.safeArea?.width + 'px' }"
-        :layoutTemplate="layoutTemplate"
-      ></call-core-view>
-    </view>
-  </view>
-</template>
-
-<script setup>
-  import { ref, watch, onMounted } from 'vue';
-  import { useCallState } from '@/uni_modules/tuikit-atomic-x/state/CallState';
-
-  const { activeCall } = useCallState();
-  const systemInfo = ref({});
-  // Layout template: 'Float' for single floating-window layout, 'Grid' for multi-party tile layout
-  const layoutTemplate = ref("Grid");
-
-  // Switch layout automatically based on call info: Grid for multi-party / group, Float for 1-on-1
-  watch(() => activeCall.value, (newValue) => {
-    if (!newValue || !newValue.inviteeIds) {
-      return;
-    }
-    const newTemplate = (newValue.inviteeIds.length > 1 || newValue.chatGroupId !== '') ? 'Grid' : 'Float';
-    if (layoutTemplate.value !== newTemplate) {
-      layoutTemplate.value = newTemplate;
-    }
-  }, { immediate: true, deep: true });
-
-  onMounted(() => {
-    uni.getSystemInfo({
-      success: (res) => {
-        systemInfo.value = res;
-      }
-    });
-  });
-</script>
-
-<style>
-  .call-view-container {
-    background: rgba(15, 16, 20, 0.5);
-    overflow: hidden;
-  }
-</style>
-```
-
-**`layoutTemplate` parameter details:**
-
-| **Parameter** | **Type** | **Description** |
-| --- | --- | --- |
-| `layoutTemplate` | String | Layout mode of `CallCoreView`. **Float**: full-screen self-view while waiting; after connecting, full-screen remote view with a floating self-view; floating window supports drag and tap-to-swap. **Grid**: all participants tiled in a grid; suitable for 2+ users; tap to enlarge a single view. **PIP**: 1v1 always shows the remote view; multi-party uses the active-speaker strategy and full-screen the current speaker; while waiting, the self-view is shown; after connecting, the call duration is displayed. |
-
-## FAQ
-
-### How can I keep the screen always on during a call?
-
-uni-app provides `uni.setScreenBrightness` for this purpose.
-
-### How do I disable the system swipe-back-to-previous-page behavior?
-
-- **iOS:** Set the `disableSwipeBack` property on the page. See the uni-app official documentation for details.
-- **Android:** Intercept the system swipe gesture and the physical Back key via `onBackPress`. Sample code:
-
-> **Note:**
->
-> Intercepting the system swipe gesture and the physical Back key with this approach requires the page to use a custom navigation bar.
-
-```vue
-<script setup>
-  import { onBackPress } from '@dcloudio/uni-app';
-
-  // Intercept the system swipe and physical Back key to avoid accidentally exiting during a call
-  onBackPress((option) => {
-    if (option.from === 'backbutton') {
-      return true; // Returning true blocks the default back behavior
-    }
-  });
-</script>
-```