@tencentcloud/sdk-mcp 1.4.0 → 1.4.2

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

@@ -0,0 +1,1154 @@
+本文档将帮助您使用 **AtomicXCore SDK** 的 **DeviceStore**、**CallStore** 以及核心组件 **CallCoreView**，快速完成拨打电话功能。
+
+## 核心功能
+
+**AtomicXCore** 中用于搭建多人音视频通话场景所需要使用到的核心模块包含以下三个：
+
+| 模块 | 功能描述 |
+|------|----------|
+| [CallCoreView](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callcoreview) | 通话视图核心组件。自动监听 CallStore 数据并完成画面渲染，同时提供布局切换、头像与图标配置等 UI 定制化能力。 |
+| [CallStore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callstore) | 通话生命周期管理：拨打电话、接通电话、拒接电话、挂断电话。实时获取参与通话人员音视频状态，通话计时、通话记录等数据。 |
+| [DeviceStore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/devicestore) | 音视频设备控制：麦克风（开关/音量）、摄像头（开关/切换/画质）、屏幕共享，设备状态实时监听。 |
+
+## 准备工作
+
+### 步骤1：开通服务
+
+请参见 开通服务，获取体验版或付费版 SDK。
+
+### 步骤2：集成 SDK
+
+**1. 添加 Pod 依赖：** 在您项目的 `Podfile` 文件中添加 `pod 'AtomicXCore'` 依赖。
+
+```ruby
+target 'YourProjectTarget' do
+    pod 'AtomicXCore'
+end
+```
+
+> **提示：** 若项目没有 Podfile 文件，在终端中进入到您的 `.xcodeproj` 目录下，然后执行 `pod init` 命令创建 `Podfile` 文件。
+
+**2. 安装组件：** 在终端进入到 `Podfile` 文件所在的目录，然后执行以下命令安装组件。
+
+```bash
+pod install --repo-update
+```
+
+> **提示：** 安装完成后，使用 `YourProjectName.xcworkspace` 文件打开项目。
+
+### 步骤3：初始化与登录流程
+
+启动通话服务需依次完成以下三步：
+
+1. **实例化 CallStore**：`let _ = CallStore.shared` 初始化通话数据层。
+2. **用户登录**：调用 `LoginStore.shared.login(...)` 完成 IM 登录。
+3. **初始化通话引擎**：登录成功后调用 `TUICallEngine.createInstance().init(...)` 初始化 TRTC 通话信令引擎（**必须调用，否则无法正常收发通话**）。
+
+示例代码如下：
+
+```swift
+import UIKit
+import AtomicXCore
+import RTCRoomEngine
+import Combine
+
+class ViewController: UIViewController {
+    var cancellables = Set<AnyCancellable>()
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+
+        // CallStore 初始化
+        let _ = CallStore.shared
+
+        // 配置您的信息
+        let userID = "test_001"  // 请替换为您的 UserID
+        let sdkAppID: Int = 1400000001  // 请替换为在控制台得到的 SDKAppID
+        let secretKey = "**************"  // 联调用 SDKSecretKey；勿打入正式包。MCP 可与 sdkAppID 一并配置
+
+        // 生成 UserSig：联调可用 GenerateTestUserSig；正式须服务端签发。MCP 已配置 sdkAppId、sdkSecretKey 时可由工具自动生成
+        let userSig = GenerateTestUserSig.genTestUserSig(
+            userID: userID,
+            sdkAppID: sdkAppID,
+            secretKey: secretKey
+        )
+
+        // 登录
+        LoginStore.shared.login(
+            sdkAppID: Int32(sdkAppID),
+            userID: userID,
+            userSig: userSig
+        ) { result in
+            switch result {
+            case .success:
+                Log.info("login success")
+                // 完成 TUICallEngine 的初始化
+                TUICallEngine.createInstance().`init`(Int32(sdkAppID), userId: userID, userSig: userSig) {
+                    Log.info("TUICallEngine init success")
+                } fail: { code, message in
+                    Log.error("TUICallEngine init failed, code: \(code), message: \(message ?? "")")
+                }
+            case .failure(let error):
+                Log.error("login failed, code: \(error.code), error: \(error.message)")
+            }
+        }
+    }
+}
+```
+
+**登录接口参数说明：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `userID` | String | 当前用户的唯一 ID，长度不超过32字节，不支持使用特殊字符，建议使用英文字母或数字。为避免多端登录冲突，请勿使用 1、123 等简单 ID。 |
+| `sdkAppID` | int | 从控制台获取，通常是以 140 或 160 开头的 10 位整数 |
+| `secretKey` | String | 与 `sdkAppID` 配套的 SDKSecretKey，仅用于联调时在本地计算 UserSig；勿随正式客户端分发。**Tencent RTC MCP Server** 可与 `sdkAppID` 一并配置后由工具生成 UserSig。 |
+| `userSig` | String | IM 登录鉴权票据。联调可本地生成临时值（如 [`GenerateTestUserSig.genTestUserSig`](https://github.com/Tencent-RTC/TUIKit_iOS/blob/main/application/Debug/GenerateTestUserSig.swift)）；**Tencent RTC MCP Server** 已配置 `sdkAppId` 与 `sdkSecretKey` 时可由工具自动生成。**生产环境**须由业务服务端使用密钥签发 UserSig，勿在客户端存储或下发 SecretKey。 |
+
+## 实现步骤
+
+> **发起通话前，请确保完成登录**，这是服务可用的必要前提。以下将分 5 步为您讲解如何"拨打一通电话"。
+
+### 步骤1：创建通话界面
+
+您需要创建一个通话页面，当发起通话时唤起通话页面，实现方式如下：
+
+1. **创建通话页面**：新建一个 UIViewController 作为通话宿主页面。
+2. **通话页面绑定 CallCoreView**：通话视图核心组件，自动监听 CallStore 数据并完成画面渲染。
+
+```swift
+import UIKit
+import AtomicXCore
+
+class CallViewController: UIViewController {
+    private var callCoreView: CallCoreView?
+
+    // 1.创建通话页面
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        view.backgroundColor = .black
+
+        // 2.通话页面绑定 CallCoreView
+        callCoreView = CallCoreView(frame: view.bounds)
+        callCoreView?.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+        if let callCoreView = callCoreView {
+            view.addSubview(callCoreView)
+        }
+    }
+}
+```
+
+**CallCoreView 视图组件功能说明：**
+
+| 功能 | 说明 | 参考文档 |
+|------|------|----------|
+| **设置布局模式** | 支持自由切换布局模式。若未设置，将根据通话人数自动适配布局。 | 切换布局模式 |
+| **设置头像** | 支持通过传入头像资源路径，为特定用户自定义头像。 | 自定义默认头像 |
+| **设置音量提示图标** | 支持根据不同音量等级，配置个性化的音量指示图标。 | 自定义音量提示的图标 |
+| **设置网络提示图标** | 支持根据实时网络质量，配置对应的网络状态提示图标。 | 自定义网络提示的图标 |
+| **设置等待接听用户的动画** | 在多人通话场景下，支持传入 GIF 图像路径，为待接听状态的用户展示动画。 | 自定义 loading 动画 |
+
+### 步骤2：添加通话控制按钮
+
+您可以参考 [DeviceStore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/devicestore)、[CallStore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callstore) 提供的 API，自定义添加您的按钮。
+
+- **DeviceStore 功能说明：** 麦克风（开关/音量）、摄像头（开关/切换/画质）、屏幕共享，设备状态实时监听。建议将对应方法绑定至按钮点击事件，并通过监听设备状态变更来实时刷新按钮的 UI 状态。
+- **CallStore 功能说明：** 接听、挂断、拒接等核心通话控制能力。建议将对应方法绑定至按钮点击事件，并监听通话状态的变化，以确保按钮显示与当前通话阶段保持同步。
+
+**图标资源下载：** 按钮图标可以直接从 [GitHub](https://github.com/Tencent-RTC/TUIKit_iOS/tree/main/atomic_x/Resources/AtomicX.xcassets/icon/call) 下载。这些图标由我们的设计师专为 TUICallKit 打造，无版权风险，可放心使用。
+
+| 图标 | 下载地址 |
+|------|----------|
+| 拨号图标 | https://github.com/Tencent-RTC/TUIKit_iOS/tree/main/atomic_x/Resources/AtomicX.xcassets/icon/call/icon_dialing.imageset |
+| 挂断图标 | https://github.com/Tencent-RTC/TUIKit_iOS/tree/main/atomic_x/Resources/AtomicX.xcassets/icon/call/icon_hangup.imageset |
+| 摄像头关闭图标 | https://github.com/Tencent-RTC/TUIKit_iOS/tree/main/atomic_x/Resources/AtomicX.xcassets/icon/call/icon_camera_off.imageset |
+| 摄像头开启图标 | https://github.com/Tencent-RTC/TUIKit_iOS/tree/main/atomic_x/Resources/AtomicX.xcassets/icon/call/icon_camera_on.imageset |
+| 静音开启图标 | https://github.com/Tencent-RTC/TUIKit_iOS/tree/main/atomic_x/Resources/AtomicX.xcassets/icon/call/icon_mute_on.imageset |
+| 静音图标 | https://github.com/Tencent-RTC/TUIKit_iOS/tree/main/atomic_x/Resources/AtomicX.xcassets/icon/call/icon_mute.imageset |
+| 免提图标 | https://github.com/Tencent-RTC/TUIKit_iOS/tree/main/atomic_x/Resources/AtomicX.xcassets/icon/call/icon_handsfree.imageset |
+| 免提开启图标 | https://github.com/Tencent-RTC/TUIKit_iOS/tree/main/atomic_x/Resources/AtomicX.xcassets/icon/call/icon_handsfree_on.imageset |
+
+**以添加挂断、麦克风、摄像头按钮为例，实现方式如下：**
+
+#### 1.1 添加挂断按钮
+
+创建并添加挂断按钮，在点击事件中调用 hangup 接口并销毁界面。
+
+```swift
+import UIKit
+import AtomicXCore
+import Combine
+
+class CallViewController: UIViewController {
+    private lazy var buttonHangup: UIButton = {
+        let buttonWidth: CGFloat = 80
+        let buttonHeight: CGFloat = 80
+        let spacing: CGFloat = 30
+        let bottomMargin: CGFloat = 80
+        let totalWidth = buttonWidth * 3 + spacing * 2
+        let startX = (view.bounds.width - totalWidth) / 2
+        let buttonY = view.bounds.height - bottomMargin - buttonHeight
+
+        let button = createButton(
+            frame: CGRect(x: startX + (buttonWidth + spacing) * 2, y: buttonY, width: buttonWidth, height: buttonHeight),
+            title: "挂断"
+        )
+        button.backgroundColor = .systemRed
+        button.addTarget(self, action: #selector(touchHangupButton), for: .touchUpInside)
+        return button
+    }()
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        // 1.添加挂断按钮
+        view.addSubview(buttonHangup)
+    }
+
+    // 2.在点击事件中调用 hangup 接口并销毁页面
+    @objc private func touchHangupButton() {
+        CallStore.shared.hangup(completion: nil)
+    }
+
+    private func createButton(frame: CGRect, title: String) -> UIButton {
+        let button = UIButton(type: .system)
+        button.frame = frame
+        button.setTitle(title, for: .normal)
+        button.setTitleColor(.white, for: .normal)
+        button.backgroundColor = UIColor(white: 0.3, alpha: 0.8)
+        button.layer.cornerRadius = frame.width / 2
+        button.titleLabel?.font = UIFont.systemFont(ofSize: 14)
+        return button
+    }
+}
+```
+
+#### 1.2 添加麦克风开关按钮
+
+创建并添加麦克风开关按钮，并在点击事件中调用 openLocalMicrophone 或 closeLocalMicrophone 接口。
+
+```swift
+import UIKit
+import AtomicXCore
+import Combine
+
+class CallViewController: UIViewController {
+    private lazy var buttonMicrophone: UIButton = {
+        let buttonWidth: CGFloat = 80
+        let buttonHeight: CGFloat = 80
+        let spacing: CGFloat = 30
+        let bottomMargin: CGFloat = 80
+        let totalWidth = buttonWidth * 3 + spacing * 2
+        let startX = (view.bounds.width - totalWidth) / 2
+        let buttonY = view.bounds.height - bottomMargin - buttonHeight
+
+        let button = createButton(
+            frame: CGRect(x: startX + buttonWidth + spacing, y: buttonY, width: buttonWidth, height: buttonHeight),
+            title: "麦克风"
+        )
+        button.addTarget(self, action: #selector(touchMicrophoneButton), for: .touchUpInside)
+        return button
+    }()
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        // 1.添加麦克风开关按钮
+        view.addSubview(buttonMicrophone)
+    }
+
+    // 2.点击事件调用开启或关闭麦克风
+    @objc private func touchMicrophoneButton() {
+        let microphoneStatus = DeviceStore.shared.state.value.microphoneStatus
+        if microphoneStatus == .on {
+            DeviceStore.shared.closeLocalMicrophone()
+        } else {
+            DeviceStore.shared.openLocalMicrophone(completion: nil)
+        }
+    }
+}
+```
+
+#### 1.3 添加摄像头开关按钮
+
+创建并添加摄像头开关按钮，并在点击事件中调用 openLocalCamera 或 closeLocalCamera 接口。
+
+```swift
+import UIKit
+import AtomicXCore
+import Combine
+
+class CallViewController: UIViewController {
+    private lazy var buttonCamera: UIButton = {
+        let buttonWidth: CGFloat = 80
+        let buttonHeight: CGFloat = 80
+        let spacing: CGFloat = 30
+        let bottomMargin: CGFloat = 80
+        let totalWidth = buttonWidth * 3 + spacing * 2
+        let startX = (view.bounds.width - totalWidth) / 2
+        let buttonY = view.bounds.height - bottomMargin - buttonHeight
+
+        let button = createButton(
+            frame: CGRect(x: startX, y: buttonY, width: buttonWidth, height: buttonHeight),
+            title: "摄像头"
+        )
+        button.addTarget(self, action: #selector(touchCameraButton), for: .touchUpInside)
+        return button
+    }()
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        // 1.添加摄像头开关按钮
+        view.addSubview(buttonCamera)
+    }
+
+    // 2.摄像头按钮点击事件
+    @objc private func touchCameraButton() {
+        let cameraStatus = DeviceStore.shared.state.value.cameraStatus
+        if cameraStatus == .on {
+            DeviceStore.shared.closeLocalCamera()
+        } else {
+            let isFront = DeviceStore.shared.state.value.isFrontCamera
+            DeviceStore.shared.openLocalCamera(isFront: isFront, completion: nil)
+        }
+    }
+}
+```
+
+#### 1.4 实时更新媒体设备按钮文本
+
+监听麦克风和摄像头的状态，实时更新按钮文本。
+
+```swift
+import UIKit
+import AtomicXCore
+import Combine
+
+class CallViewController: UIViewController {
+    private var cancellables = Set<AnyCancellable>()
+    private var buttonCamera: UIButton?
+    private var buttonMicrophone: UIButton?
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        // 1.监听麦克风和摄像头的状态
+        observeDeviceState()
+    }
+
+    private func observeDeviceState() {
+        DeviceStore.shared.state.subscribe()
+            .map { $0.cameraStatus }
+            .removeDuplicates()
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] cameraStatus in
+                // 2.更新摄像头按钮文本
+                let title = cameraStatus == .on ? "关闭摄像头" : "开启摄像头"
+                self?.buttonCamera?.setTitle(title, for: .normal)
+            }
+            .store(in: &cancellables)
+
+        DeviceStore.shared.state.subscribe()
+            .map { $0.microphoneStatus }
+            .removeDuplicates()
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] microphoneStatus in
+                // 2.更新麦克风按钮文本
+                let title = microphoneStatus == .on ? "关闭麦克风" : "开启麦克风"
+                self?.buttonMicrophone?.setTitle(title, for: .normal)
+            }
+            .store(in: &cancellables)
+    }
+}
+```
+
+### 步骤3：申请麦克风/摄像头权限
+
+建议在发起通话前，先行检测音视频权限。若权限缺失，请引导用户动态申请。实现方法如下：
+
+**1. 声明权限：** 请在应用的 `Info.plist` 文件中添加以下两项，并填写对应的使用说明，这些说明将在系统请求权限时向用户显示：
+
+```xml
+<key>NSCameraUsageDescription</key>
+<string>需要访问您的摄像头，并可用于视频通话、群组视频通话等功能</string>
+<key>NSMicrophoneUsageDescription</key>
+<string>需要访问您的麦克风，并可用于音频通话、群组音频通话、视频通话、群组视频通话等功能</string>
+```
+
+**2. 动态申请权限：** 我们推荐您在发起通话时，根据通话媒体类型动态申请音视频权限。以下是权限处理的示例代码：
+
+```swift
+import AVFoundation
+import UIKit
+
+extension UIViewController {
+    func checkMicrophonePermission(completion: @escaping (Bool) -> Void) {
+        let status = AVCaptureDevice.authorizationStatus(for: .audio)
+        switch status {
+        case .authorized:
+            completion(true)
+        case .notDetermined:
+            AVCaptureDevice.requestAccess(for: .audio) { granted in
+                DispatchQueue.main.async { completion(granted) }
+            }
+        case .denied, .restricted:
+            completion(false)
+        @unknown default:
+            completion(false)
+        }
+    }
+
+    func checkCameraPermission(completion: @escaping (Bool) -> Void) {
+        let status = AVCaptureDevice.authorizationStatus(for: .video)
+        switch status {
+        case .authorized:
+            completion(true)
+        case .notDetermined:
+            AVCaptureDevice.requestAccess(for: .video) { granted in
+                DispatchQueue.main.async { completion(granted) }
+            }
+        case .denied, .restricted:
+            completion(false)
+        @unknown default:
+            completion(false)
+        }
+    }
+
+    func showPermissionAlert(message: String) {
+        let alert = UIAlertController(title: "权限请求", message: message, preferredStyle: .alert)
+        alert.addAction(UIAlertAction(title: "去设置", style: .default) { _ in
+            if let url = URL(string: UIApplication.openSettingsURLString) {
+                UIApplication.shared.open(url)
+            }
+        })
+        alert.addAction(UIAlertAction(title: "取消", style: .cancel))
+        present(alert, animated: true)
+    }
+}
+```
+
+### 步骤4：发起通话
+
+您可以在 calls 调用成功后跳转通话界面，我们建议您根据媒体类型自动开启麦克风或摄像头获得更好的通话体验，实现方式如下：
+
+1. **发起通话：** 调用 `calls` 发起通话。
+2. **开启媒体设备：** 发起通话成功后开启麦克风，如果是视频通话同时开启摄像头。
+3. **唤起通话页面：** 发起通话成功，唤起通话页面。
+
+```swift
+import UIKit
+import AtomicXCore
+import Combine
+
+class MainViewController: UIViewController {
+    // 1.发起通话
+    private func startCall(userIdList: [String], mediaType: CallMediaType) {
+        var params = CallParams()
+        params.timeout = 30
+
+        CallStore.shared.calls(
+            participantIds: userIdList,
+            mediaType: mediaType,
+            params: params
+        ) { [weak self] result in
+            switch result {
+            case .success:
+                // 2.开启媒体设备
+                self?.openDevices(for: mediaType)
+                // 3.唤起通话页面
+                DispatchQueue.main.async {
+                    let callVC = CallViewController()
+                    callVC.modalPresentationStyle = .fullScreen
+                    self?.present(callVC, animated: true)
+                }
+            case .failure(let error):
+                Log.error("发起通话失败: \(error)")
+            }
+        }
+    }
+
+    private func openDevices(for mediaType: CallMediaType) {
+        DeviceStore.shared.openLocalMicrophone(completion: nil)
+        if mediaType == .video {
+            let isFront = DeviceStore.shared.state.value.isFrontCamera
+            DeviceStore.shared.openLocalCamera(isFront: isFront, completion: nil)
+        }
+    }
+}
+```
+
+**calls 接口参数详细说明：**
+
+| 参数 | 类型 | 是否必填 | 说明 |
+|------|------|----------|------|
+| participantIds | [String] | 是 | 目标用户的 userId 列表 |
+| mediaType | CallMediaType | 是 | 通话媒体类型。`CallMediaType.video`：视频通话；`CallMediaType.audio`：语音通话 |
+| params | CallParams | 否 | 通话扩展参数：`roomId`(String)房间ID；`timeout`(Int)呼叫超时时间（秒）；`userData`(String)用户自定义数据；`chatGroupId`(String)Chat群组ID；`isEphemeralCall`(Bool)是否为加密通话 |
+
+### 步骤5：结束通话
+
+无论您调用 `hangup` 挂断还是对方主动结束通话，均会触发 `onCallEnded` 事件。建议监听该事件，当该事件被触发（即通话结束）时，执行关闭当前界面的操作。实现方式如下：
+
+1. **监听通话结束事件：** 监听 `onCallEnded` 事件。
+2. **销毁通话页面：** `onCallEnded` 触发后，销毁通话页面。
+
+```swift
+import UIKit
+import AtomicXCore
+import Combine
+
+class CallViewController: UIViewController {
+    private var cancellables = Set<AnyCancellable>()
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        // 1.添加通话事件监听
+        addListener()
+    }
+
+    private func addListener() {
+        CallStore.shared.callEventPublisher
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] event in
+                if case .onCallEnded = event {
+                    // 2.销毁通话页面
+                    self?.dismiss(animated: true)
+                }
+            }
+            .store(in: &cancellables)
+    }
+}
+```
+
+**onCallEnded 事件参数详细说明：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `callId` | String | 此次通话的唯一标识 |
+| `mediaType` | CallMediaType | 通话媒体类型。`CallMediaType.video`：视频通话；`CallMediaType.audio`：语音通话 |
+| `reason` | CallEndReason | 通话结束原因：`CallEndReason.unknown`未知；`CallEndReason.hangup`正常挂断；`CallEndReason.reject`拒绝接听；`CallEndReason.noResponse`无响应；`CallEndReason.offline`对方离线；`CallEndReason.lineBusy`对方忙线；`CallEndReason.canceled`通话取消；`CallEndReason.otherDeviceAccepted`其他设备已接听；`CallEndReason.otherDeviceReject`其他设备已拒绝；`CallEndReason.endByServer`服务器结束 |
+| `userId` | String | 触发结束的用户 ID |
+
+### 运行效果
+
+当您完成以上 5 步后，"拨打一通电话"运行效果如下：
+
+## 定制页面
+
+**CallCoreView** 提供了完善的 UI 定制能力，支持头像及音量提示等图标的自由替换。为助力快速集成，您可以直接从 [GitHub](https://github.com/Tencent-RTC/TUIKit_iOS/tree/main/atomic_x/Resources/AtomicX.xcassets/icon/call) 下载。无版权风险，可放心使用。
+
+### 自定义音量提示的图标
+
+您可以调用 **CallCoreView** 组件的 [setVolumeLevelIcons](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callcoreview/setvolumelevelicons(icons:)) 设置音量大小等级不同的提示图标。
+
+**setVolumeLevelIcons 示例代码：**
+
+```swift
+let volumeLevelIcons: [VolumeLevel: String] = [
+    .mute: "对应图标资源的路径"
+]
+callCoreView.setVolumeLevelIcons(icons: volumeLevelIcons)
+```
+
+**setVolumeLevelIcons 接口参数详细说明：**
+
+| 参数 | 类型 | 是否必填 | 说明 |
+|------|------|----------|------|
+| icons | [VolumeLevel: String] | 是 | 音量等级与图标资源的映射表。Key为VolumeLevel：`.mute`麦克风关闭/静音；`.low`音量(0-25]；`.medium`音量(25-50]；`.high`音量(50-75]；`.peak`音量(75-100]。Value为对应图标资源路径 |
+
+**音量提示图标：**
+
+| 文件名 | 说明 | 下载地址 |
+|--------|------|----------|
+| icon_volume | 【图标含义】音量提示图标。<br>【推荐用法】您可以将该图标等级设置为 `.low` 或 `.medium`，当用户音量大于对应等级时显示。 | https://github.com/Tencent-RTC/TUIKit_iOS/tree/main/atomic_x/Resources/AtomicX.xcassets/icon/call/icon_volume.imageset |
+| icon_mic_off | 【图标含义】静音图标。<br>【推荐用法】您可以将该图标等级设置为 `.mute`，当该用户静音时显示。 | https://github.com/Tencent-RTC/TUIKit_iOS/tree/main/atomic_x/Resources/AtomicX.xcassets/icon/call/icon_mic_off.imageset |
+
+### 自定义网络提示的图标
+
+您可以调用 **CallCoreView** 组件的 [setNetworkQualityIcons](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callcoreview/setnetworkqualityicons(icons:)) 设置不同网络状态的提示图标。
+
+**setNetworkQualityIcons 示例代码：**
+
+```swift
+let networkQualityIcons: [NetworkQuality: String] = [
+    .bad: "对应图标的路径"
+]
+callCoreView.setNetworkQualityIcons(icons: networkQualityIcons)
+```
+
+**setNetworkQualityIcons 接口参数详细说明：**
+
+| 参数 | 类型 | 是否必填 | 说明 |
+|------|------|----------|------|
+| icons | [NetworkQuality: String] | 是 | 网络质量与图标资源的映射表。Key为NetworkQuality：`.unknown`未知；`.excellent`极佳；`.good`较好；`.poor`较差；`.bad`差；`.veryBad`极差；`.down`网络断开。Value为对应图标资源路径 |
+
+**网络较差的提示图标：**
+
+| 文件名 | 说明 | 下载地址 |
+|--------|------|----------|
+| group_network_low_quality | 【图标含义】网络较差的提示图标。<br>【推荐用法】您可以将该图标等级设置为 `.bad`、`.veryBad` 或 `.down`，当网络较差时显示该图标。 | https://github.com/Tencent-RTC/TUIKit_iOS/tree/main/atomic_x/Resources/AtomicX.xcassets/icon/call/group_network_low_quality.imageset |
+
+### 自定义默认头像
+
+您可以调用 **CallCoreView** 的 [setParticipantAvatars](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callcoreview/setparticipantavatars(avatars:)) 接口设置用户头像。建议监听响应式数据 allParticipants。
+
+**setParticipantAvatars 示例代码：**
+
+```swift
+var avatars: [String: String] = [:]
+let userId = ""  // 用户 ID
+let avatarPath = ""  // 用户默认头像资源的路径
+avatars[userId] = avatarPath
+callCoreView.setParticipantAvatars(avatars: avatars)
+```
+
+**setParticipantAvatars 接口参数详细说明：**
+
+| 参数 | 类型 | 是否必填 | 说明 |
+|------|------|----------|------|
+| avatars | [String: String] | 是 | 用户头像映射表。Key：用户的 userID；Value：该用户的头像资源绝对路径 |
+
+**默认头像资源：**
+
+| 文件名 | 说明 | 下载地址 |
+|--------|------|----------|
+| default_participant_icon | 【图标含义】默认头像。<br>【推荐用法】当用户头像加载失败或无头像时，您可以给该用户设置此默认头像。 | https://github.com/Tencent-RTC/TUIKit_iOS/tree/main/atomic_x/Resources/AtomicX.xcassets/icon/call/default_participant_icon.imageset |
+
+### 自定义 loading 动画
+
+您可以调用 **CallCoreView** 的 [setWaitingAnimation](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callcoreview/setwaitinganimation(path:)) 接口，为等待中用户设置等待动画。
+
+**setWaitingAnimation 示例代码：**
+
+```swift
+let waitingAnimationPath = ""  // 等待动画 GIF 图像资源的路径
+callCoreView.setWaitingAnimation(path: waitingAnimationPath)
+```
+
+**setWaitingAnimation 接口参数详细说明：**
+
+| 参数 | 类型 | 是否必填 | 说明 |
+|------|------|----------|------|
+| path | String | 是 | GIF 格式图像资源的绝对路径 |
+
+**等待接听的动画：**
+
+| 文件名 | 说明 | 下载地址 |
+|--------|------|----------|
+| loading.gif | 【图标含义】用户等待接听动画。<br>【推荐用法】群组通话时设置的动画。设置后，当用户的状态为等待接听时，显示该动画。 | https://github.com/Tencent-RTC/TUIKit_iOS/blob/main/atomic_x/Resources/CallResource/loading.gif |
+
+### 添加通话计时提示
+
+通话计时通过响应式数据 [activeCall](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callstate) 的 `duration` 字段实时获得。
+
+1. **数据层订阅：** 订阅 `CallStore.shared.state`，建立当前活跃通话的响应式监听。
+2. **绑定通话计时数据：** 将 `activeCall.duration` 字段绑定至 UI 控件。该字段为响应式数据，会自动驱动 UI 实时刷新，无需手动维护定时器。
+
+```swift
+import UIKit
+import AtomicXCore
+import Combine
+
+class TimerView: UILabel {
+    private var cancellables = Set<AnyCancellable>()
+
+    override init(frame: CGRect) {
+        super.init(frame: frame)
+        setupView()
+    }
+
+    required init?(coder: NSCoder) {
+        super.init(coder: coder)
+        setupView()
+    }
+
+    private func setupView() {
+        textColor = .white
+        textAlignment = .center
+        font = .systemFont(ofSize: 16)
+    }
+
+    override func didMoveToWindow() {
+        super.didMoveToWindow()
+        if window != nil {
+            // 1.数据层订阅
+            registerActiveCallObserver()
+        } else {
+            cancellables.removeAll()
+        }
+    }
+
+    private func registerActiveCallObserver() {
+        CallStore.shared.state.subscribe()
+            .map { $0.activeCall }
+            .removeDuplicates { $0.duration == $1.duration }
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] activeCall in
+                // 2.绑定通话计时数据
+                self?.updateDurationView(activeCall: activeCall)
+            }
+            .store(in: &cancellables)
+    }
+
+    private func updateDurationView(activeCall: CallInfo) {
+        let currentDuration = Int(activeCall.duration)
+        let minutes = currentDuration / 60
+        let seconds = currentDuration % 60
+        text = String(format: "%02d:%02d", minutes, seconds)
+    }
+}
+```
+
+## 更多功能
+
+### 自定义用户头像/昵称
+
+通话开始前，您可以通过 `setSelfInfo` 方法，设置自己的昵称和头像。
+
+**setSelfInfo 示例代码：**
+
+```swift
+import AtomicXCore
+
+var userProfile = UserProfile()
+userProfile.userID = ""  // 您的 userID
+userProfile.avatarURL = ""  // 头像的 url
+userProfile.nickname = ""  // 需要设置的昵称
+
+LoginStore.shared.setSelfInfo(userProfile: userProfile) { result in
+    switch result {
+    case .success:
+        // 设置成功回调
+    case .failure(let error):
+        // 设置失败回调
+    }
+}
+```
+
+**setSelfInfo 接口参数详细说明：**
+
+| 参数 | 类型 | 是否必填 | 说明 |
+|------|------|----------|------|
+| `userProfile` | [UserProfile](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/userprofile) | 是 | 用户信息结构体：<br><br>- `userID`：用户的 ID。<br>- `avatarURL`：用户头像的 URL。<br>- `nickname`：用户的昵称。<br><br>更多字段详情可参考 [UserProfile](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/userprofile)。 |
+| `completion` | CompletionHandler | 否 | 【字段含义】操作完成回调，用于返回接通电话的结果。 |
+
+### 切换布局模式
+
+您可以通过 [setLayoutTemplate](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callcoreview/setlayouttemplate(_:)) 接口灵活切换布局模式。若未主动配置，**CallCoreView** 将根据通话人数自动适配：1v1 默认 `Float` 模式，多人通话自动切换为 `Grid` 模式。
+
+**三种布局模式对比：**
+
+| 模式 | 布局逻辑 | 交互特性 |
+|------|----------|----------|
+| **Float** | 呼叫等待时全屏显示己方画面；接通后全屏显示对方画面，己方画面以悬浮小窗展示。 | 支持小窗拖拽移动，点击小窗可实现大小画面互换。 |
+| **Grid** | 所有成员画面呈网格状平铺排列成宫格模式布局，适用 2 人以上通话。 | 支持点击特定成员画面放大查看。 |
+| **Pip** | 1v1 场景固定显示对方画面；多人场景采用 Active Speaker 策略，自动全屏展示正在说话的用户。 | 等待时显示自己的画面，接通后还会显示通话计时。 |
+
+**setLayoutTemplate 示例代码：**
+
+```swift
+let callCoreView = CallCoreView(frame: view.bounds)
+callCoreView.setLayoutTemplate(.grid)
+```
+
+**setLayoutTemplate 接口参数详细说明：**
+
+| 参数 | 类型 | 是否必填 | 说明 |
+|------|------|----------|------|
+| template | CallLayoutTemplate | 是 | 布局模式：`.float`（浮窗）、`.grid`（宫格）、`.pip`（画中画） |
+
+### 设置通话的默认超时时间
+
+在发起通话时，通过 `CallParams` 中的 `timeout` 字段指定等待超时时间。
+
+```swift
+var callParams = CallParams()
+callParams.timeout = 30  // 设置通话超时为30秒
+
+CallStore.shared.calls(
+    participantIds: userIdList,
+    mediaType: .video,
+    params: callParams,
+    completion: nil
+)
+```
+
+| 参数 | 类型 | 是否必填 | 说明 |
+|------|------|----------|------|
+| userIdList | [String] | 是 | 目标用户的 userId 列表 |
+| mediaType | CallMediaType | 是 | 通话媒体类型。`CallMediaType.video`：视频通话；`CallMediaType.audio`：语音通话 |
+| params | CallParams | 否 | 通话扩展参数：`roomId`(String)房间ID，可选参数，未指定时由服务端自动分配；`timeout`(Int)呼叫超时时间（秒）；`userData`(String)用户自定义数据；`chatGroupId`(String)Chat群组ID，用于群组通话场景；`isEphemeralCall`(Boolean)是否为加密通话（不产生通话记录） |
+
+### 实现应用内悬浮窗
+
+AtomicXCore SDK 提供了 CallPipView 组件，可以在应用内实现悬浮窗效果。当您的通话界面被其他页面覆盖时（例如用户点击了返回键但通话未结束），可以显示一个悬浮的小窗口，让用户随时查看通话状态并快速返回通话界面。
+
+**第一步：** 创建悬浮窗控制器。
+
+```swift
+import UIKit
+import AtomicXCore
+import Combine
+
+class FloatWindowViewController: UIViewController {
+    var tapGestureAction: (() -> Void)?
+    private var cancellables = Set<AnyCancellable>()
+
+    private lazy var callCoreView: CallCoreView = {
+        let view = CallCoreView(frame: self.view.bounds)
+        view.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+        view.setLayoutTemplate(.pip)
+        view.isUserInteractionEnabled = false
+        return view
+    }()
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        view.backgroundColor = UIColor(white: 0.1, alpha: 1.0)
+        view.layer.cornerRadius = 10
+        view.layer.masksToBounds = true
+
+        view.addSubview(callCoreView)
+
+        let tapGesture = UITapGestureRecognizer(target: self, action: #selector(handleTap))
+        view.addGestureRecognizer(tapGesture)
+
+        DispatchQueue.main.asyncAfter(deadline: .now() + 1.0) { [weak self] in
+            self?.observeCallStatus()
+        }
+    }
+
+    @objc private func handleTap() {
+        tapGestureAction?()
+    }
+
+    private func observeCallStatus() {
+        CallStore.shared.state
+            .subscribe(StatePublisherSelector<CallState, CallParticipantStatus>(keyPath: \.selfInfo.status))
+            .removeDuplicates()
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] status in
+                if status == .none {
+                    NotificationCenter.default.post(name: NSNotification.Name("HideFloatingWindow"), object: nil)
+                }
+            }
+            .store(in: &cancellables)
+    }
+
+    deinit {
+        cancellables.removeAll()
+    }
+}
+```
+
+**第二步：** 在主界面实现悬浮窗管理逻辑。
+
+```swift
+import UIKit
+import AtomicXCore
+
+class MainViewController: UIViewController {
+    private var floatWindow: UIWindow?
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+
+        NotificationCenter.default.addObserver(
+            self,
+            selector: #selector(showFloatingWindow),
+            name: NSNotification.Name("ShowFloatingWindow"),
+            object: nil
+        )
+
+        NotificationCenter.default.addObserver(
+            self,
+            selector: #selector(hideFloatingWindow),
+            name: NSNotification.Name("HideFloatingWindow"),
+            object: nil
+        )
+    }
+
+    @objc private func showFloatingWindow() {
+        let selfStatus = CallStore.shared.state.value.selfInfo.status
+        guard selfStatus == .accept else { return }
+        guard floatWindow == nil else { return }
+        guard let windowScene = UIApplication.shared.connectedScenes.first as? UIWindowScene else { return }
+
+        let pipWidth: CGFloat = 100
+        let pipHeight: CGFloat = pipWidth * 16 / 9
+        let pipX = UIScreen.main.bounds.width - pipWidth - 20
+        let pipY: CGFloat = 100
+
+        let window = UIWindow(windowScene: windowScene)
+        window.windowLevel = .alert + 1
+        window.backgroundColor = .clear
+        window.frame = CGRect(x: pipX, y: pipY, width: pipWidth, height: pipHeight)
+
+        let floatVC = FloatWindowViewController()
+        floatVC.tapGestureAction = { [weak self] in
+            self?.openCallViewController()
+        }
+
+        window.rootViewController = floatVC
+        self.floatWindow = window
+
+        window.isHidden = false
+        window.makeKeyAndVisible()
+
+        if let mainWindow = windowScene.windows.first(where: { $0 != window }) {
+            mainWindow.makeKey()
+        }
+    }
+
+    @objc private func hideFloatingWindow() {
+        floatWindow?.isHidden = true
+        floatWindow = nil
+    }
+
+    private func openCallViewController() {
+        hideFloatingWindow()
+        guard let topVC = getTopViewController() else { return }
+        let callVC = CallViewController()
+        callVC.modalPresentationStyle = .fullScreen
+        topVC.present(callVC, animated: true)
+    }
+
+    private func getTopViewController() -> UIViewController? {
+        guard let windowScene = UIApplication.shared.connectedScenes.first as? UIWindowScene,
+              let keyWindow = windowScene.windows.first(where: { $0.isKeyWindow }),
+              let rootVC = keyWindow.rootViewController else {
+            return nil
+        }
+        var topVC = rootVC
+        while let presentedVC = topVC.presentedViewController {
+            topVC = presentedVC
+        }
+        return topVC
+    }
+
+    deinit {
+        NotificationCenter.default.removeObserver(self)
+    }
+}
+```
+
+**第三步：** 在通话界面添加悬浮窗触发逻辑。
+
+```swift
+import UIKit
+import AtomicXCore
+
+class CallViewController: UIViewController {
+    override func viewWillAppear(_ animated: Bool) {
+        super.viewWillAppear(animated)
+        NotificationCenter.default.post(name: NSNotification.Name("HideFloatingWindow"), object: nil)
+    }
+
+    override func viewWillDisappear(_ animated: Bool) {
+        super.viewWillDisappear(animated)
+        let selfStatus = CallStore.shared.state.value.selfInfo.status
+        if selfStatus == .accept {
+            NotificationCenter.default.post(name: NSNotification.Name("ShowFloatingWindow"), object: nil)
+        }
+    }
+}
+```
+
+### 实现应用外画中画
+
+AtomicXCore SDK 支持通过底层 TRTC 引擎实现应用外画中画功能。当应用进入后台时，通话画面可以以系统画中画形式悬浮在其他应用之上，用户可以边使用其他应用边进行视频通话。实现方式如下：
+
+> **说明：**
+>
+> 1. 需要在 Xcode 的 `Signing & Capabilities` 中添加 `Background Modes` 能力，并勾选 `Audio, AirPlay, and Picture in Picture`。
+> 2. 需要 iOS 15.0 及以上版本支持。
+
+1. **配置画中画参数：** 您需要设置画中画窗口的填充模式、用户视频区域、画布参数等参数。
+
+```swift
+import Foundation
+import AtomicXCore
+
+enum PictureInPictureFillMode: Int, Codable {
+    case fill = 0  // 填充模式
+    case fit = 1   // 适应模式
+}
+
+// 用户视频区域
+struct PictureInPictureRegion: Codable {
+    let userId: String           // 用户 ID
+    let width: Double            // 宽度（0.0-1.0，相对于画布）
+    let height: Double           // 高度（0.0-1.0，相对于画布）
+    let x: Double                // X 坐标（0.0-1.0，相对于画布左上角）
+    let y: Double                // Y 坐标（0.0-1.0，相对于画布左上角）
+    let fillMode: PictureInPictureFillMode  // 填充模式
+    let streamType: String       // 流类型（"high" 或 "low"）
+    let backgroundColor: String  // 背景颜色
+}
+
+// 画布配置
+struct PictureInPictureCanvas: Codable {
+    let width: Int              // 画布宽度
+    let height: Int             // 画布高度
+    let backgroundColor: String // 背景颜色
+}
+
+// 画中画参数
+struct PictureInPictureParams: Codable {
+    let enable: Bool                        // 是否启用画中画
+    let cameraBackgroundCapture: Bool?      // 是否在后台采集摄像头
+    let canvas: PictureInPictureCanvas?      // 画布配置（可选）
+    let regions: [PictureInPictureRegion]?   // 用户视频区域列表（可选）
+}
+
+// 画中画请求
+struct PictureInPictureRequest: Codable {
+    let api: String                    // API 名称
+    let params: PictureInPictureParams // 参数
+}
+```
+
+**2. 启用画中画：** 您可以通过 `configPictureInPicture` 方法启用/关闭画中画功能。
+
+```swift
+let params = PictureInPictureParams(
+    enable: true,
+    cameraBackgroundCapture: true,
+    canvas: nil,
+    regions: nil
+)
+
+let request = PictureInPictureRequest(
+    api: "configPictureInPicture",
+    params: params
+)
+
+// 编码为 JSON 字符串
+let encoder = JSONEncoder()
+if let data = try? encoder.encode(request),
+   let jsonString = String(data: data, encoding: .utf8) {
+    TUICallEngine.createInstance().callExperimentalAPI(jsonObject: jsonString)
+}
+```
+
+### 设置通话过程中屏幕常亮
+
+通话过程中保持屏幕常亮是通话应用的基本需求。iOS 提供了 `UIApplication.shared.isIdleTimerDisabled` 属性来实现此功能。
+
+```swift
+class CallViewController: UIViewController {
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        // 禁用自动锁屏，保持屏幕常亮
+        UIApplication.shared.isIdleTimerDisabled = true
+    }
+
+    override func viewWillDisappear(_ animated: Bool) {
+        super.viewWillDisappear(animated)
+        // 恢复自动锁屏
+        UIApplication.shared.isIdleTimerDisabled = false
+    }
+}
+```
+
+### 播放等待接听的提示音
+
+您可以监听自己的通话状态，在等待接听时播放铃声，在接听通话或通话结束时停止播放铃声。
+
+```swift
+import Combine
+
+private var cancellables = Set<AnyCancellable>()
+
+private func observeSelfCallStatus() {
+    CallStore.shared.state.subscribe()
+        .map { $0.selfInfo.status }
+        .removeDuplicates()
+        .receive(on: DispatchQueue.main)
+        .sink { [weak self] status in
+            if status == .accept || status == .none {
+                // 停止播放铃声
+                return
+            }
+            if status == .waiting {
+                // 播放铃声
+            }
+        }
+        .store(in: &cancellables)
+}
+```
+
+### 开启后台采集音频/视频
+
+为了确保应用在进入后台时仍能正常采集音频和视频（例如用户锁屏或切换到其他应用），您需要配置 iOS 的后台模式权限并设置音频会话。
+
+**配置步骤：** 在 Xcode 中打开您的项目，按照以下步骤操作：
+
+1. 选择项目的 `Target` → `Signing & Capabilities`。
+2. 点击 `+ Capability`。
+3. 搜索并添加 `Background Modes`。
+4. 勾选以下三个选项：
+   - `Audio, AirPlay, and Picture in Picture`（保持音频采集和画中画功能）。
+   - `Voice over IP`（支持 VoIP 通话）。
+   - `Remote notifications`（可选，用于接收离线推送）。
+
+配置完成后，您的 `Info.plist` 会自动添加以下内容：
+
+```xml
+<key>UIBackgroundModes</key>
+<array>
+    <string>audio</string>
+    <string>voip</string>
+    <string>remote-notification</string>
+</array>
+```
+
+**配置音频会话（AVAudioSession）：**
+
+为了确保通话音频在后台正常工作，您需要在通话开始前配置音频会话。建议在通话界面的 `viewDidLoad` 或发起通话前设置：
+
+```swift
+import AVFoundation
+
+private func setupAudioSession() {
+    let audioSession = AVAudioSession.sharedInstance()
+    do {
+        try audioSession.setCategory(.playAndRecord, options: [.allowBluetooth, .allowBluetoothA2DP])
+        try audioSession.setActive(true)
+    } catch {
+        // 音频会话配置失败
+    }
+}
+```
+
+**播放铃声时的特殊处理（可选）：**
+
+如果您需要在等待接听时播放铃声，并且希望铃声通过扬声器播放，可以临时切换音频会话为 `.playback` 模式：
+
+```swift
+private func setAudioSessionForRingtone() {
+    let audioSession = AVAudioSession.sharedInstance()
+    do {
+        try audioSession.setCategory(.playback, options: [.allowBluetooth, .allowBluetoothA2DP])
+        try audioSession.overrideOutputAudioPort(.speaker)
+        try audioSession.setActive(true)
+    } catch {
+        // 铃声音频会话配置失败
+    }
+}
+
+private func restoreAudioSessionForCall() {
+    let audioSession = AVAudioSession.sharedInstance()
+    do {
+        try audioSession.setCategory(.playAndRecord, options: [.allowBluetooth, .allowBluetoothA2DP])
+        try audioSession.setActive(true)
+    } catch {
+        // 恢复音频会话失败
+    }
+}
+```
+
+### 设置离线推送参数
+
+## 常见问题
+
+### 在通话邀请超时时间内，被邀请者如果离线再上线，能否收到来电事件？
+
+单人通话时，如果在超时时间内上线，会触发来电邀请；群组通话，如果在超时时间内上线，会拉起未处理的 20 条群消息，如果存在通话邀请，则触发来电邀请事件。