@tencent-rtc/mcp 1.4.1 → 1.4.3

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

@@ -0,0 +1,1052 @@
+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. |
+
+## Make Your First Call
+
+### 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 hang up, microphone, and camera buttons.
+
+1. **Add the hang up button:** Create a hang up button and call `hangup` in its tap handler to end the call and dismiss the page.
+
+```vue
+<template>
+  <view class="btn" @tap="handleHangup">
+    <image class="btn-img" :style="[style]" :src="HANGUP_SRC"></image>
+    <text class="btn-text" v-if="isShowText">Hang up</text>
+  </view>
+</template>
+
+<script setup lang="ts">
+  import { computed } from "vue";
+  import HANGUP_SRC from "../../../static/icon/hangup.png"; // Replace with the icon path used in your project
+  import { useCallState } from '@/uni_modules/tuikit-atomic-x/state/CallState';
+
+  const { hangup } = useCallState();
+
+  const props = defineProps({
+    size: {
+      type: Number,
+      default: 60,
+    },
+    isShowText: {
+      type: Boolean,
+      default: true,
+    },
+  });
+
+  const style = computed(() => ({
+    width: props.size + "px",
+    height: props.size + "px",
+  }));
+
+  const handleHangup = () => {
+    hangup();
+    // In the tap handler, call hangup and dismiss the page
+  };
+</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>
+```
+
+2. **Add the microphone toggle button:** Call `openLocalMicrophone` or `closeLocalMicrophone` in the tap handler, and watch the microphone state to update the button text in real time.
+
+```vue
+<template>
+  <view class="btn" @tap="handleMic">
+    <image class="btn-img" :src="microphoneStatus === DeviceStatus.ON ? MIC_ON_SRC : MIC_OFF_SRC"></image>
+    <text class="btn-text">
+      {{ microphoneStatus === DeviceStatus.ON ? 'Mic on' : 'Mic off' }}
+    </text>
+  </view>
+</template>
+
+<script setup lang="ts">
+  import MIC_ON_SRC from "../../../static/icon/mic-on.png";   // Replace with the icon path used in your project
+  import MIC_OFF_SRC from "../../../static/icon/mic-off.png"; // Replace with the icon path used in your project
+  import {
+    useDeviceState,
+    DeviceStatus
+  } from '@/uni_modules/tuikit-atomic-x/state/DeviceState';
+
+  const {
+    microphoneStatus,
+    openLocalMicrophone,
+    closeLocalMicrophone,
+  } = useDeviceState();
+
+  // Toggle the microphone in the tap handler
+  const handleMic = () => {
+    if (microphoneStatus.value === DeviceStatus.ON) {
+      closeLocalMicrophone();
+    } else {
+      openLocalMicrophone();
+    }
+  };
+</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. **Add the camera toggle button:** Call `openLocalCamera` or `closeLocalCamera` in the tap handler, and watch the camera state to update the button text in real time.
+
+```vue
+<template>
+  <div class="btn" @tap="handleCamera">
+    <image class="btn-img" :src="cameraStatus === DeviceStatus.ON ? CAMERA_ON_SRC : CAMERA_OFF_SRC"></image>
+    <text class="btn-text">
+      {{ cameraStatus === DeviceStatus.ON ? 'Camera on' : 'Camera off' }}
+    </text>
+  </div>
+</template>
+
+<script setup lang="ts">
+  import CAMERA_ON_SRC from "../../../static/icon/camera-on.png";   // Replace with the icon path used in your project
+  import CAMERA_OFF_SRC from "../../../static/icon/camera-off.png"; // Replace with the icon path used in your project
+  import {
+    useDeviceState,
+    DeviceStatus
+  } from '@/uni_modules/tuikit-atomic-x/state/DeviceState';
+
+  const {
+    cameraStatus,
+    openLocalCamera,
+    closeLocalCamera,
+    isFrontCamera,
+  } = useDeviceState();
+
+  // Camera button tap handler
+  const handleCamera = () => {
+    if (cameraStatus.value === DeviceStatus.ON) {
+      closeLocalCamera();
+    } else {
+      openLocalCamera({ isFront: isFrontCamera.value });
+    }
+  };
+</script>
+
+<style>
+  .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>
+```
+
+### Step 3: Initiate a Call
+
+After `calls` returns successfully, navigate to the call page. For a smoother experience, we recommend opening the microphone (and the camera for video calls) automatically based on the media type. Implementation:
+
+1. **Initiate the call:** Call `calls`.
+2. **Open media devices:** After the call starts, open the microphone; if it is a video call, open the camera as well.
+3. **Launch the call page:** When the call starts successfully, navigate to the call page.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useCallState } from '@/uni_modules/tuikit-atomic-x/state/CallState';
+import { useDeviceState } from '@/uni_modules/tuikit-atomic-x/state/DeviceState';
+
+const { calls } = useCallState();
+const { openLocalCamera, openLocalMicrophone } = useDeviceState();
+const calleeUserID = ref('');
+const mediaType = ref(1); // 0: audio, 1: video
+
+const startCall = () => {
+  const userID = calleeUserID.value.trim();
+  if (!userID) {
+    uni.showToast({ icon: 'none', title: 'Please enter the target user ID' });
+    return;
+  }
+
+  // 1. Open local devices
+  if (mediaType.value === 1) {
+    openLocalCamera({ isFront: true });
+  }
+  openLocalMicrophone();
+
+  // 2. Initiate the call
+  calls({
+    participantIds: [userID],
+    mediaType: mediaType.value,
+    success: () => {
+      console.log('Call started successfully');
+      uni.navigateTo({
+        url: '/uni_modules/tuikit-atomic-x/pages/call?layoutTemplate=Float' // Example path; replace with the actual call page path created in Step 1
+      });
+    },
+    fail: (code: number, message: string) => {
+      console.error('Call start failed:', code, message);
+      uni.showToast({ icon: 'none', title: `Call failed: ${message}` });
+    }
+  });
+};
+</script>
+```
+
+### Step 4: End the Call
+
+Whether you call `hangup` or the remote side ends the call, the `onCallEnded` event is fired. Subscribe to this event and dismiss the call page when it fires. Implementation:
+
+1. **Listen for the call-end event:** Subscribe to `onCallEnded`.
+2. **Dismiss the call page:** When `onCallEnded` fires, close the call UI.
+
+```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
+    }
+  });
+}
+```
+
+**onCallEnded event parameters:**
+
+| **Parameter** | **Type** | **Description** |
+| --- | --- | --- |
+| `callId` | String | Unique identifier for this call. |
+| `mediaType` | CallMediaType | Media type of the call. `CallMediaType.Video`: video call. `CallMediaType.Audio`: audio call. |
+| `reason` | CallEndReason | Reason for the call ending. `Unknown`: unknown reason. `Hangup`: hung up by the user. `Reject`: rejected by the callee. `Busy`: callee is busy. `Cancel`: caller canceled before the callee answered. |
+| `userId` | String | User ID that triggered the end event. |
+
+### Demo Result
+
+After completing the steps above, the "make 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. |
+
+### Set the Default Call Timeout
+
+When initiating a call, specify the wait timeout via the `timeout` field in `CallParams`:
+
+```vue
+<script setup>
+import { ref } from 'vue';
+import { useCallState } from '@/uni_modules/tuikit-atomic-x/state/CallState';
+
+const { calls } = useCallState();
+const calleeUserID = ref('');
+const mediaType = ref(1); // 0: audio, 1: video
+
+const startCall = () => {
+  const userID = calleeUserID.value.trim();
+  if (!userID) {
+    uni.showToast({ icon: 'none', title: 'Please enter the target user ID' });
+    return;
+  }
+
+  calls({
+    participantIds: [userID],
+    mediaType: mediaType.value,
+    params: {
+      timeout: 30
+    },
+    success: () => {
+      console.log('Call started successfully');
+      uni.navigateTo({
+        url: '/uni_modules/tuikit-atomic-x/pages/call?layoutTemplate=Float' // Example path; replace with the actual call page path created in Step 1
+      });
+    },
+    fail: (code, message) => {
+      console.error('Call start failed:', code, message);
+      uni.showToast({ icon: 'none', title: `Call failed: ${message}` });
+    }
+  });
+};
+</script>
+```
+
+**`calls` parameter details:**
+
+| **Parameter** | **Type** | **Required** | **Description** |
+| --- | --- | --- | --- |
+| `participantIds` | Array | Yes | List of target user IDs. |
+| `mediaType` | CallMediaType | Yes | Media type. `CallMediaType.Video`: video call. `CallMediaType.Audio`: audio call. |
+| `params` | CallParams | No | Call extension parameters such as room ID, invitation timeout, etc. `roomId` (String): room ID; auto-assigned by the server if omitted. `timeout` (Int): call timeout in seconds. `userData` (String): custom user data. `chatGroupId` (String): Chat group ID for group calls. `isEphemeralCall` (Boolean): whether the call is ephemeral / encrypted (no call record). |
+
+### Play Waiting Ringtone
+
+Watch your own call state and play a ringtone while waiting for the callee to answer; stop the ringtone when the call is accepted or ends.
+
+```typescript
+import { watch } from 'vue';
+import { useCallState } from '@/uni_modules/tuikit-atomic-x/state/CallState';
+
+const { selfInfo } = useCallState();
+
+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;
+}
+
+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) {}
+  }, 50);
+}
+
+function stopRingtone() {
+  if (uni.$innerAudioContext) {
+    try {
+      uni.$innerAudioContext.loop = false;
+      uni.$innerAudioContext.stop();
+    } catch (e) {}
+  }
+}
+
+export { playRingtone, stopRingtone };
+
+// Recommended to invoke on app startup
+export function initCallService() {
+  ensureAudioContext();
+
+  // When the call is connected (status === 2) or ended (status === 0), stop the ringtone
+  watch(() => selfInfo.value, (newVal) => {
+    if (newVal?.status === 2 || newVal?.status === 0) {
+      stopRingtone();
+    }
+  }, { immediate: true, deep: true });
+}
+```
+
+## 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>
+```