@tencentcloud/sdk-mcp 1.4.7 → 1.6.0-beta.1

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

@@ -0,0 +1,1292 @@
+本文档将帮助您使用 **AtomicXCore SDK** 的 **DeviceStore**、**CallStore** 以及核心组件 **CallCoreView**，快速完成拨打电话功能。
+
+> 推荐使用更高效的 AI 集成助手
+>
+
+> 我们为您提供了全新的 AI 集成方式，只需要描述您的需求，即可自动生成集成代码，大幅提升开发效率。
+>
+
+> 点击这里，立即体验 AI 集成
+>
+
+## 核心功能
+
+**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**：`CallStore.shared` 初始化通话数据层。
+
+2. **用户登录：**调用 `LoginStore.shared.login()` 完成用户登录。
+
+3. **初始化通话引擎：**登录成功后调用 `TUICallEngine.createInstance().`init`()` 初始化通话信令引擎。
+
+   流程图与示例代码如下：
+
+【iOS】
+``` 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 = "**************"           // 请替换为在控制台得到的 SecretKey
+
+        // 生成 UserSig（仅用于本地快速测试，正式环境请在服务端生成）
+        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)")
+            }
+        }
+
+    }
+}
+```
+
+| <strong>参数</strong> | <strong>类型</strong> | <strong>说明</strong> |
+| --- | --- | --- |
+| userID | String | 当前用户的唯一 ID，仅包含英文字母、数字、连字符和下划线。为避免多端登录冲突，请勿使用 1、123 等简单 ID。 |
+| sdkAppID | int | 从 <a href="https://console.cloud.tencent.com/trtc">控制台</a> 获取，通常是以 140 或 160 开头的 10 位整数。 |
+| secretKey | String | 在 <a href="https://console.cloud.tencent.com/trtc">控制台</a> 创建的音视频应用的 SDKSecretKey。 |
+| userSig | String | 用于腾讯云鉴权的票据。请注意：<br>- 开发环境：您可以采用本地 <a href="https://github.com/Tencent-RTC/TUIKit_iOS/blob/main/call/TUICallKit_Swift/Debug/GenerateTestUserSig.swift">GenerateTestUserSig.genTestUserSig</a> 函数生成 userSig 或者通过 <a href="https://console.cloud.tencent.com/im/tool-usersig">UserSig 辅助工具</a> 生成临时的 UserSig。<br>- 生产环境：为了防止密钥泄露，请务必采用服务端生成 UserSig 的方式。详细信息请参考 <a href="https://cloud.tencent.com/document/product/647/17275">服务端生成 UserSig</a>。<br>更多信息请参见 <a href="https://cloud.tencent.com/document/product/647/17275">如何计算及使用 UserSig</a>。 |
+
+## 实现步骤
+
+**发起通话前，请确保完成登录**，这是服务可用的必要前提。以下将分 5 步为您讲解如何"拨打一通电话"。
+
+### 步骤1：创建通话界面
+
+您需要创建一个通话页面，当发起通话时唤起通话页面，实现方式如下：
+1. **创建通话页面**：您可以新建一个 UIViewController 作为通话宿主页面，用于响应来电时的跳转逻辑。
+
+2. **通话页面绑定 **[**CallCoreView**](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callcoreview/): 通话视图核心组件，自动监听 **CallStore** 数据并完成画面渲染，同时提供布局切换、头像与图标配置等 UI 定制化能力。
+
+【iOS】
+``` swift
+import UIKit
+import AtomicXCore
+
+class CallViewController: UIViewController {
+    // 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 图像路径，为待接听状态的用户展示动画。|步骤2：添加通话控制按钮|
+
+### 步骤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](http://github.com/Tencent-RTC/TUIKit_iOS/tree/main/call/TUICallKit_Swift/Resources/Assets.xcassets) 下载。这些图标由我们的设计师专为 TUICallKit 打造，无版权风险，可放心使用。
+
+| <strong>图标：</strong> |  |  |  |  |  |  |  |  |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+
+- **以添加挂断、麦克风、摄像头按钮为例，实现方式如下：**
+
+  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)
+          }
+
+          @objc private func touchHangupButton() {
+              // 2.在点击事件中调用 hangup 接口并销毁页面
+              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
+          }
+      }
+      ```
+  2. **添加麦克风开关按钮：**创建并添加麦克风开关按钮，并在点击事件中调用 [openLocalMicrophone](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/devicestore/openlocalmicrophone(completion:)) 或 [closeLocalMicrophone](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/devicestore/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)
+              }
+          }
+
+          // 创建圆形按钮辅助方法
+          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
+          }
+      }
+      ```
+  3. **添加摄像头开关按钮：**在底部工具栏容器中添加摄像头开关按钮，并在点击事件中调用 [openLocalCamera](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/devicestore/openlocalcamera(isfront:completion:)) 或 [closeLocalCamera](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/devicestore/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)
+              }
+          }
+
+          // 创建圆形按钮辅助方法
+          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
+          }
+      }
+      ```
+  4. **实时更新媒体设备按钮文本：**监听麦克风和摄像头的状态，实时更新按钮文本。
+
+      ``` swift
+      import UIKit
+      import AtomicXCore
+      import Combine
+
+      class CallViewController: UIViewController {
+          private var cancellables = Set<AnyCancellable>()
+
+          override func viewDidLoad() {
+              super.viewDidLoad()
+              // 其他初始化代码
+              // 1.监听麦克风和摄像头的状态
+              observeDeviceState()
+          }
+
+          private func observeDeviceState() {
+              DeviceStore.shared.state.subscribe()
+                  .map { $0.cameraStatus }
+                  .removeDuplicates()
+                  .receive(on: DispatchQueue.main)
+                  .sink {
+                      // 2.更新摄像头按钮文本
+                      [weak self] cameraStatus in
+                      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 {
+                      // 2.更新麦克风按钮文本
+                      [weak self] microphoneStatus in
+                      let title = microphoneStatus == .on ? "关闭麦克风" : "开启麦克风"
+                      self?.buttonMicrophone?.setTitle(title, for: .normal)
+                  }
+                  .store(in: &cancellables)
+          }
+      }
+      ```
+
+### 步骤3：申请麦克风/摄像头权限
+
+建议在发起通话前，先行检测音视频权限。若权限缺失，请引导用户动态申请。实现方法如下：
+1. **声明权限：**请在应用的 `Info.plist` 文件中添加以下两项，并填写对应的使用说明，这些说明将在系统请求权限时向用户显示：
+
+   ``` swift
+   <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](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callstore/calls(participantids:callmediatype:params:completion:)) 调用成功后跳转通话界面，我们建议您根据媒体类型自动开启麦克风或摄像头获得更好的通话体验，实现方式如下：
+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  // 设置通话超时时间为30秒
+
+           CallStore.shared.calls(
+               participantIds: userIdList,
+               mediaType: mediaType,      // 通话类型：.audio(音频) 或 .video(视频)
+               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 接口参数详细说明：**
+
+| <strong>参数</strong> | <strong>类型</strong> | <strong>是否必填</strong> | <strong>说明</strong> |
+| --- | --- | --- | --- |
+| participantIds | List<String> | 是 | 目标用户的 <code>userId</code> 列表。 |
+| mediaType | <a href="https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callmediatype">CallMediaType</a> | 是 | 通话媒体类型，用于指定发起音频通话还是视频通话。<br>- <code>CallMediaType.video</code> : 视频通话。<br>- <code>CallMediaType.audio</code> : 语音通话。 |
+| params | <a href="https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callparams">CallParams</a> | 否 | 通话扩展参数，如：房间号、通话邀请超时时间等。<br>- <code>roomId</code> (String) : 房间 ID，可选参数，未指定时由服务端自动分配。<br>- <code>timeout</code> (Int) : 呼叫超时时间（秒）。<br>- <code>userData</code> (String) : 用户自定义数据。<br>- <code>chatGroupId</code> (String) : Chat 群组 ID，用于群组通话场景。<br>- <code>isEphemeralCall</code> (Boolean) : 是否为加密通话（不产生通话记录）。 |
+
+### 步骤5：结束通话
+
+无论您调用 [hangup](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callstore/hangup(completion:)) 挂断还是对方主动结束通话，均会触发 [onCallEnded](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callevent/oncallended(callid:mediatype:reason:userid:)) 事件。 建议监听该事件，当该事件被触发（即通话结束）时，执行关闭当前界面的操作。实现方式如下：
+1. **监听通话结束事件**：监听 `onCallEnded` 事件。
+
+2. **销毁通话页面**：`onCallEnded` 触发后，销毁通话页面。
+
+   ``` swift
+   import UIKit
+   import AtomicXCore
+   import Combine
+
+   class CallViewController: UIViewController {
+       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 事件参数详细说明**：
+
+| <strong>参数</strong> | <strong>类型</strong> | <strong>说明</strong> |
+| --- | --- | --- |
+| callId | String | 此次通话的唯一标识。 |
+| mediaType | <a href="https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callmediatype">CallMediaType</a> | 通话媒体类型，用于指定发起音频通话还是视频通话。<br>- <code>CallMediaType.video</code> : 视频通话。<br>- <code>CallMediaType.audio</code> : 语音通话。 |
+| reason | <a href="https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callendreason">CallEndReason</a> | 通话结束的原因。<br>- <code>unknown</code> : 未知原因，无法确定结束原因。<br>- <code>hangup</code> : 正常挂断，用户主动挂断通话。<br>- <code>reject</code> : 拒绝接听，被叫方拒绝来电。<br>- <code>noResponse</code> : 无响应，被叫方未在超时时间内接听。<br>- <code>offline</code> : 对方离线，被叫方不在线。<br>- <code>lineBusy</code> : 对方忙线，被叫方正在通话中。<br>- <code>canceled</code> : 通话取消，主叫方在对方接听前取消。<br>- <code>otherDeviceAccepted</code> : 其他设备已接听，通话已在另一登录设备上接听。<br>- <code>otherDeviceReject</code> : 其他设备已拒绝，通话已在另一登录设备上拒绝。<br>- <code>endByServer</code> : 服务器结束，通话被服务器终止。 |
+| userId | String | 触发结束的用户 ID。 |
+
+### 运行效果
+
+当您完成以上 5 步后，"拨打一通电话"运行效果如下：
+
+## 定制页面
+
+**CallCoreView** 提供了完善的 UI 定制能力，支持头像及音量提示等图标的自由替换。**为助力快速集成，您可以直接从 **[**GitHub**](http://github.com/Tencent-RTC/TUIKit_iOS/tree/main/call/TUICallKit_Swift/Resources/Assets.xcassets)**下载。这些图标由我们的设计师专为 TUICallKit 打造，无版权风险，可放心使用。**
+
+### 自定义音量提示的图标
+
+您可以调用 **CallCoreView** 组件的 [setVolumeLevelIcons](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callcoreview/setvolumelevelicons(icons:)) 设置音量大小等级不同的提示图标。
+
+- **setVolumeLevelIcons****示例代码：**
+
+【iOS】
+``` swift
+// 设置音量提示图标
+let volumeLevelIcons: [VolumeLevel: String] = [
+    .mute: "对应图标资源的路径"
+]
+callCoreView.setVolumeLevelIcons(icons: volumeLevelIcons)
+```
+
+- **setVolumeLevelIcons 接口参数详细说明：**
+
+| <strong>参数</strong> | <strong>类型</strong> | <strong>是否必填</strong> | <strong>说明</strong> |
+| --- | --- | --- | --- |
+| icons | [VolumeLevel: String] | 是 | 音量等级与图标资源的映射表。字典结构说明如下：<br>key ( VolumeLevel ) 表示音量等级：<br>- <code>VolumeLevel.mute</code> ：表示麦克风关闭，静音状态。<br>- <code>VolumeLevel.low</code> ：表示音量范围 (0-25]。<br>- <code>VolumeLevel.medium</code> : 表示音量范围 (25-50]。<br>- <code>VolumeLevel.high</code> : 表示音量范围 (50-75]。<br>- <code>VolumeLevel.peak</code> : 表示音量范围 (75-100]。<br>Value ( String ) 表示对应音量等级的图标资源路径。 |
+
+- **音量提示图标：**
+
+| <strong>图标</strong> | <strong>说明</strong> |
+| --- | --- |
+|  | 【图标含义】音量提示图标。<br>【推荐用法】您可以将该图标等级设置为 <code>VolumeLevel.low</code> 或 <code>VolumeLevel.medium</code> ，当用户音量大于对应等级时显示。 |
+|  | 【图标含义】静音图标。<br>【推荐用法】您可以将该图标等级设置为 <code>VolumeLevel.mute</code> ，当该用户静音时显示。 |
+
+### 自定义网络提示的图标
+
+您可以调用 **CallCoreView** 组件的 [setNetworkQualityIcons](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callcoreview/setnetworkqualityicons(icons:)) 设置不同网络状态的提示图标。
+
+- **setNetworkQualityIcons 示例代码：**
+
+【iOS】
+``` swift
+// 设置网络质量图标
+let networkQualityIcons: [NetworkQuality: String] = [
+    .bad: "对应图标的路径"
+]
+callCoreView.setNetworkQualityIcons(icons: networkQualityIcons)
+```
+
+- **setNetworkQualityIcons****接口参数详细说明：**
+
+| <strong>参数</strong> | <strong>类型</strong> | <strong>是否必填</strong> | <strong>说明</strong> |
+| --- | --- | --- | --- |
+| icons | [NetworkQuality: String] | 是 | 网络质量与图标资源的映射表。字典结构说明如下：<br>Key ( NetworkQuality ) : 表示网络质量等级。<br><code>NetworkQuality.unknown</code> ：未知网络状态。<br><code>NetworkQuality.excellent</code>：网络状态极佳。<br><code>NetworkQuality.good</code> : 网络状态较好。<br><code>NetworkQuality.poor</code> : 网络状态较差。<br><code>NetworkQuality.bad</code> : 网络状态差。<br><code>NetworkQuality.veryBad</code> ：网络状态极差。<br><code>NetworkQuality.down</code> ：网络断开。<br>Value ( String ) : 对应网络状态的图标资源路径。 |
+
+- **网络较差的提示图标：**
+
+| <strong>图标</strong> | <strong>说明</strong> |
+| --- | --- |
+|  | 【图标含义】网络较差的提示图标。<br>【推荐用法】您可以将该图标等级设置为 <code>NetworkQuality.bad</code>、<code>NetworkQuality.veryBad</code> 或 <code>NetworkQuality.down</code> ，当网络较差时显示该图标。 |
+
+### 自定义默认头像
+
+您可以调用 **CallCoreView** 的 [setParticipantAvatars](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callcoreview/setparticipantavatars(avatars:)) 接口设置用户头像。建议您监听响应式数据 [allParticipants](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callstate/allparticipants)（所有参与通话的成员）：当获取到用户头像时设置并展示；若用户未设置头像或加载失败，则显示默认头像（占位图）。
+- **setParticipantAvatars****示例代码：**
+
+【iOS】
+``` swift
+// 设置用户头像
+var avatars: [String: String] = [:]
+let userId = ""      // 用户 ID
+let avatarPath = ""  // 用户默认头像资源的路径
+avatars[userId] = avatarPath
+
+callCoreView.setParticipantAvatars(avatars: avatars)
+```
+
+- **setParticipantAvatars****接口参数详细说明：**
+
+| <strong>参数</strong> | <strong>类型</strong> | <strong>是否必填</strong> | <strong>说明</strong> |
+| --- | --- | --- | --- |
+| avatars | [String: String] | 是 | 用户头像映射表。字典结构说明如下：<br>- Key : 用户的 userID。<br>- Value : 该用户的头像资源绝对路径。 |
+
+- **默认头像资源：**
+
+| <strong>图标</strong> | <strong>说明</strong> |
+| --- | --- |
+|  | 【图标含义】默认头像。<br>【推荐用法】当用户头像加载失败或无头像时，您可以给该用户设置此默认头像。 |
+
+### 自定义 loading 动画
+
+您可以调用 **CallCoreView** 的 [setWaitingAnimation](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callcoreview/setwaitinganimation(path:)) 接口，为等待中用户设置等待动画获得更好的体验。
+
+- **setWaitingAnimation 示例代码：**
+
+【iOS】
+``` swift
+// 设置等待动画
+let waitingAnimationPath = ""  // 等待动画 GIF 图像资源的路径
+callCoreView.setWaitingAnimation(path: waitingAnimationPath)
+```
+
+- **setWaitingAnimation 接口参数详细说明：**
+
+   |**参数**|**类型**|**是否必填**|**说明**|
+   |---------|---------|---------|---------|
+   |path|String|是|GIF 格式图像资源的绝对路径。|
+
+- **等待接听的动画：**
+
+| <strong>图标</strong> | <strong>说明</strong> |
+| --- | --- |
+|  | 【图标含义】用户等待接听动画<br>【推荐用法】群组通话时设置的动画。设置后，当用户的状态为等待接听时，显示该动画。 |
+
+### 添加通话计时提示
+
+通话计时可通过响应式数据 [activeCall](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callstate/activecall) 的 `duration` 字段实时获得，实时显示通话计时的实现方式如下：
+1. **数据层订阅：**订阅 `CallStore.observerState.activeCall` , 建立当前活跃通话的响应式监听。
+
+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
+                   // 更新通话计时
+                   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)
+       }
+   }
+   ```
+
+   > **说明：**
+   >
+
+   > 若您想了解更多通话状态响应式数据，详细可参考：[CallState](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callstate)。
+   >
+
+## 更多功能
+
+### 自定义用户头像/昵称
+
+通话开始前，您可以通过 [setSelfInfo](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/loginstore/setselfinfo(userprofile:completion:)) 方法，设置自己的昵称和头像。
+- **setSelfInfo 示例代码**：
+
+   ``` swift
+   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 接口参数详细说明：**
+
+| <strong>参数</strong> | <strong>类型</strong> | <strong>是否必填</strong> | <strong>说明</strong> |
+| --- | --- | --- | --- |
+| userProfile | <a href="https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/userprofile">UserProfile</a> | 是 | 用户信息结构体：<br>- <code>userID</code> ：用户的 ID<br>- <code>avatarURL</code> : 用户头像的 URL<br>- <code>nickname</code> ：用户的昵称<br>更多字段详情可参考 <a href="https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/userprofile">UserProfile</a>。 |
+
+### 切换布局模式
+
+**CallCoreView** 内置三种布局模式，您可以调用 [setLayoutTemplate](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callcoreview/setlayouttemplate(_:)) 设置布局模式。若未主动配置，**CallCoreView** 将根据通话人数自动适配：1v1 场景下默认采用 `Float` 模式，多人通话场景下则自动切换为 `Grid` 模式。不同布局模式的说明如下：
+| <strong>Float 模式</strong> | <strong>Grid 模式</strong> | <strong>PIP 模式</strong> |
+| --- | --- | --- |
+|  |  |  |
+| - <strong>布局逻辑：</strong>呼叫等待时全屏显示己方画面；接通后全屏显示对方画面，己方画面以悬浮小窗展示。<br>- <strong>交互特性：</strong>支持小窗拖拽移动，点击小窗可实现大小画面互换。 | - <strong>布局逻辑：</strong>所有成员画面呈网格状平铺排列成宫格模式布局，适用 2 人以上通话，支持点击放大画面功能。<br>- <strong>交互特性：</strong>支持点击特定成员画面放大查看。 | - <strong>布局逻辑：</strong>1 v 1 场景固定显示对方画面，多人场景：采用当前发言者（Active Speaker） 策略，自动识别并全屏展示正在说话的用户。<br>- <strong>交互特性：</strong>等待时显示自己的画面，接通后还会显示通话计时。 |
+
+- **setLayoutTemplate 示例代码：**
+
+   ``` swift
+   func setLayoutTemplate(_ template: CallLayoutTemplate)
+   ```
+- **setLayoutTemplate 接口参数详细说明：**
+
+| <strong>参数</strong> | <strong>类型</strong> | <strong>说明</strong> |
+| --- | --- | --- |
+| template | <a href="https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/calllayouttemplate">CallLayoutTemplate</a> | CallCoreView 的布局模式<br>- <code>CallLayoutTemplate.float</code> ：<br>- 布局逻辑：呼叫等待时全屏显示己方画面；接通后全屏显示对方画面，己方画面以悬浮小窗展示。<br>- 交互特性：支持小窗拖拽移动，点击小窗可实现大小画面互换。<br>- <code>CallLayoutTemplate.grid</code> ：<br>- 布局逻辑：所有成员画面呈网格状平铺排列成宫格模式布局，适用 2 人以上通话，支持点击放大画面功能。<br>- 交互特性：支持点击特定成员画面放大查看。<br>- <code>CallLayoutTemplate.pip</code> :<br>- 布局逻辑：1v1 场景固定显示对方画面，多人场景：采用当前发言者（Active Speaker） 策略，自动识别并全屏展示正在说话的用户。<br>- 交互特性：等待时显示自己的画面，接通后还会显示通话计时。 |
+
+### 设置通话的默认超时时间
+
+您可以在发起通话 [calls](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callstore/calls(participantids:callmediatype:params:completion:)) 时，通过配置参数 [CallParams](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callparams) 中的 `timeout` 字段来指定等待超时时间。示例代码如下：
+``` swift
+var callParams = CallParams()
+callParams.timeout = 30  // 设置通话超时为30秒
+CallStore.shared.calls(
+    participantIds: userIdList,
+    mediaType: .video,
+    params: callParams,
+    completion: nil
+)
+```
+| <strong>参数</strong> | <strong>类型</strong> | <strong>是否必填</strong> | <strong>说明</strong> |
+| --- | --- | --- | --- |
+| userIdList | List<String> | 是 | 目标用户的 userId 列表。 |
+| mediaType | <a href="https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callmediatype">CallMediaType</a> | 是 | 通话媒体类型，用于指定发起音频通话还是视频通话。<br>- <code>CallMediaType.video</code> : 视频通话。<br>- <code>CallMediaType.audio</code> : 语音通话。 |
+| params | <a href="https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callparams">CallParams</a> | 否 | 通话扩展参数，如：房间号、通话邀请超时时间等。<br>- <code>roomId</code> (String) : 房间 ID，可选参数，未指定时由服务端自动分配。<br>- <code>timeout</code> (Int) : 呼叫超时时间（秒）。<br>- <code>userData</code> (String) : 用户自定义数据。<br>- <code>chatGroupId</code> (String) : Chat 群组 ID，用于群组通话场景。<br>- <code>isEphemeralCall</code> (Boolean) : 是否为加密通话（不产生通话记录）。 |
+
+### 实现应用内悬浮窗
+
+AtomicXCore SDK 提供了 `CallPipView` 组件，可以在应用内实现悬浮窗效果。当您的通话界面被其他页面覆盖时（例如用户点击了返回键但通话未结束），可以显示一个悬浮的小窗口，让用户随时查看通话状态并快速返回通话界面。
+
+**第一步：**创建悬浮窗控制器。
+``` swift
+import UIKit
+import AtomicXCore
+import Combine
+
+/**
+ * 悬浮窗控制器
+ *
+ * 用于显示通话悬浮窗，内部包含 CallCoreView
+ */
+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)  // 设置为 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 }
+
+        // ⚠️ 关键：必须使用当前的 windowScene 来创建 window
+        guard let windowScene = UIApplication.shared.connectedScenes.first as? UIWindowScene else {
+            return
+        }
+
+        // 创建悬浮窗（宽高比 9:16）
+        let pipWidth: CGFloat = 100
+        let pipHeight: CGFloat = pipWidth * 16 / 9
+        let pipX = UIScreen.main.bounds.width - pipWidth - 20
+        let pipY: CGFloat = 100
+
+        // 创建悬浮窗 Window（关联到 windowScene）
+        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()
+
+        // 立即将主窗口恢复为 key window
+        if let mainWindow = windowScene.windows.first(where: { $0 != window }) {
+            mainWindow.makeKey()
+        }
+    }
+
+    /**
+     * 隐藏应用内悬浮窗
+     */
+    @objc private func hideFloatingWindow() {
+        floatWindow?.isHidden = true
+        floatWindow = nil
+    }
+
+    /**
+     * 打开通话界面（从悬浮窗点击进入）
+     */
+    private func openCallViewController() {
+        // 先隐藏悬浮窗
+        hideFloatingWindow()
+
+        // 获取当前最顶层的 ViewController
+        guard let topVC = getTopViewController() else {
+            return
+        }
+
+        let callVC = CallViewController()
+        callVC.modalPresentationStyle = .fullScreen
+        topVC.present(callVC, animated: true)
+    }
+
+    /**
+     * 获取当前最顶层的 ViewController
+     */
+    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
+
+   /**
+    * 设置音频会话，支持后台音频采集
+    *
+    * 建议在以下场景调用：
+    * 1. 通话界面的 viewDidLoad 中
+    * 2. 发起通话 (calls) 之前
+    * 3. 接听通话 (accept) 之前
+    */
+   private func setupAudioSession() {
+       let audioSession = AVAudioSession.sharedInstance()
+       do {
+           // 设置音频会话类别为播放和录音
+           // .allowBluetooth: 支持蓝牙耳机
+           // .allowBluetoothA2DP: 支持高质量蓝牙音频（A2DP 协议）
+           try audioSession.setCategory(.playAndRecord, options: [.allowBluetooth, .allowBluetoothA2DP])
+
+           // 激活音频会话
+           try audioSession.setActive(true)
+       } catch {
+           // 音频会话配置失败
+       }
+   }
+   ```
+- **播放铃声时的特殊处理（可选）**
+
+   如果您需要在等待接听时播放铃声，并且希望铃声通过扬声器播放，可以临时切换音频会话为 `.playback` 模式：
+
+   ``` swift
+   /**
+    * 播放铃声时切换音频会话
+    *
+    * 使用场景：当您使用 AVAudioPlayer 播放铃声时
+    */
+   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条群消息，如果存在通话邀请，则触发来电邀请事件。