@tencentcloud/sdk-mcp 1.4.1 → 1.4.2

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

@@ -0,0 +1,876 @@
+本文档将帮助您使用 **AtomicXCore SDK** 的 **DeviceStore**、**CallStore** 以及核心组件 **CallCoreView**，快速完成拨打电话功能。
+
+## 核心功能
+
+**AtomicXCore** 中用于搭建多人音视频通话场景所需要使用到的核心模块包含以下三个：
+
+| 模块 | 功能描述 |
+|------|----------|
+| [CallCoreView](https://liteav.sdk.cloudcachetci.com/doc/product/tuikit/atomic-x/android/zh/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.view/-call-core-view/index.html) | 通话视图核心组件。自动监听 CallStore 数据并完成画面渲染，同时提供布局切换、头像与图标配置等 UI 定制化能力。 |
+| [CallStore](https://liteav.sdk.cloudcachetci.com/doc/product/tuikit/atomic-x/android/zh/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.call/-call-store/index.html) | 通话生命周期管理：拨打电话、接通电话、拒接电话、挂断电话。实时获取参与通话人员音视频状态，通话计时、通话记录等数据。 |
+| [DeviceStore](https://liteav.sdk.cloudcachetci.com/doc/product/tuikit/atomic-x/android/zh/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.device/-device-store/index.html) | 音视频设备控制：麦克风（开关 / 音量）、摄像头（开关 / 切换 / 画质）、屏幕共享，设备状态实时监听。 |
+
+## 准备工作
+
+### 步骤1：开通服务
+
+请参见 开通服务，获取体验版或付费版 SDK。
+
+### 步骤2：集成 SDK
+
+1. 请在您的 **build.gradle** 文件中添加 `api "io.trtc.uikit:atomicx-core:latest.release"` 和 `api "com.tencent.imsdk:imsdk-plus:8.7.7201"` 依赖，然后执行 **Gradle Sync**。
+
+```kotlin
+dependencies {
+    api "io.trtc.uikit:atomicx-core:latest.release"
+    api "com.tencent.imsdk:imsdk-plus:8.7.7201"
+    // 其他依赖...
+}
+```
+
+2. 由于 SDK 内部使用了 Java 反射特性，需要将部分类加入不混淆名单。请在 `app` 目录下的 `proguard-rules.pro` 文件末尾添加如下代码。添加完后，点击右上角的 **Sync Now**，同步代码。
+
+```
+-keep class com.tencent.** { *; }
+```
+
+3. 在 `app` 目录下找到 `AndroidManifest.xml` 文件，在 `application` 节点中添加 `tools:replace="android:allowBackup"`，覆盖组件内的设置，使用自己的设置。
+
+```xml
+<application
+    android:name=".BaseApplication"
+    android:allowBackup="false"
+    android:icon="@drawable/app_ic_launcher"
+    android:label="@string/app_name"
+    android:largeHeap="true"
+    android:theme="@style/AppTheme"
+    tools:replace="android:allowBackup">
+```
+
+### 步骤3：初始化与登录流程
+
+启动通话服务需依次完成以下三步：
+
+1. **实例化 CallStore**：`CallStore.shared` 初始化通话数据层。
+2. **用户登录**：调用 `LoginStore.shared.login(...)` 完成 IM 登录。
+3. **初始化通话引擎**：登录成功后调用 `TUICallEngine.createInstance(context).init(sdkAppId, userId, userSig, null)` 初始化 TRTC 通话信令引擎（**必须调用，否则无法正常收发通话**）。
+
+示例代码如下：
+
+```kotlin
+class MainActivity : ComponentActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+
+        // CallStore 初始化
+        CallStore.shared
+
+        val sdkAppId = 1400000001    // 替换为您的 SDKAppID
+        val userId = "test_001"       // 替换为您的 UserID
+        val userSig = "xxxxxxxxxxx"   // 联调填临时 UserSig；MCP 已配置 sdkAppId、sdkSecretKey 时可由工具自动生成
+
+        LoginStore.shared.login(
+            this,
+            sdkAppId,
+            userId,
+            userSig,
+            object : CompletionHandler {
+                override fun onSuccess() {
+                    // 完成 TUICallEngine 的初始化
+                    TUICallEngine.createInstance(this@MainActivity).init(sdkAppId, userId, userSig, null)
+                    Log.d("Login", "login success")
+                }
+                override fun onFailure(code: Int, desc: String) {
+                    Log.e("Login", "login failed, code: $code, error: $desc")
+                }
+            }
+        )
+    }
+}
+```
+
+**登录接口参数说明：**
+
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| `userId` | String | 当前用户的唯一 ID，长度不超过32字节，不支持使用特殊字符，建议使用英文字母或数字。为避免多端登录冲突，请勿使用 1、123 等简单 ID。 |
+| `sdkAppId` | int | 从控制台获取，通常是以 140 或 160 开头的 10 位整数 |
+| `userSig` | String | IM 登录鉴权票据。联调可本地生成临时值（如 `GenerateTestUserSig.genTestUserSig`）；**Tencent RTC MCP Server** 已配置 `sdkAppId` 与 `sdkSecretKey` 时可由工具自动生成。**生产环境**须由业务服务端使用密钥签发 UserSig，勿在客户端存储或下发 SecretKey。 |
+
+## 实现步骤
+
+**发起通话前，请确保完成登录**，这是服务可用的必要前提。以下将分 5 步为您讲解如何"拨打一通电话"。
+
+### 步骤1：创建通话界面
+
+新建一个 Activity 作为通话宿主页面，通话页面绑定 `CallCoreView`：
+
+```kotlin
+class CallActivity : AppCompatActivity() {
+    private var callCoreView: CallCoreView? = null
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        callCoreView = CallCoreView(this)
+        setContentView(callCoreView)
+    }
+}
+```
+
+**CallCoreView 视图组件功能说明：**
+
+| 功能 | 说明 |
+|------|------|
+| 设置布局模式 | 支持自由切换布局模式，若未设置将根据通话人数自动适配 |
+| 设置头像 | 支持传入头像资源路径，为特定用户自定义头像 |
+| 设置音量提示图标 | 支持根据不同音量等级配置个性化的音量指示图标 |
+| 设置网络提示图标 | 支持根据实时网络质量配置对应的网络状态提示图标 |
+| 设置等待接听动画 | 多人通话场景下，支持传入 GIF 图像路径为待接听状态用户展示动画 |
+
+### 步骤2：添加通话控制按钮
+
+您可以参考 DeviceStore、CallStore 提供的 API，自定义添加您的按钮。
+
+- **DeviceStore 功能说明：** 麦克风（开关/音量）、摄像头（开关/切换/画质）、屏幕共享，设备状态实时监听。建议将对应方法绑定至按钮点击事件，并通过监听设备状态变更来实时刷新按钮的 UI 状态。
+- **CallStore 功能说明：** 接听、挂断、拒接等核心通话控制能力。建议将对应方法绑定至按钮点击事件，并监听通话状态的变化，以确保按钮显示与当前通话阶段保持同步。
+
+**图标资源下载：** 按钮图标可以直接从 GitHub 下载。这些图标由设计师专为 TUICallKit 打造，无版权风险，可放心使用。
+
+图标资源目录：https://github.com/Tencent-RTC/TUIKit_Android/tree/main/atomic_x/src/main/res-callview/drawable-xxhdpi
+
+| 文件名 | 用途 |
+|--------|------|
+| callview_ic_dialing.png | 拨号图标 |
+| callview_ic_hangup.png | 挂断图标 |
+| callview_ic_camera_enable.png | 摄像头开启 |
+| callview_ic_camera_disable.png | 摄像头关闭 |
+| callview_ic_mic_unmute.png | 麦克风开启 |
+| callview_ic_mic_mute.png | 麦克风静音 |
+| callview_ic_handsfree_enable.png | 免提开启 |
+| callview_ic_handsfree_disable.png | 免提关闭 |
+
+#### 2.1 创建底部栏容器
+
+在通话页面底部创建一个容器，用于添加挂断、麦克风、摄像头按钮。
+
+```kotlin
+import io.trtc.tuikit.atomicxcore.api.call.CallStore
+import io.trtc.tuikit.atomicxcore.api.view.CallCoreView
+import io.trtc.tuikit.atomicxcore.api.device.DeviceStore
+
+class CallActivity : AppCompatActivity() {
+    private var buttonContainer: LinearLayout? = null
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        createButtonContainer()
+        setContentView(buttonContainer)
+    }
+
+    private fun createButtonContainer() {
+        buttonContainer = LinearLayout(this).apply {
+            orientation = LinearLayout.HORIZONTAL
+            gravity = Gravity.CENTER
+            layoutParams = FrameLayout.LayoutParams(
+                FrameLayout.LayoutParams.MATCH_PARENT,
+                FrameLayout.LayoutParams.WRAP_CONTENT
+            ).apply {
+                gravity = Gravity.BOTTOM
+                bottomMargin = dpToPx(80)
+            }
+        }
+    }
+}
+```
+
+#### 2.2 添加挂断按钮
+
+在点击事件中调用 `hangup` 接口并销毁页面：
+
+```kotlin
+class CallActivity : AppCompatActivity() {
+    private var buttonContainer: LinearLayout? = null
+    private var buttonHangup: Button? = null
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        addHangupButton()
+        setContentView(buttonContainer)
+    }
+
+    private fun addHangupButton() {
+        buttonHangup = Button(this).apply {
+            text = "挂断"
+            layoutParams = LinearLayout.LayoutParams(0, LinearLayout.LayoutParams.WRAP_CONTENT, 1f).apply {
+                marginEnd = dpToPx(8)
+            }
+            setOnClickListener {
+                CallStore.shared.hangup(null)
+                finish()
+            }
+        }
+        buttonContainer?.addView(buttonHangup)
+    }
+}
+```
+
+#### 2.3 添加麦克风开关按钮
+
+调用 `openLocalMicrophone` 或 `closeLocalMicrophone` 接口：
+
+```kotlin
+class CallActivity : AppCompatActivity() {
+    private var buttonContainer: LinearLayout? = null
+    private var buttonMicrophone: Button? = null
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        addMicrophoneButton()
+        setContentView(buttonContainer)
+    }
+
+    private fun addMicrophoneButton() {
+        buttonMicrophone = Button(this).apply {
+            layoutParams = LinearLayout.LayoutParams(0, LinearLayout.LayoutParams.WRAP_CONTENT, 1f).apply {
+                setMargins(16, 0, 16, 0)
+            }
+            setOnClickListener {
+                val isMicrophoneOpen = DeviceStore.shared().deviceState.microphoneStatus.value == DeviceStatus.ON
+                if (isMicrophoneOpen) {
+                    DeviceStore.shared().closeLocalMicrophone()
+                } else {
+                    DeviceStore.shared().openLocalMicrophone(null)
+                }
+            }
+        }
+        val isMicrophoneOpen = DeviceStore.shared().deviceState.microphoneStatus.value == DeviceStatus.ON
+        buttonMicrophone?.text = if (isMicrophoneOpen) "关麦克风" else "开麦克风"
+        buttonContainer?.addView(buttonMicrophone)
+    }
+}
+```
+
+#### 2.4 添加摄像头开关按钮
+
+调用 `openLocalCamera` 或 `closeLocalCamera` 接口：
+
+```kotlin
+class CallActivity : AppCompatActivity() {
+    private var buttonContainer: LinearLayout? = null
+    private var buttonCamera: Button? = null
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        addCameraButton()
+        setContentView(buttonContainer)
+    }
+
+    private fun addCameraButton() {
+        buttonCamera = Button(this).apply {
+            layoutParams = LinearLayout.LayoutParams(0, LinearLayout.LayoutParams.WRAP_CONTENT, 1f).apply {
+                setMargins(16, 0, 16, 0)
+            }
+            setOnClickListener {
+                val isCameraOpen = DeviceStore.shared().deviceState.cameraStatus.value == DeviceStatus.ON
+                if (isCameraOpen) {
+                    DeviceStore.shared().closeLocalCamera()
+                } else {
+                    val isFrontCamera = DeviceStore.shared().deviceState.isFrontCamera.value
+                    DeviceStore.shared().openLocalCamera(isFrontCamera, null)
+                }
+            }
+        }
+        val isCameraOpen = DeviceStore.shared().deviceState.cameraStatus.value == DeviceStatus.ON
+        buttonCamera?.text = if (isCameraOpen) "关摄像头" else "开摄像头"
+        buttonContainer?.addView(buttonCamera)
+    }
+}
+```
+
+#### 2.5 实时更新媒体设备按钮文本
+
+监听麦克风和摄像头的状态，实时更新按钮文本：
+
+```kotlin
+import io.trtc.tuikit.atomicxcore.api.call.*
+import io.trtc.tuikit.atomicxcore.api.device.DeviceStore
+import kotlinx.coroutines.*
+
+class CallActivity : AppCompatActivity() {
+    private var buttonCamera: Button? = null
+    private var buttonMicrophone: Button? = null
+    private var deviceStateJob: Job? = null
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        observeDeviceState()
+    }
+
+    private fun observeDeviceState() {
+        deviceStateJob = CoroutineScope(Dispatchers.Main).launch {
+            supervisorScope {
+                launch {
+                    DeviceStore.shared().deviceState.cameraStatus.collect { status ->
+                        buttonCamera?.text = if (status == DeviceStatus.ON) "关闭摄像头" else "开启摄像头"
+                    }
+                }
+                launch {
+                    DeviceStore.shared().deviceState.microphoneStatus.collect { status ->
+                        buttonMicrophone?.text = if (status == DeviceStatus.ON) "关闭麦克风" else "开启麦克风"
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+### 步骤3：申请麦克风/摄像头权限
+
+**1. 声明权限**（`AndroidManifest.xml`）：
+
+```xml
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="android.permission.RECORD_AUDIO" />
+    <uses-permission android:name="android.permission.CAMERA" />
+
+    <application>
+        <activity
+            android:name=".CallActivity"
+            android:exported="false"
+            android:screenOrientation="portrait" />
+    </application>
+</manifest>
+```
+
+**2. 动态申请权限：**
+
+```kotlin
+private fun requestAllCallPermissions() {
+    val allPermissions = arrayOf(
+        Manifest.permission.CAMERA,
+        Manifest.permission.RECORD_AUDIO
+    )
+    if (!checkPermissions(allPermissions)) {
+        ActivityCompat.requestPermissions(this, allPermissions, PERMISSION_REQUEST_CODE)
+    }
+}
+
+override fun onRequestPermissionsResult(
+    requestCode: Int,
+    permissions: Array<out String>,
+    grantResults: IntArray
+) {
+    super.onRequestPermissionsResult(requestCode, permissions, grantResults)
+    if (requestCode == PERMISSION_REQUEST_CODE) {
+        var allGranted = true
+        for (result in grantResults) {
+            if (result != PackageManager.PERMISSION_GRANTED) {
+                allGranted = false
+                break
+            }
+        }
+        if (allGranted) {
+            // 权限申请成功
+        } else {
+            // 部分权限被拒绝
+        }
+    }
+}
+```
+
+### 步骤4：发起通话
+
+在 `calls` 调用成功后跳转通话界面，根据媒体类型自动开启麦克风或摄像头：
+
+```kotlin
+import io.trtc.tuikit.atomicxcore.api.CompletionHandler
+import io.trtc.tuikit.atomicxcore.api.call.CallMediaType
+import io.trtc.tuikit.atomicxcore.api.call.CallStore
+
+class MainActivity : ComponentActivity() {
+
+    private fun startCall(userIdList: List<String>, mediaType: CallMediaType) {
+        CallStore.shared.calls(userIdList, mediaType, null, object : CompletionHandler {
+            override fun onFailure(code: Int, desc: String) {
+            }
+            override fun onSuccess() {
+                openDeviceForMediaType(mediaType)
+                val intent = Intent(this@MainActivity, CallActivity::class.java)
+                startActivity(intent)
+            }
+        })
+    }
+
+    private fun openDeviceForMediaType(mediaType: CallMediaType?) {
+        if (mediaType == null) {
+            return
+        }
+        DeviceStore.shared().openLocalMicrophone(null)
+        if (mediaType == CallMediaType.Video) {
+            val isFrontCamera = DeviceStore.shared().deviceState.isFrontCamera.value
+            DeviceStore.shared().openLocalCamera(isFrontCamera, null)
+        }
+    }
+}
+```
+
+**`calls` 接口参数说明：**
+
+| 参数 | 类型 | 是否必填 | 说明 |
+|------|------|----------|------|
+| `userIdList` | `List<String>` | 是 | 目标用户的 userId 列表 |
+| `mediaType` | `CallMediaType` | 是 | `CallMediaType.Video`：视频通话；`CallMediaType.Audio`：语音通话 |
+| `params` | `CallParams` | 否 | 扩展参数：`roomId`（房间ID）、`timeout`（超时秒数）、`userData`（自定义数据）、`chatGroupId`（群组ID）、`isEphemeralCall`（是否加密通话） |
+
+### 步骤5: 结束通话
+
+监听 `onCallEnded` 事件，通话结束时销毁页面：
+
+```kotlin
+import io.trtc.tuikit.atomicxcore.api.call.CallEndReason
+import io.trtc.tuikit.atomicxcore.api.call.CallListener
+import io.trtc.tuikit.atomicxcore.api.call.CallMediaType
+import io.trtc.tuikit.atomicxcore.api.call.CallStore
+
+class CallActivity : AppCompatActivity() {
+    private var callListener: CallListener? = null
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        addListener()
+    }
+
+    private fun addListener() {
+        callListener = object : CallListener() {
+            override fun onCallEnded(callId: String, mediaType: CallMediaType, reason: CallEndReason, userId: String) {
+                finish()
+            }
+        }
+        callListener?.let { CallStore.shared.addListener(it) }
+    }
+}
+```
+
+**`onCallEnded` 事件参数说明：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `callId` | String | 此次通话的唯一标识。 |
+| `mediaType` | [CallMediaType](https://liteav.sdk.cloudcachetci.com/doc/product/tuikit/atomic-x/android/zh/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.call/-call-media-type/index.html) | 通话媒体类型，用于指定发起音频通话还是视频通话。CallMediaType.Video：视频通话。CallMediaType.Audio：语音通话。 |
+| `reason` | [CallEndReason](https://liteav.sdk.cloudcachetci.com/doc/product/tuikit/atomic-x/android/zh/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.call/-call-end-reason/index.html) | 通话结束的原因。Unknown：未知原因，无法确定结束原因。Hangup：正常挂断，用户主动挂断通话。Reject：拒绝接听，被叫方拒绝来电。NoResponse：无响应，被叫方未在超时时间内接听。Offline：对方离线，被叫方不在线。LineBusy：对方忙线，被叫方正在通话中。Canceled：通话取消，主叫方在对方接听前取消。OtherDeviceAccepted：其他设备已接听，通话已在另一登录设备上接听。OtherDeviceReject：其他设备已拒绝，通话已在另一登录设备上拒绝。EndByServer：服务器结束，通话被服务器终止。 |
+| `userId` | String | 触发结束的用户 ID 。 |
+
+### 运行效果
+
+当您完成以上 5 步后，"拨打一通电话"运行效果如下：
+
+## 定制页面
+
+**CallCoreView** 提供了完善的 UI 定制能力，支持头像及音量提示等图标的自由替换。**为助力快速集成，您可以直接从** [GitHub](https://github.com/Tencent-RTC/TUIKit_Android/tree/main/atomic_x/src/main/res-callview/drawable-xxhdpi) **下载。这些图标由我们的设计师专为 TUICallKit 打造，无版权风险，可放心使用。**
+
+### 自定义音量提示的图标
+
+您可以调用 **CallCoreView** 组件的 [setVolumeLevelIcons](https://liteav.sdk.cloudcachetci.com/doc/product/tuikit/atomic-x/android/zh/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.view/-call-core-view/set-volume-level-icons.html) 设置音量大小等级不同的提示图标。
+
+**setVolumeLevelIcons 示例代码：**
+
+```kotlin
+private fun setIconResourcePath() {
+    val volumeLevelIcons = mapOf(VolumeLevel.Mute to "对应图标资源的路径")
+    val callCoreView = CallCoreView(context)
+    callCoreView.setVolumeLevelIcons(volumeLevelIcons)
+}
+```
+
+**setVolumeLevelIcons 接口参数详细说明：**
+
+| 参数 | 类型 | 是否必填 | 说明 |
+|------|------|----------|------|
+| icons | Map<VolumeLevel, String> | 是 | 音量等级与图标资源的映射表。Key（VolumeLevel）表示音量等级，Value（String）表示对应音量等级的图标资源路径 |
+
+**VolumeLevel 等级：**
+
+| 等级 | 说明 |
+|------|------|
+| `VolumeLevel.Mute` | 麦克风关闭，静音状态 |
+| `VolumeLevel.Low` | 音量范围 (0-25] |
+| `VolumeLevel.Medium` | 音量范围 (25-50] |
+| `VolumeLevel.High` | 音量范围 (50-75] |
+| `VolumeLevel.Peak` | 音量范围 (75-100] |
+
+**音量提示图标：**
+
+| 文件名 | 说明 | 下载地址 |
+|--------|------|----------|
+| callview_ic_audio_input.png | 【图标含义】音量提示图标。<br>【推荐用法】您可以将该图标等级设置为 `VolumeLevel.Low` 或 `VolumeLevel.Medium`，当用户音量大于对应等级时显示。 | https://github.com/Tencent-RTC/TUIKit_Android/blob/main/atomic_x/src/main/res-callview/drawable-xxhdpi/callview_ic_audio_input.png |
+| callview_ic_self_mute.png | 【图标含义】静音图标。<br>【推荐用法】您可以将该图标等级设置为 `VolumeLevel.Mute`，当该用户静音时显示。 | https://github.com/Tencent-RTC/TUIKit_Android/blob/main/atomic_x/src/main/res-callview/drawable-xxhdpi/callview_ic_self_mute.png |
+
+### 自定义网络提示图标
+
+您可以调用 **CallCoreView** 组件的 [setNetworkQualityIcons](https://liteav.sdk.cloudcachetci.com/doc/product/tuikit/atomic-x/android/zh/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.view/-call-core-view/set-network-quality-icons.html) 设置不同网络状态的提示图标。
+
+**setNetworkQualityIcons 示例代码：**
+
+```kotlin
+private fun setNetworkQualityIcons() {
+    val networkIcons = mapOf(NetworkQuality.BAD to "对应图标的路径")
+    val callCoreView = CallCoreView(context)
+    callCoreView.setNetworkQualityIcons(networkIcons)
+}
+```
+
+**setNetworkQualityIcons 接口参数详细说明：**
+
+| 参数 | 类型 | 是否必填 | 说明 |
+|------|------|----------|------|
+| icons | Map<NetworkQuality, String> | 是 | 网络质量与图标资源的映射表。Key（NetworkQuality）表示网络质量等级，Value（String）表示对应网络状态的图标资源路径 |
+
+**NetworkQuality 等级：**
+
+| 等级 | 说明 |
+|------|------|
+| `NetworkQuality.UNKNOWN` | 未知网络状态 |
+| `NetworkQuality.EXCELLENT` | 网络状态极佳 |
+| `NetworkQuality.GOOD` | 网络状态较好 |
+| `NetworkQuality.POOR` | 网络状态较差 |
+| `NetworkQuality.BAD` | 网络状态差 |
+| `NetworkQuality.VERY_BAD` | 网络状态极差 |
+| `NetworkQuality.DOWN` | 网络断开 |
+
+**网络较差的提示图标：**
+
+| 文件名 | 说明 | 下载地址 |
+|--------|------|----------|
+| callview_ic_network_bad.png | 【图标含义】网络较差的提示图标。<br>【推荐用法】您可以将该图标等级设置为 `NetworkQuality.BAD`、`NetworkQuality.VERY_BAD` 或 `NetworkQuality.DOWN`，当网络较差时显示该图标。 | https://github.com/Tencent-RTC/TUIKit_Android/blob/main/atomic_x/src/main/res-callview/drawable-xxhdpi/callview_ic_network_bad.png |
+
+### 自定义默认头像
+
+您可以调用 **CallCoreView** 的 [setParticipantAvatars](https://liteav.sdk.cloudcachetci.com/doc/product/tuikit/atomic-x/android/zh/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.view/-call-core-view/set-participant-avatars.html) 接口设置用户头像。建议您监听响应式数据 allParticipants（所有参与通话的成员）：当获取到用户头像时设置并展示；若用户未设置头像或加载失败，则显示默认头像（占位图）。
+
+**setParticipantAvatars 示例代码：**
+
+```kotlin
+private fun setParticipantAvatars() {
+    val avatars: MutableMap<String, String> = mutableMapOf()
+    val userId = ""       // 用户 ID
+    val avatarPath = ""   // 用户默认头像资源的路径
+    avatars[userId] = avatarPath
+    val callCoreView = CallCoreView(context)
+    callCoreView.setParticipantAvatars(avatars)
+}
+```
+
+**setParticipantAvatars 接口参数详细说明：**
+
+| 参数 | 类型 | 是否必填 | 说明 |
+|------|------|----------|------|
+| icons | Map<String, String> | 是 | 用户头像映射表。Key：用户的 userID。Value：该用户的头像资源绝对路径 |
+
+**默认头像资源：**
+
+| 文件名 | 说明 | 下载地址 |
+|--------|------|----------|
+| callview_ic_avatar.png | 【图标含义】默认头像。<br>【推荐用法】当用户头像加载失败或无头像时，您可以给该用户设置此默认头像。 | https://github.com/Tencent-RTC/TUIKit_Android/blob/main/atomic_x/src/main/res-callview/drawable-xxhdpi/callview_ic_avatar.png |
+
+### 自定义 loading 动画
+
+您可以调用 **CallCoreView** 的 [setWaitingAnimation](https://liteav.sdk.cloudcachetci.com/doc/product/tuikit/atomic-x/android/zh/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.view/-call-core-view/set-waiting-animation.html) 接口，为等待中用户设置等待动画获得更好的体验。
+
+**setWaitingAnimation 示例代码：**
+
+```kotlin
+private fun setWaitingAnimation() {
+    val waitingAnimationPath = ""  // 等待动画 GIF 图像资源的路径
+    val callCoreView = CallCoreView(context)
+    callCoreView.setWaitingAnimation(waitingAnimationPath)
+}
+```
+
+**setWaitingAnimation 接口参数详细说明：**
+
+| 参数 | 类型 | 是否必填 | 说明 |
+|------|------|----------|------|
+| path | String | 是 | GIF 格式图像资源的绝对路径 |
+
+**等待接听的动画：**
+
+| 文件名 | 说明 | 下载地址 |
+|--------|------|----------|
+| callview_ic_loading.gif | 【图标含义】用户等待接听动画。<br>【推荐用法】群组通话时设置的动画。设置后，当用户的状态为等待接听时，显示该动画。 | https://github.com/Tencent-RTC/TUIKit_Android/blob/main/atomic_x/src/main/res-callview/drawable-xxhdpi/callview_ic_loading.gif |
+
+### 添加通话计时提示
+
+通过响应式数据 `activeCall` 的 `duration` 字段实时获取通话计时：
+
+```kotlin
+import android.content.Context
+import androidx.appcompat.widget.AppCompatTextView
+import com.tencent.qcloud.tuicore.util.DateTimeUtil
+import io.trtc.tuikit.atomicxcore.api.call.CallStore
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.launch
+
+class TimerView(context: Context) : AppCompatTextView(context) {
+    private var subscribeStateJob: Job? = null
+
+    override fun onAttachedToWindow() {
+        super.onAttachedToWindow()
+        registerActiveCallObserver()
+    }
+
+    private fun registerActiveCallObserver() {
+        subscribeStateJob = CoroutineScope(Dispatchers.Main).launch {
+            CallStore.shared.observerState.activeCall.collect { activeCall ->
+                updateDurationView(activeCall)
+            }
+        }
+    }
+
+    private fun updateDurationView(activeCall: CallInfo) {
+        val currentDuration = activeCall.duration
+        text = DateTimeUtil.formatSecondsTo00(currentDuration.toInt())
+    }
+
+    override fun onDetachedFromWindow() {
+        super.onDetachedFromWindow()
+        subscribeStateJob?.cancel()
+    }
+}
+```
+
+## 更多功能
+
+### 设置头像和昵称
+
+通话开始前，您可以通过 setSelfInfo 方法，设置自己的昵称和头像。
+
+```kotlin
+val user = UserProfile()
+user.userID = ""        // 您的 userId
+user.avatarURL = ""     // 头像的 url
+user.nickname = ""      // 需要设置的昵称
+
+LoginStore.shared.setSelfInfo(user, object : CompletionHandler {
+    override fun onSuccess() {
+        // 设置成功回调
+    }
+    override fun onFailure(code: Int, desc: String) {
+        // 设置失败回调
+    }
+})
+```
+
+### 切换布局模式
+
+| 模式 | 适用场景 | 视觉效果 |
+|------|---------|---------|
+| **Float** | 1v1 通话 | 全屏显示对方画面，己方以可拖拽悬浮小窗展示在右上角，点击可互换大小画面 |
+| **Grid** | 2人以上 | 所有成员画面等分网格平铺，2人时左右各半，4人时2×2，支持点击放大 |
+| **Pip** | 1v1 或多人 | 1v1 固定显示对方画面；多人时自动展示正在说话的用户（Active Speaker 策略） |
+
+```kotlin
+private fun setLayoutTemplate() {
+    val callCoreView = CallCoreView(context)
+    val template = CallLayoutTemplate.Grid
+    callCoreView.setLayoutTemplate(template)
+    setContentView(callCoreView)
+}
+```
+
+### 设置通话的默认超时时间
+
+您可以在发起通话 calls 时，通过配置参数 CallParams 中的 `timeout` 字段来指定等待超时时间。
+
+```kotlin
+val callParams = CallParams()
+callParams.timeout = 30  // 设置通话超时（秒）
+CallStore.shared.calls(userIdList, CallMediaType.Video, callParams, null)
+```
+
+### 实现画中画功能
+
+需 Android 8.0 (API 26) 及以上支持。
+
+**进入画中画：**
+
+```kotlin
+private fun enterPictureInPictureModeWithBuild() {
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O && hasPipModePermission()) {
+        val pictureInPictureParams: PictureInPictureParams.Builder = PictureInPictureParams.Builder()
+        val floatViewWidth = resources.getDimensionPixelSize(R.dimen.callkit_video_small_view_width)
+        val floatViewHeight = resources.getDimensionPixelSize(R.dimen.callkit_video_small_view_height)
+        val aspectRatio = Rational(floatViewWidth, floatViewHeight)
+        pictureInPictureParams.setAspectRatio(aspectRatio).build()
+        this.enterPictureInPictureMode(pictureInPictureParams.build())
+    }
+}
+```
+
+**进入画中画成功后切换布局：**
+
+```kotlin
+val callCoreView = CallCoreView(context)
+
+override fun onPictureInPictureModeChanged(isInPictureInPictureMode: Boolean) {
+    super.onPictureInPictureModeChanged(isInPictureInPictureMode)
+    if (isInPictureInPictureMode) {
+        callCoreView.setLayoutTemplate(CallLayoutTemplate.Pip)
+    }
+}
+```
+
+**从画中画返回时恢复布局：**
+
+```kotlin
+override fun onResume() {
+    super.onResume()
+    val allParticipants = CallStore.shared.observerState.allParticipants.value
+    if (allParticipants.size > 2) {
+        callCoreView?.setLayoutTemplate(CallLayoutTemplate.Grid)
+    } else {
+        callCoreView?.setLayoutTemplate(CallLayoutTemplate.Float)
+    }
+}
+```
+
+> **注意**：需要在 `AndroidManifest.xml` 中为通话 Activity 声明独立任务栈，避免画中画时 UI 异常：
+> ```xml
+> <activity
+>     android:name=".view.CallActivity"
+>     android:launchMode="singleTask"
+>     android:taskAffinity="${applicationId}.call" />
+> ```
+
+### 设置通话过程中屏幕常亮
+
+通话过程中保持屏幕常亮是通话应用的基本需求。Android 提供了 `WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON` 标志来实现此功能，这是最简单且推荐的方式。
+
+```kotlin
+class CallActivity : AppCompatActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        window.addFlags(
+            WindowManager.LayoutParams.FLAG_SHOW_WHEN_LOCKED or
+            WindowManager.LayoutParams.FLAG_DISMISS_KEYGUARD or
+            WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON or
+            WindowManager.LayoutParams.FLAG_TURN_SCREEN_ON
+        )
+        setContentView(R.layout.activity_call)
+    }
+}
+```
+
+### 播放等待接听的提示音
+
+您可以监听自己的通话状态，在等待接听时播放铃声，在接听通话或通话结束停止播放铃声。
+
+```kotlin
+MainScope().launch {
+    CallStore.shared.observerState.selfInfo.collect { selfInfo ->
+        if (selfInfo.status == CallParticipantStatus.Accept || selfInfo.status == CallParticipantStatus.None) {
+            // 停止播放铃声
+            return@collect
+        }
+        if (selfInfo.status == CallParticipantStatus.Waiting) {
+            // 播放铃声
+        }
+    }
+}
+```
+
+### 开启后台采集音频/视频
+
+**1. 配置权限与服务**（`AndroidManifest.xml`）：
+
+```xml
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_CAMERA"/>
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE"/>
+
+    <application>
+        <service
+            android:name=".CallForegroundService"
+            android:enabled="true"
+            android:exported="false"
+            android:foregroundServiceType="camera|microphone"/>
+    </application>
+</manifest>
+```
+
+**2. 创建前台服务类：**
+
+```kotlin
+import android.app.Notification
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.Service
+import android.content.Context
+import android.content.Intent
+import android.os.Build
+import android.os.IBinder
+import androidx.core.app.NotificationCompat
+
+class CallForegroundService : Service() {
+    companion object {
+        private const val NOTIFICATION_ID = 1001
+        private const val CHANNEL_ID = "call_foreground_channel"
+
+        fun start(context: Context) {
+            val intent = Intent(context, CallForegroundService::class.java)
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+                context.startForegroundService(intent)
+            } else {
+                context.startService(intent)
+            }
+        }
+
+        fun stop(context: Context) {
+            val intent = Intent(context, CallForegroundService::class.java)
+            context.stopService(intent)
+        }
+    }
+
+    override fun onCreate() {
+        super.onCreate()
+        createNotificationChannel()
+        startForeground(NOTIFICATION_ID, createNotification())
+    }
+
+    override fun onBind(intent: Intent?): IBinder? = null
+
+    private fun createNotification(): Notification {
+        return NotificationCompat.Builder(this, CHANNEL_ID)
+            .setContentTitle("正在通话中")
+            .setContentText("应用正在后台运行以保持通话")
+            .setSmallIcon(android.R.drawable.ic_menu_call)
+            .setPriority(NotificationCompat.PRIORITY_HIGH)
+            .build()
+    }
+
+    private fun createNotificationChannel() {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+            val channel = NotificationChannel(
+                CHANNEL_ID,
+                "通话保活服务",
+                NotificationManager.IMPORTANCE_HIGH
+            )
+            val manager = getSystemService(NotificationManager::class.java)
+            manager.createNotificationChannel(channel)
+        }
+    }
+}
+```
+
+## 常见问题
+
+### 进入画中画模式后，应用内跳转其他界面后画面异常？
+
+Android 的画中画模式基于任务栈运作，默认所有 Activity 共享同一任务栈。需在 `AndroidManifest.xml` 中为通话 Activity 声明独立任务栈（`launchMode="singleTask"` + 独立 `taskAffinity`）。
+
+### 在通话邀请超时时间内，被邀请者如果离线再上线，能否收到来电事件？
+
+单人通话时，如果在超时时间内上线，会触发来电邀请；群组通话，如果在超时时间内上线，会拉起未处理的 20 条群消息，如果存在通话邀请，则触发来电邀请事件。