@tencent-rtc/mcp 1.4.6 → 1.6.0-beta.1

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

@@ -1,1248 +0,0 @@
-This guide walks you through implementing the "Make a Call" feature using the **AtomicXCore SDK**, leveraging the **DeviceStore**, **CallStore**, and the core UI component **CallCoreView**.
-
-## Core Features
-
-To build multi-party audio/video calling scenarios with **AtomicXCore**, you'll use the following three core modules:
-
-| **Module** | **Description** |
-| --- | --- |
-| [CallCoreView](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callcoreview) | Core call UI component. Automatically observes `CallStore` data and renders video streams, with support for UI customization such as layout switching, avatar and icon configuration. |
-| [CallStore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callstore) | Manages the call lifecycle: make, answer, reject, and hang up calls. Provides real-time access to participant audio/video status, call duration, call history, and more. |
-| [DeviceStore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/devicestore) | Controls audio/video devices: microphone (toggle/on/off, volume), camera (toggle/on/off, switch, quality), screen sharing, and real-time device status monitoring. |
-
-## Getting Started
-
-### Step 1: Activate the Service
-
-Follow the Activate the Service guide to obtain either a trial or paid version of the SDK.
-
-### Step 2: Integrate the SDK
-
-1. **Add Pod dependency:** Add `pod 'AtomicXCore'` to your project's `Podfile`.
-
-```ruby
-target 'YourProjectTarget' do
-    pod 'AtomicXCore'
-end
-```
-
-> **Tips:**
->
-> If your project doesn't have a Podfile, navigate to your `.xcodeproj` directory in the terminal and run `pod init` to create one.
-
-2. **Install the component:** In the terminal, go to the directory containing your `Podfile` and run:
-
-```bash
-pod install --repo-update
-```
-
-> **Tips:**
->
-> After installation, open your project using the `YourProjectName.xcworkspace` file.
-
-### Step 3: Initialize and Log In
-
-Complete these steps in order:
-
-1. **Create `CallStore`:** `let _ = CallStore.shared` initializes the call data layer.
-2. **Log in the user:** call `LoginStore.shared.login(...)` to complete IM login.
-3. **Initialize the call engine:** after login succeeds, call `TUICallEngine.createInstance().init(...)` to initialize the TRTC call signaling engine (**required**; omitting this may prevent calls from being placed or received correctly).
-
-Sample:
-
-```swift
-import UIKit
-import AtomicXCore
-import RTCRoomEngine
-import Combine
-
-class ViewController: UIViewController {
-    var cancellables = Set<AnyCancellable>()
-
-    override func viewDidLoad() {
-        super.viewDidLoad()
-        // Initialize CallStore
-        let _ = CallStore.shared
-
-        // Set up user information
-        let userID = "test_001"                    // Replace with your UserID
-        let sdkAppID: Int = 1400000001             // Replace with your SDKAppID from the console
-        let secretKey = "**************"           // Replace with your SecretKey from the console; for development only — never ship the SDKSecretKey
-
-        // Generate UserSig (for local testing only; always generate UserSig on your server in production).
-        // When Tencent RTC MCP Server is configured with sdkAppID and sdkSecretKey, the tool can issue it for you automatically.
-        let userSig = GenerateTestUserSig.genTestUserSig(
-            userID: userID,
-            sdkAppID: sdkAppID,
-            secretKey: secretKey
-        )
-
-        // Log in
-        LoginStore.shared.login(
-            sdkAppID: Int32(sdkAppID),
-            userID: userID,
-            userSig: userSig
-        ) { result in
-            switch result {
-            case .success:
-                Log.info("login success")
-                // Initialize 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)")
-            }
-        }
-    }
-}
-```
-
-**Login parameters:**
-
-| **Parameter** | **Type** | **Description** |
-| --- | --- | --- |
-| `userID` | `String` | Unique user ID, up to **32 bytes**, with **no special characters**; use letters and digits. Avoid simple IDs like `1` or `123` to reduce multi-device conflicts. |
-| `sdkAppID` | `int` | Obtain from the Tencent RTC console; typically a 10-digit integer starting with `140` or `160`. |
-| `secretKey` | `String` | SDKSecretKey paired with the `sdkAppID`, available in the Tencent RTC console. Used **only** to locally compute `UserSig` during development; never ship the SDKSecretKey with a release build. When **Tencent RTC MCP Server** is configured with both `sdkAppID` and `sdkSecretKey`, the tool can issue `UserSig` for you automatically. |
-| `userSig` | `String` | Authentication token for TRTC. **Development**: use [GenerateTestUserSig.genTestUserSig](https://github.com/Tencent-RTC/TUIKit_iOS/blob/main/application/Debug/GenerateTestUserSig.swift) or the UserSig Tool to generate a temporary `UserSig`. When **Tencent RTC MCP Server** is configured with both `sdkAppID` and `sdkSecretKey`, the tool can issue a `UserSig` for you automatically. **Production**: always generate `UserSig` server-side with the SDKSecretKey; never embed or distribute the SDKSecretKey in the client. |
-
-## Implementation Steps
-
-> **Before making a call, ensure the user is logged in** — this is required for the service to function. The following five steps outline how to implement the "Make a Call" feature.
-
-### Step 1: Create the Call Interface
-
-You need to create a call screen that is displayed when a call is initiated.
-
-1. **Create the call screen:** Implement a new `UIViewController` to serve as the call interface. This will be used for both outgoing and incoming calls.
-2. **Attach [CallCoreView](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callcoreview/):** Add the core call view component to your call screen. `CallCoreView` automatically observes `CallStore` data and renders video streams, with options for customizing layout, avatars, and icons.
-
-```swift
-import UIKit
-import AtomicXCore
-
-class CallViewController: UIViewController {
-    private var callCoreView: CallCoreView?
-
-    override func viewDidLoad() {
-        super.viewDidLoad()
-        view.backgroundColor = .black
-        // Attach CallCoreView to the call screen
-        callCoreView = CallCoreView(frame: view.bounds)
-        callCoreView?.autoresizingMask = [.flexibleWidth, .flexibleHeight]
-        if let callCoreView = callCoreView {
-            view.addSubview(callCoreView)
-        }
-    }
-}
-```
-
-**CallCoreView Feature Overview:**
-
-| **Feature** | **Description** | **Reference** |
-| --- | --- | --- |
-| **Set Layout Mode** | Switch between layout modes. If not set, layout adapts automatically based on participant count. | Switching Layout Modes |
-| **Set Avatar** | Customize avatars for specific users by providing avatar resource paths. | Customizing Default Avatars |
-| **Set Volume Indicator Icon** | Set custom volume indicator icons for different volume levels. | Customizing Volume Indicator Icons |
-| **Set Network Indicator Icon** | Set network status indicator icons based on real-time network quality. | Customizing Network Indicator Icons |
-| **Set Waiting Animation for Users** | Support GIF animations for users in the waiting state during multi-party calls. | Customizing Waiting Animations |
-
-### Step 2: Add Call Control Buttons
-
-Use the APIs from [DeviceStore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/devicestore) and [CallStore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callstore) to implement custom call control buttons.
-
-- **DeviceStore Controls:** Microphone (toggle/on/off, volume), camera (toggle/on/off, switch, quality), screen sharing, and real-time device status monitoring. Bind button actions to the corresponding methods, and update button UI in real time by observing device status changes.
-- **CallStore Controls:** Answer, hang up, reject, and other core call actions. Bind button actions to the appropriate methods and observe call status to keep the UI in sync.
-
-**Icon Resources:** Download button icons from the [GitHub icon folder](https://github.com/Tencent-RTC/TUIKit_iOS/tree/main/atomic_x/Resources/AtomicX.xcassets/icon/call). These icons are designed for TUICallKit and are free to use.
-
-| **Resource** | **Description** | **Download** |
-| --- | --- | --- |
-| `icon_dialing` | Dial / accept call icon. | [GitHub](https://github.com/Tencent-RTC/TUIKit_iOS/tree/main/atomic_x/Resources/AtomicX.xcassets/icon/call/icon_dialing.imageset) |
-| `icon_hangup` | Hang up / reject call icon. | [GitHub](https://github.com/Tencent-RTC/TUIKit_iOS/tree/main/atomic_x/Resources/AtomicX.xcassets/icon/call/icon_hangup.imageset) |
-| `icon_camera_off` | Camera off icon. | [GitHub](https://github.com/Tencent-RTC/TUIKit_iOS/tree/main/atomic_x/Resources/AtomicX.xcassets/icon/call/icon_camera_off.imageset) |
-| `icon_camera_on` | Camera on icon. | [GitHub](https://github.com/Tencent-RTC/TUIKit_iOS/tree/main/atomic_x/Resources/AtomicX.xcassets/icon/call/icon_camera_on.imageset) |
-| `icon_mute_on` | Mute toggle (on) icon. | [GitHub](https://github.com/Tencent-RTC/TUIKit_iOS/tree/main/atomic_x/Resources/AtomicX.xcassets/icon/call/icon_mute_on.imageset) |
-| `icon_mute` | Mute icon. | [GitHub](https://github.com/Tencent-RTC/TUIKit_iOS/tree/main/atomic_x/Resources/AtomicX.xcassets/icon/call/icon_mute.imageset) |
-| `icon_handsfree` | Handsfree off icon. | [GitHub](https://github.com/Tencent-RTC/TUIKit_iOS/tree/main/atomic_x/Resources/AtomicX.xcassets/icon/call/icon_handsfree.imageset) |
-| `icon_handsfree_on` | Handsfree on icon. | [GitHub](https://github.com/Tencent-RTC/TUIKit_iOS/tree/main/atomic_x/Resources/AtomicX.xcassets/icon/call/icon_handsfree_on.imageset) |
-
-**Example: Adding Hang Up, Microphone, and Camera Buttons**
-
-1.1 **Add Hang Up Button:** Create and add a hang up button. When tapped, call `hangup` and close the call screen.
-
-```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: "hangup"
-        )
-        button.backgroundColor = .systemRed
-        button.addTarget(self, action: #selector(touchHangupButton), for: .touchUpInside)
-        return button
-    }()
-
-    override func viewDidLoad() {
-        super.viewDidLoad()
-        // Other initialization code
-        // 1. Add a hang-up button
-        view.addSubview(buttonHangup)
-    }
-
-    @objc private func touchHangupButton() {
-        // 2. Call the hangup API in the click event and destroy the page
-        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 **Add Microphone Toggle Button:** Create and add a microphone toggle button. When tapped, call [openLocalMicrophone](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/devicestore/openlocalmicrophone(completion:)) or [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: "Microphone"
-        )
-        button.addTarget(self, action: #selector(touchMicrophoneButton), for: .touchUpInside)
-        return button
-    }()
-
-    override func viewDidLoad() {
-        super.viewDidLoad()
-        // Other initialization code
-        // 1. Add a microphone toggle button
-        view.addSubview(buttonMicrophone)
-    }
-
-    // 2. Toggle the microphone (on/off) in the click event
-    @objc private func touchMicrophoneButton() {
-        let microphoneStatus = DeviceStore.shared.state.value.microphoneStatus
-        if microphoneStatus == .on {
-            DeviceStore.shared.closeLocalMicrophone()
-        } else {
-            DeviceStore.shared.openLocalMicrophone(completion: nil)
-        }
-    }
-
-    // Helper method to create circular buttons
-    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.3 **Add Camera Toggle Button:** Add a camera toggle button to the bottom toolbar. When tapped, call [openLocalCamera](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/devicestore/openlocalcamera(isfront:completion:)) or [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: "Camera"
-        )
-        button.addTarget(self, action: #selector(touchCameraButton), for: .touchUpInside)
-        return button
-    }()
-
-    override func viewDidLoad() {
-        super.viewDidLoad()
-        // Other initialization code
-        // 1. Add camera toggle button
-        view.addSubview(buttonCamera)
-    }
-
-    // 2. Camera button click event
-    @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)
-        }
-    }
-
-    // Helper method to create circular buttons
-    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.4 **Update Button Labels in Real Time:** Observe microphone and camera status and update button labels accordingly.
-
-```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()
-        // Other initialization code
-        // 1. Observe microphone and camera status
-        observeDeviceState()
-    }
-
-    private func observeDeviceState() {
-        DeviceStore.shared.state.subscribe()
-            .map { $0.cameraStatus }
-            .removeDuplicates()
-            .receive(on: DispatchQueue.main)
-            .sink { [weak self] cameraStatus in
-                // 2. Update camera button text
-                let title = cameraStatus == .on ? "Turn Off Camera" : "Turn On Camera"
-                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. Update microphone button text
-                let title = microphoneStatus == .on ? "Turn Off Mic" : "Turn On Mic"
-                self?.buttonMicrophone?.setTitle(title, for: .normal)
-            }
-            .store(in: &cancellables)
-    }
-}
-```
-
-### Step 3: Request Microphone/Camera Permissions
-
-Check for audio/video permissions before starting a call. If permissions are missing, prompt the user to grant them.
-
-1. **Declare permissions:** Add the following keys to your app's `Info.plist` with appropriate usage descriptions. These will be shown to users when the system requests permissions:
-
-```xml
-<key>NSCameraUsageDescription</key>
-<string>Camera access is required for video calls and group video calls.</string>
-<key>NSMicrophoneUsageDescription</key>
-<string>Microphone access is required for audio calls, group audio calls, video calls, and group video calls.</string>
-```
-
-2. **Request permissions dynamically:** Request audio/video permissions based on the call media type when initiating a call.
-
-```swift
-import AVFoundation
-import UIKit
-
-extension UIViewController {
-    // Check microphone permission
-    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)
-        }
-    }
-
-    // Check camera permission
-    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)
-        }
-    }
-
-    // Show permission alert
-    func showPermissionAlert(message: String) {
-        let alert = UIAlertController(
-            title: "Permission Required",
-            message: message,
-            preferredStyle: .alert
-        )
-        alert.addAction(UIAlertAction(title: "Settings", style: .default) { _ in
-            if let url = URL(string: UIApplication.openSettingsURLString) {
-                UIApplication.shared.open(url)
-            }
-        })
-        alert.addAction(UIAlertAction(title: "Cancel", style: .cancel))
-        present(alert, animated: true)
-    }
-}
-```
-
-### Step 4: Make a Call
-
-After calling [calls](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callstore/calls(participantids:callmediatype:params:completion:)), navigate to the call screen. For the best user experience, automatically enable the microphone or camera based on the media type.
-
-1. **Initiate the call:** Call `calls` to start a call.
-2. **Enable media devices:** After the call is initiated, enable the microphone. If it's a video call, also enable the camera.
-3. **Present the call screen:** On successful call initiation, present the call screen.
-
-```swift
-import UIKit
-import AtomicXCore
-import Combine
-
-class MainViewController: UIViewController {
-    // 1. Initiate a call
-    private func startCall(userIdList: [String], mediaType: CallMediaType) {
-        var params = CallParams()
-        params.timeout = 30  // Set call timeout to 30 seconds
-
-        CallStore.shared.calls(
-            participantIds: userIdList,
-            mediaType: mediaType,      // Call type: .audio or .video
-            params: params
-        ) { [weak self] result in
-            switch result {
-            case .success:
-                // 2. Enable media devices
-                self?.openDevices(for: mediaType)
-                // 3. Launch the call interface
-                DispatchQueue.main.async {
-                    let callVC = CallViewController()
-                    callVC.modalPresentationStyle = .fullScreen
-                    self?.present(callVC, animated: true)
-                }
-            case .failure(let error):
-                Log.error("Failed to initiate call: \(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 API Parameter Reference:**
-
-| **Parameter** | **Type** | **Required** | **Description** |
-| --- | --- | --- | --- |
-| `participantIds` | `[String]` | Yes | A list of target user IDs. |
-| `mediaType` | `CallMediaType` | Yes | The media type of the call, used to specify whether to initiate an audio or video call.<br>- `CallMediaType.video`: Video call.<br>- `CallMediaType.audio`: Audio call. |
-| `params` | `CallParams` | No | Extended call parameters, such as Room ID, call invitation timeout, etc.<br>- `roomId` (`String`): Room ID. Optional; if not specified, it will be automatically assigned by the server.<br>- `timeout` (`Int`): Call Timeout (in seconds).<br>- `userData` (`String`): Custom user data for application-specific information.<br>- `chatGroupId` (`String`): Chat Group ID, used for group call scenarios.<br>- `isEphemeralCall` (`Bool`): Ephemeral Call. If set to `true`, no call history record will be generated. |
-
-### Step 5: End the Call
-
-When you call [hangup](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callstore/hangup(completion:)) or the remote party ends the call, the [onCallEnded](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callevent/oncallended(callid:mediatype:reason:userid:)) event is triggered. Listen for this event and close the call screen when the call ends.
-
-1. **Listen for call end event:** Observe the `onCallEnded` event.
-2. **Close the call screen:** When `onCallEnded` is triggered, dismiss the call screen.
-
-```swift
-import UIKit
-import AtomicXCore
-import Combine
-
-class CallViewController: UIViewController {
-    private var cancellables = Set<AnyCancellable>()
-
-    override func viewDidLoad() {
-        super.viewDidLoad()
-        // Other initialization code
-        // 1. Add call event listener
-        addListener()
-    }
-
-    private func addListener() {
-        CallStore.shared.callEventPublisher
-            .receive(on: DispatchQueue.main)
-            .sink { [weak self] event in
-                if case .onCallEnded = event {
-                    // 2. Dismiss the call interface
-                    self?.dismiss(animated: true)
-                }
-            }
-            .store(in: &cancellables)
-    }
-}
-```
-
-**onCallEnded Event Parameters:**
-
-| **Parameter** | **Type** | **Description** |
-| --- | --- | --- |
-| `callId` | `String` | Unique ID for this call. |
-| `mediaType` | `CallMediaType` | The media type of the call.<br>- `CallMediaType.video`: Video call.<br>- `CallMediaType.audio`: Audio call. |
-| `reason` | `CallEndReason` | The reason why the call ended.<br>- `unknown`: Unable to determine the reason for termination.<br>- `hangup`: Normal termination; a user actively ended the call.<br>- `reject`: The callee declined the incoming call.<br>- `noResponse`: The callee did not answer within the timeout period.<br>- `offline`: The callee is currently offline.<br>- `lineBusy`: The callee is already in another call.<br>- `canceled`: The caller canceled the call before it was answered.<br>- `otherDeviceAccepted`: The call was answered on another logged-in device.<br>- `otherDeviceReject`: The call was declined on another logged-in device.<br>- `endByServer`: The call was forced to end by the server. |
-| `userId` | `String` | The User ID of the person who triggered the call termination. |
-
-### Demo
-
-After completing these five steps, the "Make a Call" feature is wired up end-to-end.
-
-## Customization
-
-`CallCoreView` provides extensive UI customization, including support for custom avatars and volume indicator icons. To speed up your integration, you can download ready-to-use icons from the [GitHub icon folder](https://github.com/Tencent-RTC/TUIKit_iOS/tree/main/atomic_x/Resources/AtomicX.xcassets/icon/call). All icons are designed for TUICallKit and are free to use.
-
-### Customizing Volume Indicator Icons
-
-Use the `CallCoreView` [setVolumeLevelIcons](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callcoreview/setvolumelevelicons(icons:)) method to assign different icons for each volume level.
-
-```swift
-// Set volume indicator icons
-let volumeLevelIcons: [VolumeLevel: String] = [
-    .mute: "Path to the corresponding icon resource"
-]
-callCoreView.setVolumeLevelIcons(icons: volumeLevelIcons)
-```
-
-**setVolumeLevelIcons API Parameters:**
-
-| **Parameter** | **Type** | **Required** | **Description** |
-| --- | --- | --- | --- |
-| `icons` | `[VolumeLevel: String]` | Yes | Mapping of volume levels to icon resources.<br>**Key (`VolumeLevel`):**<br>- `VolumeLevel.mute`: Microphone is off or muted.<br>- `VolumeLevel.low`: Volume range (0, 25].<br>- `VolumeLevel.medium`: Volume range (25, 50].<br>- `VolumeLevel.high`: Volume range (50, 75].<br>- `VolumeLevel.peak`: Volume range (75, 100].<br>**Value (`String`):** Path or name of the icon resource for each volume level. |
-
-**Volume Indicator Icons:**
-
-| **Resource** | **Description** | **Download** |
-| --- | --- | --- |
-| `icon_volume` | Volume indicator icon. Set this icon for `VolumeLevel.low` or `VolumeLevel.medium`; it is displayed when the user's volume exceeds the specified level. | [GitHub](https://github.com/Tencent-RTC/TUIKit_iOS/tree/main/atomic_x/Resources/AtomicX.xcassets/icon/call/icon_volume.imageset) |
-| `icon_mic_off` | Mute icon. Set this icon for `VolumeLevel.mute`; it is displayed when the user is currently muted. | [GitHub](https://github.com/Tencent-RTC/TUIKit_iOS/tree/main/atomic_x/Resources/AtomicX.xcassets/icon/call/icon_mic_off.imageset) |
-
-### Customizing Network Indicator Icons
-
-Use the `CallCoreView` [setNetworkQualityIcons](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callcoreview/setnetworkqualityicons(icons:)) method to assign icons for different network states.
-
-```swift
-// Set network quality icons
-let networkQualityIcons: [NetworkQuality: String] = [
-    .bad: "Path to the corresponding icon"
-]
-callCoreView.setNetworkQualityIcons(icons: networkQualityIcons)
-```
-
-**setNetworkQualityIcons API Parameters:**
-
-| **Parameter** | **Type** | **Required** | **Description** |
-| --- | --- | --- | --- |
-| `icons` | `[NetworkQuality: String]` | Yes | Network Quality Icon mapping table.<br>**Key (`NetworkQuality`):**<br>- `NetworkQuality.unknown`: Network status is undetermined.<br>- `NetworkQuality.excellent`: Outstanding network connection.<br>- `NetworkQuality.good`: Stable and good network connection.<br>- `NetworkQuality.poor`: Weak network signal.<br>- `NetworkQuality.bad`: Very weak or unstable network.<br>- `NetworkQuality.veryBad`: Extremely poor network, near disconnection.<br>- `NetworkQuality.down`: Network disconnected.<br>**Value (`String`):** Absolute path or resource name of the icon corresponding to the network status. |
-
-**Network Warning Icon:**
-
-| **Resource** | **Description** | **Download** |
-| --- | --- | --- |
-| `group_network_low_quality` | Poor network indicator. Set this icon for `NetworkQuality.bad`, `NetworkQuality.veryBad`, or `NetworkQuality.down`; it is displayed when the network quality is poor. | [GitHub](https://github.com/Tencent-RTC/TUIKit_iOS/tree/main/atomic_x/Resources/AtomicX.xcassets/icon/call/group_network_low_quality.imageset) |
-
-### Customizing Default Avatars
-
-Use the `CallCoreView` [setParticipantAvatars](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callcoreview/setparticipantavatars(avatars:)) API to set user avatars. Listen to the [allParticipants](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callstate/allparticipants) reactive data: when you have a user's avatar, set and display it; if not, show the default avatar.
-
-```swift
-// Set user avatars
-var avatars: [String: String] = [:]
-let userId = ""      // User ID
-let avatarPath = ""  // Path to user's default avatar resource
-avatars[userId] = avatarPath
-
-callCoreView.setParticipantAvatars(avatars: avatars)
-```
-
-**setParticipantAvatars API Parameters:**
-
-| **Parameter** | **Type** | **Required** | **Description** |
-| --- | --- | --- | --- |
-| `avatars` | `[String: String]` | Yes | User avatar mapping table.<br>- **Key:** The `userID` of the user.<br>- **Value:** The absolute path to the user's avatar resource. |
-
-**Default Avatar:**
-
-| **Resource** | **Description** | **Download** |
-| --- | --- | --- |
-| `default_participant_icon` | Default profile picture. Use as the default avatar when a user's profile image fails to load or no avatar is provided. | [GitHub](https://github.com/Tencent-RTC/TUIKit_iOS/tree/main/atomic_x/Resources/AtomicX.xcassets/icon/call/default_participant_icon.imageset) |
-
-### Customizing Waiting Animations
-
-Use the `CallCoreView` [setWaitingAnimation](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callcoreview/setwaitinganimation(path:)) API to set a waiting animation for users who are waiting to answer.
-
-```swift
-// Set waiting animation
-let waitingAnimationPath = ""  // Path to waiting animation GIF resource
-callCoreView.setWaitingAnimation(path: waitingAnimationPath)
-```
-
-**setWaitingAnimation API Parameters:**
-
-| **Parameter** | **Type** | **Required** | **Description** |
-| --- | --- | --- | --- |
-| `path` | `String` | Yes | Absolute path to a GIF format image resource. |
-
-**User Waiting Animation:**
-
-| **Resource** | **Description** | **Download** |
-| --- | --- | --- |
-| `loading.gif` | User waiting animation. Recommended for group calls; displayed when the user's status is "Waiting to Answer" (Pending). | [GitHub](https://github.com/Tencent-RTC/TUIKit_iOS/blob/main/atomic_x/Resources/CallResource/loading.gif) |
-
-### Adding a Call Duration Indicator
-
-To display the call duration in real time, subscribe to the [activeCall](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callstate/activecall) `duration` field.
-
-1. **Subscribe to the data layer:** Subscribe to `CallStore.shared.state` to observe the active call reactively.
-2. **Bind the duration to your UI:** Bind `activeCall.duration` to your UI controls. This field is reactive and drives refreshes automatically so you don't need your own timer.
-
-```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 {
-            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
-                // Update call duration
-                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)
-    }
-}
-```
-
-> **Note:**
->
-> For more reactive call status data, see [CallState](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callstate).
-
-## More Features
-
-### Customizing User Avatar and Nickname
-
-Before a call starts, set your own nickname and avatar using [setSelfInfo](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/loginstore/setselfinfo(userprofile:completion:)).
-
-```swift
-var userProfile = UserProfile()
-userProfile.userID = ""      // Your User ID
-userProfile.avatarURL = ""   // URL of the avatar image
-userProfile.nickname = ""    // The nickname to be set
-
-LoginStore.shared.setSelfInfo(userProfile: userProfile) { result in
-    switch result {
-    case .success:
-        // Success callback: profile updated successfully
-        break
-    case .failure(let error):
-        // Failure callback: handle the error
-        break
-    }
-}
-```
-
-**setSelfInfo API Parameters:**
-
-| **Parameter** | **Type** | **Required** | **Description** |
-| --- | --- | --- | --- |
-| `userProfile` | `UserProfile` | Yes | User info struct:<br>- `userID`: User ID.<br>- `avatarURL`: User avatar URL.<br>- `nickname`: User nickname.<br>For more field details, see the [UserProfile](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/userprofile) class. |
-
-### Switching Layout Modes
-
-`CallCoreView` supports three built-in layout modes. Use [setLayoutTemplate](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callcoreview/setlayouttemplate(_:)) to set the layout. If not set, `CallCoreView` will automatically use `Float` mode for 1-on-1 calls and `Grid` mode for multi-party calls.
-
-| **Mode** | **Layout** | **Interaction** |
-| --- | --- | --- |
-| **Float Mode** | While waiting, display your own video full screen. After answering, show the remote video full screen and your own video as a floating window. | Drag the small window or tap to swap big/small video. |
-| **Grid Mode** | All participant videos are tiled in a grid. Best for 2+ participants. Tap to enlarge a video. | Tap a participant to enlarge their video. |
-| **PIP Mode** | In 1v1, remote video is fixed; in multi-party, the active speaker is shown full screen. | Shows your own video while waiting; displays the call timer after answering. |
-
-**setLayoutTemplate Sample code:**
-
-```swift
-func setLayoutTemplate(_ template: CallLayoutTemplate)
-```
-
-**setLayoutTemplate API Parameters:**
-
-| **Parameter** | **Type** | **Description** |
-| --- | --- | --- |
-| `template` | `CallLayoutTemplate` | `CallCoreView`'s layout mode.<br>- `CallLayoutTemplate.float`: While waiting, display your own video full screen; after answering, show the remote video full screen and your own video as a floating window.<br>- `CallLayoutTemplate.grid`: All participant videos are tiled in a grid; best for 2+ participants.<br>- `CallLayoutTemplate.pip`: In 1v1, remote video is fixed; in multi-party, the active speaker is shown full screen. |
-
-### Setting Default Call Timeout
-
-When making a call using [calls](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callstore/calls(participantids:callmediatype:params:completion:)), set the `timeout` field in [CallParams](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callparams) to specify the call invitation timeout.
-
-```swift
-var callParams = CallParams()
-callParams.timeout = 30  // Set call timeout to 30 seconds.
-CallStore.shared.calls(
-    participantIds: userIdList,
-    mediaType: .video,
-    params: callParams,
-    completion: nil
-)
-```
-
-**calls API Parameter Reference:**
-
-| **Parameter** | **Type** | **Required** | **Description** |
-| --- | --- | --- | --- |
-| `participantIds` | `[String]` | Yes | A list of User IDs for the target participants. |
-| `mediaType` | `CallMediaType` | Yes | The media type of the call.<br>- `CallMediaType.video`: Video Call.<br>- `CallMediaType.audio`: Audio Call. |
-| `params` | `CallParams` | No | Extended call parameters, such as Room ID, call invitation timeout, etc.<br>- `roomId` (`String`): Room ID. Optional; if not specified, it will be automatically assigned by the server.<br>- `timeout` (`Int`): Call Timeout (in seconds).<br>- `userData` (`String`): User Custom Data for app-specific logic.<br>- `chatGroupId` (`String`): Chat Group ID, used specifically for group call scenarios.<br>- `isEphemeralCall` (`Bool`): Ephemeral Call. Whether the call is encrypted and transient (will not generate a call history record). |
-
-### Implementing In-App Floating Window
-
-The AtomicXCore SDK provides the `CallPipView` component to enable in-app floating windows. When the call interface is covered by another screen (e.g., the user navigates away but the call is ongoing), a floating window displays call status and lets users quickly return to the call.
-
-**Step 1:** Create the Floating Window Controller.
-
-```swift
-import UIKit
-import AtomicXCore
-import Combine
-
-/**
- * Floating Window Controller
- *
- * Used to display the call in a floating window, containing a CallCoreView internally.
- */
-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)  // Set to Picture-in-Picture (PIP) layout mode
-        view.isUserInteractionEnabled = false  // Disable interaction to allow taps to pass through to the parent view
-        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)
-
-        // Add tap gesture recognizer
-        let tapGesture = UITapGestureRecognizer(target: self, action: #selector(handleTap))
-        view.addGestureRecognizer(tapGesture)
-
-        // Delay status observation to prevent the window from closing immediately upon creation
-        DispatchQueue.main.asyncAfter(deadline: .now() + 1.0) { [weak self] in
-            self?.observeCallStatus()
-        }
-    }
-
-    @objc private func handleTap() {
-        tapGestureAction?()
-    }
-
-    /**
-     * Observe call status changes.
-     * Automatically closes the floating window when the call ends.
-     */
-    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 {
-                    // Call ended, post notification to hide the floating window
-                    NotificationCenter.default.post(name: NSNotification.Name("HideFloatingWindow"), object: nil)
-                }
-            }
-            .store(in: &cancellables)
-    }
-
-    deinit {
-        cancellables.removeAll()
-    }
-}
-```
-
-**Step 2:** Implement floating window management logic in the main interface.
-
-```swift
-import UIKit
-import AtomicXCore
-
-class MainViewController: UIViewController {
-    private var floatWindow: UIWindow?
-
-    override func viewDidLoad() {
-        super.viewDidLoad()
-        // Listen for the notification to show the floating window
-        NotificationCenter.default.addObserver(
-            self,
-            selector: #selector(showFloatingWindow),
-            name: NSNotification.Name("ShowFloatingWindow"),
-            object: nil
-        )
-        // Listen for the notification to hide the floating window
-        NotificationCenter.default.addObserver(
-            self,
-            selector: #selector(hideFloatingWindow),
-            name: NSNotification.Name("HideFloatingWindow"),
-            object: nil
-        )
-    }
-
-    /**
-     * Displays the in-app floating window.
-     */
-    @objc private func showFloatingWindow() {
-        // Check if the call is currently active/accepted
-        let selfStatus = CallStore.shared.state.value.selfInfo.status
-        guard selfStatus == .accept else {
-            return
-        }
-        // Prevent duplicate creation if the floating window already exists
-        guard floatWindow == nil else { return }
-        // CRITICAL: The current windowScene must be used to create the new window
-        guard let windowScene = UIApplication.shared.connectedScenes.first as? UIWindowScene else {
-            return
-        }
-        // Define floating window dimensions (9:16 aspect ratio)
-        let pipWidth: CGFloat = 100
-        let pipHeight: CGFloat = pipWidth * 16 / 9
-        let pipX = UIScreen.main.bounds.width - pipWidth - 20
-        let pipY: CGFloat = 100
-
-        // Create the floating window (associated with the windowScene)
-        let window = UIWindow(windowScene: windowScene)
-        window.windowLevel = .alert + 1 // Ensure it stays above standard UI
-        window.backgroundColor = .clear
-        window.frame = CGRect(x: pipX, y: pipY, width: pipWidth, height: pipHeight)
-
-        // Initialize the floating window controller
-        let floatVC = FloatWindowViewController()
-        floatVC.tapGestureAction = { [weak self] in
-            self?.openCallViewController()
-        }
-        window.rootViewController = floatVC
-        self.floatWindow = window
-
-        // Make the window visible
-        window.isHidden = false
-        window.makeKeyAndVisible()
-
-        // Immediately restore the main window as the key window to maintain proper app focus
-        if let mainWindow = windowScene.windows.first(where: { $0 != window }) {
-            mainWindow.makeKey()
-        }
-    }
-
-    /**
-     * Hides the in-app floating window.
-     */
-    @objc private func hideFloatingWindow() {
-        floatWindow?.isHidden = true
-        floatWindow = nil
-    }
-
-    /**
-     * Opens the call interface (triggered upon tapping the floating window).
-     */
-    private func openCallViewController() {
-        // Dismiss the floating window first
-        hideFloatingWindow()
-        // Retrieve the current top-most ViewController
-        guard let topVC = getTopViewController() else {
-            return
-        }
-        let callVC = CallViewController()
-        callVC.modalPresentationStyle = .fullScreen
-        topVC.present(callVC, animated: true)
-    }
-
-    /**
-     * Utility to retrieve the current top-most ViewController in the view hierarchy.
-     */
-    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)
-    }
-}
-```
-
-**Step 3:** Add the floating window trigger logic to the Call Interface.
-
-```swift
-import UIKit
-import AtomicXCore
-
-class CallViewController: UIViewController {
-    override func viewWillAppear(_ animated: Bool) {
-        super.viewWillAppear(animated)
-        // When entering the call interface, post a notification to hide the floating window
-        NotificationCenter.default.post(name: NSNotification.Name("HideFloatingWindow"), object: nil)
-    }
-
-    override func viewWillDisappear(_ animated: Bool) {
-        super.viewWillDisappear(animated)
-        // When leaving the call interface, check if the call is still active
-        let selfStatus = CallStore.shared.state.value.selfInfo.status
-        if selfStatus == .accept {
-            // If the call is still ongoing, post a notification to show the floating window
-            NotificationCenter.default.post(name: NSNotification.Name("ShowFloatingWindow"), object: nil)
-        }
-    }
-}
-```
-
-### Enabling System Picture-in-Picture (PiP) Outside the App
-
-AtomicXCore SDK supports system-level PiP via the underlying TRTC engine. When your app goes to the background, the call video can float above other apps as a system PiP window, so users can continue their video call while multitasking.
-
-> **Note:**
->
-> 1. In Xcode, add `Background Modes` under `Signing & Capabilities` and enable `Audio, AirPlay, and Picture in Picture`.
-> 2. Requires iOS 15.0 or later.
-
-1. **Configure PiP Parameters:** You need to set parameters such as the fill mode for the PiP window, user video regions, and canvas configurations.
-
-```swift
-import Foundation
-import AtomicXCore
-
-// Fill Mode Enumeration
-enum PictureInPictureFillMode: Int, Codable {
-    case fill = 0  // Aspect Fill (Scale to fill, may crop)
-    case fit = 1   // Aspect Fit (Scale to fit, no cropping)
-}
-
-// User Video Region
-struct PictureInPictureRegion: Codable {
-    let userId: String           // Unique User ID
-    let width: Double            // Width (0.0 - 1.0, relative to canvas)
-    let height: Double           // Height (0.0 - 1.0, relative to canvas)
-    let x: Double                // X coordinate (0.0 - 1.0, relative to top-left of canvas)
-    let y: Double                // Y coordinate (0.0 - 1.0, relative to top-left of canvas)
-    let fillMode: PictureInPictureFillMode  // Rendering fill mode
-    let streamType: String       // Stream type ("high" for HD or "low" for SD)
-    let backgroundColor: String  // Hex background color (e.g., "#000000")
-}
-
-// Canvas Configuration
-struct PictureInPictureCanvas: Codable {
-    let width: Int              // Canvas width in pixels
-    let height: Int             // Canvas height in pixels
-    let backgroundColor: String // Hex background color
-}
-
-// Picture-in-Picture Parameters
-struct PictureInPictureParams: Codable {
-    let enable: Bool                        // Toggle PiP functionality
-    let cameraBackgroundCapture: Bool?      // Whether to continue camera capture in background
-    let canvas: PictureInPictureCanvas?     // Canvas settings (Optional)
-    let regions: [PictureInPictureRegion]?  // List of user video regions (Optional)
-}
-
-// PiP API Request Object
-struct PictureInPictureRequest: Codable {
-    let api: String                    // API identifier name
-    let params: PictureInPictureParams // Parameter payload
-}
-```
-
-2. **Enable Picture-in-Picture:** You can enable or disable the PiP feature using the `configPictureInPicture` method.
-
-```swift
-let params = PictureInPictureParams(
-    enable: true,
-    cameraBackgroundCapture: true,
-    canvas: nil,
-    regions: nil
-)
-
-let request = PictureInPictureRequest(
-    api: "configPictureInPicture",
-    params: params
-)
-
-// Encode to JSON string and call the Experimental API
-let encoder = JSONEncoder()
-if let data = try? encoder.encode(request),
-   let jsonString = String(data: data, encoding: .utf8) {
-    TUICallEngine.createInstance().callExperimentalAPI(jsonObject: jsonString)
-}
-```
-
-### Keeping the Screen Awake During Calls
-
-To prevent the screen from dimming or locking during a call, set `UIApplication.shared.isIdleTimerDisabled = true` when the call starts, and restore it when the call ends.
-
-```swift
-class CallViewController: UIViewController {
-    override func viewDidLoad() {
-        super.viewDidLoad()
-        // Disable automatic screen lock to keep the screen on
-        UIApplication.shared.isIdleTimerDisabled = true
-    }
-
-    override func viewWillDisappear(_ animated: Bool) {
-        super.viewWillDisappear(animated)
-        // Restore the automatic screen lock behavior
-        UIApplication.shared.isIdleTimerDisabled = false
-    }
-}
-```
-
-### Playing a Ringtone While Waiting for Answer
-
-Listen to your own call status to play a ringtone while waiting for an answer, and stop the ringtone when the call is answered or ends.
-
-```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 {
-                // Stop playing ringtone
-                return
-            }
-            if status == .waiting {
-                // Start playing ringtone
-            }
-        }
-        .store(in: &cancellables)
-}
-```
-
-### Enabling Background Audio/Video Capture
-
-To allow your app to capture audio and video while in the background (e.g., when the user locks the screen or switches apps), configure iOS background mode permissions and set up the audio session.
-
-**Configuration Steps:**
-
-1. In Xcode, select your project `Target` → `Signing & Capabilities`.
-2. Click `+ Capability`.
-3. Add `Background Modes`.
-4. Enable:
-    - `Audio, AirPlay, and Picture in Picture` (for audio capture and PiP).
-    - `Voice over IP` (for VoIP calls).
-    - `Remote notifications` (optional, for offline push).
-
-Your `Info.plist` will then include:
-
-```xml
-<key>UIBackgroundModes</key>
-<array>
-    <string>audio</string>
-    <string>voip</string>
-    <string>remote-notification</string>
-</array>
-```
-
-**Configure Audio Session (`AVAudioSession`):**
-
-Set up the audio session before the call starts, ideally in the call interface's `viewDidLoad` or before making/answering a call.
-
-```swift
-import AVFoundation
-
-/**
- * Configure the Audio Session to support background audio capture.
- *
- * Recommended to call this method in the following scenarios:
- * 1. Inside viewDidLoad of the call interface.
- * 2. Before initiating a call (calls).
- * 3. Before answering a call (accept).
- */
-private func setupAudioSession() {
-    let audioSession = AVAudioSession.sharedInstance()
-    do {
-        // Set the audio session category to PlayAndRecord.
-        // .allowBluetooth: Support for standard Bluetooth headsets.
-        // .allowBluetoothA2DP: Support for high-quality Bluetooth audio (A2DP protocol).
-        try audioSession.setCategory(.playAndRecord, options: [.allowBluetooth, .allowBluetoothA2DP])
-        // Activate the audio session.
-        try audioSession.setActive(true)
-    } catch {
-        // Audio session configuration failed.
-        print("Failed to configure Audio Session: \(error)")
-    }
-}
-```
-
-**Special Handling for Ringtone Playback (Optional):**
-
-To play a ringtone through the speaker while waiting for an answer, temporarily switch the audio session to `.playback` mode.
-
-```swift
-/**
- * Switch the Audio Session for ringtone playback.
- *
- * Use Case: When using AVAudioPlayer to play the ringtone.
- */
-private func setAudioSessionForRingtone() {
-    let audioSession = AVAudioSession.sharedInstance()
-    do {
-        // Switch to playback mode (optimizes for output only)
-        try audioSession.setCategory(.playback, options: [.allowBluetooth, .allowBluetoothA2DP])
-        // Force the ringtone to play through the built-in speaker
-        try audioSession.overrideOutputAudioPort(.speaker)
-        try audioSession.setActive(true)
-    } catch {
-        // Failed to configure Audio Session for ringtone
-        print("Ringtone audio session error: \(error)")
-    }
-}
-
-/**
- * Restore to Call Mode after the ringtone stops playing.
- */
-private func restoreAudioSessionForCall() {
-    let audioSession = AVAudioSession.sharedInstance()
-    do {
-        // Restore to PlayAndRecord mode (required for two-way VoIP communication)
-        try audioSession.setCategory(.playAndRecord, options: [.allowBluetooth, .allowBluetoothA2DP])
-        try audioSession.setActive(true)
-    } catch {
-        // Failed to restore Audio Session
-        print("Failed to restore call audio session: \(error)")
-    }
-}
-```
-
-## FAQs
-
-### If the callee is offline and comes online within the call invitation timeout, will they receive the incoming call event?
-
-For one-on-one calls, if the callee comes online within the timeout, they will receive an incoming call invitation. For group calls, if the callee comes online within the timeout, up to 20 pending group messages will be retrieved. If there is a call invitation, the incoming call event will be triggered.