@tencentcloud/sdk-mcp 1.4.1 → 1.4.3-beta.1

package/resource/doc/callkit/core-sdk/ios/offline-push.md

@@ -0,0 +1,470 @@
+本文档将指导您如何基于 TIMPush 服务实现 VoIP 推送功能，适用于使用 AtomicXCore 进行无 UI 集成的场景。
+
+**注意：** 使用 VoIP 推送功能首先需要开通 TIMPush 服务。
+
+LiveCommunicationKit 需要在 **iOS 17.4 及以上系统**中使用。
+
+VoIP Push 无法复用 APNs 普通推送证书，需要单独在苹果开发者网站上申请 VoIP Push 证书。
+
+## 集成效果
+
+按照本文档接入 Apple LiveCommunicationKit 后，您的 App 将瞬间拥有微信同款的原生通话能力，在进程关闭或锁屏状态下，也能无差别唤醒系统级全屏接听界面：
+
+## 准备条件
+
+### 开通服务
+
+进入 IM 控制台 > 插件市场，单击**立即购买**或**免费试用**（每个应用可免费试用一次，有效期7天）。
+
+> **注意：** 推送插件试用或购买到期后，将自动停止提供推送服务（包括普通消息离线推送、全员/标签推送等）。为避免影响业务正常使用，请提前购买或续费。
+
+### 厂商配置
+
+#### 步骤1：申请 VoIP Push 证书
+
+在申请 VoIP Push 证书之前，请先在苹果开发者中心开启 App 的远程推送功能。当 AppID 具备了 Push Notification 能力后，按如下步骤操作：
+
+1. 登录苹果开发者中心，单击 **Certificates, IDs & Profiles**
+2. 单击 Certificates 右侧的 **+**
+3. 在 **Create a New Certificate** 中，选择 **VoIP Services Certificate**，单击 **Continue**
+4. 在 **Select an App ID for your VoIP Service Certificate** 中，选择当前 App 的 BundleID，单击 **Continue**
+5. 系统提示需要一个 **Certificate Signing Request（CSR）**
+6. 制作 CSR 文件：Mac 上打开**钥匙串访问工具**，菜单选择 **钥匙串访问 > 证书助理 > 从证书颁发机构请求证书**
+7. 输入用户电子邮件地址、常用名称，选择**存储到磁盘**，单击继续，生成 `*.certSigningRequest` 文件
+8. 返回 Apple Developer 网站，上传 `*.certSigningRequest` 文件，单击 Continue 生成证书，点击 Download 下载
+9. 双击打开 `voip_services.cer`，系统将其导入钥匙串
+10. 打开钥匙串应用，在 **登录 > 我的证书**，右键导出 VoIP Services 的 **P12** 文件
+
+> **说明：** 保存 P12 文件时，请务必为其设置密码。
+
+#### 步骤2：上传证书到 IM 控制台
+
+登录 IM 控制台，选择 IM 应用，按如下步骤上传证书：
+
+1. 选择 IM 应用，进入应用的**接入设置**
+2. 在**厂商配置**中，切换到 **iOS**，点击**添加证书**，上传 iOS 证书（p12），设置证书密码，单击**确认**
+3. 上传完成后，**记录不同环境下的证书 ID**
+
+> **说明：**
+> - 添加证书时，推送类型默认为 APNs，不影响 VoIP 证书的上传和使用。
+> - VoIP Push 证书本身不区分生产环境和测试环境，生产环境和开发环境使用同一份证书，请分别上传
+> - 上传证书名最好使用全英文（不能使用括号等特殊字符）
+> - 上传证书需要设置密码，无密码收不到推送
+> - 发布 App Store 的证书需要设置为生产环境，否则无法收到推送
+> - 上传的 p12 证书必须是自己申请的真实有效的证书
+> - 开发环境和生产环境下的证书 ID 要严格区分
+
+## 功能接入
+
+### 步骤1：完成工程配置
+
+1. 在工程的 **Capability** 中添加 **Push Notification** 能力
+2. 在工程 Capability 的 **Background Modes** 中，开启 **Voice over IP** 选项
+
+### 步骤2：添加依赖
+
+**1. 添加 Pod 依赖：** 在 `Podfile` 文件中添加：
+
+```ruby
+pod 'TUICore'
+```
+
+**2. 安装组件：** 在终端进入 `Podfile` 所在目录，执行：
+
+```bash
+pod install --repo-update
+```
+
+### 步骤3：初始化 PushKit 并设置证书 ID
+
+创建一个类来管理 VoIP 推送，初始化 PushKit 用于接收 VoIP 推送通知：
+
+```swift
+import PushKit
+import ImSDK_Plus
+import LiveCommunicationKit
+
+class VoIPPushManager: NSObject {
+    private let pushRegistry: PKPushRegistry
+    private var certificateID: Int = 0
+    private var voipToken: Data?  // 保存 Token，待 TUILogin 成功后上报
+
+    private var currentCallUUID: UUID?
+
+    // ConversationManager：用于步骤 7 展示系统来电界面
+    private lazy var conversationManager: ConversationManager = {
+        let configuration = ConversationManager.Configuration(
+            ringtoneName: "phone_ringing.mp3",  // 来电铃声文件名
+            iconTemplateImageData: nil,         // 来电图标（可选）
+            supportsVideo: true                  // 是否支持视频通话
+        )
+        let manager = ConversationManager(configuration: configuration)
+        manager.delegate = self
+        return manager
+    }()
+
+    override init() {
+        pushRegistry = PKPushRegistry(queue: DispatchQueue.main)
+        super.init()
+        pushRegistry.delegate = self
+        pushRegistry.desiredPushTypes = [.voIP]
+
+        NotificationCenter.default.addObserver(
+            self,
+            selector: #selector(onTUILoginSuccess),
+            name: NSNotification.Name("TUILoginSuccess"),
+            object: nil
+        )
+    }
+
+    deinit {
+        NotificationCenter.default.removeObserver(self)
+    }
+
+    func setCertificateID(_ certificateID: Int) {
+        self.certificateID = certificateID
+    }
+
+    @objc private func onTUILoginSuccess() {
+        uploadVoIPToken()
+    }
+
+    private func uploadVoIPToken() {
+        guard let token = voipToken else {
+            return
+        }
+        guard certificateID != 0 else {
+            return
+        }
+
+        let config = V2TIMVOIPConfig()
+        config.certificateID = certificateID
+        config.token = token
+
+        V2TIMManager.sharedInstance().setVOIP(config: config, succ: {
+            // VoIP Token 上报成功
+        }, fail: { code, desc in
+            // VoIP Token 上报失败
+        })
+    }
+}
+```
+
+在 `AppDelegate` 中初始化并设置证书 ID：
+
+```swift
+class AppDelegate: UIResponder, UIApplicationDelegate {
+    private lazy var voipPushManager: VoIPPushManager = {
+        let manager = VoIPPushManager()
+        manager.setCertificateID(1234) // 替换为您在 IM 控制台获取的证书 ID
+        return manager
+    }()
+
+    func application(_ application: UIApplication,
+                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
+        _ = voipPushManager
+        return true
+    }
+}
+```
+
+> **注意：**
+> - `certificateID` 是您在 IM 控制台上传证书后获取的证书 ID
+> - 开发环境和生产环境的证书 ID 要严格区分
+
+### 步骤4：获取并保存 VoIP Token
+
+实现 `PKPushRegistryDelegate` 代理方法，获取到 VoIP Token 后先保存，等待 TUILogin 成功后再上报：
+
+```swift
+import PushKit
+import ImSDK_Plus
+
+extension VoIPPushManager: PKPushRegistryDelegate {
+    func pushRegistry(_ registry: PKPushRegistry,
+                     didUpdate pushCredentials: PKPushCredentials,
+                     for type: PKPushType) {
+        guard type == .voIP else { return }
+
+        // 保存 token
+        voipToken = pushCredentials.token
+
+        let tokenString = pushCredentials.token.map { String(format: "%02.2hhx", $0) }.joined()
+
+        // 如果 TUILogin 已经完成，立即上报
+        uploadVoIPToken()
+    }
+
+    func pushRegistry(_ registry: PKPushRegistry,
+                     didInvalidatePushTokenFor type: PKPushType) {
+        // VoIP Token 已失效
+    }
+}
+```
+
+> **注意：** VoIP Token 的上报必须在 IM SDK 登录成功后才能进行，因此不宜在首次获取 Token 的回调里假设登录已完成。
+
+### 步骤5：Token 上报
+
+在用户登录时，需要先登录 IM SDK，再登录 TUICore。TUICore 登录成功后会发送 `TUILoginSuccess` 通知，`VoIPPushManager` 监听到该通知后会自动上报 VoIP Token：
+
+```swift
+import TUICore
+import AtomicXCore
+
+// 步骤1：登录 IM SDK（AtomicXCore 的 LoginStore）
+LoginStore.shared.login(
+    sdkAppID: sdkAppID,
+    userID: userID,
+    userSig: userSig
+) { result in
+    switch result {
+    case .success:
+        // 步骤2：登录 TUICore
+        TUILogin.login(
+            sdkAppID,
+            userID: userID,
+            userSig: userSig
+        ) {
+            // TUICore 登录成功，触发 VoIP Token 上报
+            NotificationCenter.default.post(
+                name: NSNotification.Name("TUILoginSuccess"),
+                object: nil
+            )
+        } fail: { code, message in
+            // TUICore 登录失败
+        }
+    case .failure(let error):
+        // IM SDK 登录失败
+    }
+}
+```
+
+### 步骤6：接收 VoIP 推送通知
+
+实现 PKPushRegistryDelegate 代理方法，收到 VoIP 推送时必须在 5 秒内向系统报告来电，否则会 crash。
+
+```swift
+extension VoIPPushManager: PKPushRegistryDelegate {
+    func pushRegistry(_ registry: PKPushRegistry,
+                     didReceiveIncomingPushWith payload: PKPushPayload,
+                     for type: PKPushType) {
+        guard type == .voIP else { return }
+
+        // 必须在 5 秒内向系统报告来电，否则会 crash
+        showIncomingCall(with: payload)
+    }
+}
+```
+
+### 步骤7：展示来电通知
+
+使用 LiveCommunicationKit 向系统报告来电，系统自动展示原生来电界面：
+
+```swift
+import LiveCommunicationKit
+
+extension VoIPPushManager {
+    private func showIncomingCall(with payload: PKPushPayload) {
+        // 解析推送数据
+        let payloadDict = payload.dictionaryPayload
+
+        // 1. 获取来电者名称（必需字段）
+        guard let callerName = payloadDict["voip_caller_name"] as? String else {
+            return
+        }
+
+        // 2. 解析 ext 字段获取通话类型（音频/视频）
+        var isVideoCall = false
+        if let extString = payloadDict["ext"] as? String,
+           let extData = extString.data(using: .utf8),
+           let extDic = try? JSONSerialization.jsonObject(with: extData) as? [String: Any],
+           let voipExtDic = extDic["voip_ext"] as? [String: String],
+           let mediaType = voipExtDic["voip_media_type"] {
+            isVideoCall = (mediaType == "video")
+        }
+
+        // 创建来电通知内容
+        let uuid = UUID()
+        currentCallUUID = uuid
+
+        var update = Conversation.Update(
+            members: [Handle(type: .generic, value: callerName, displayName: callerName)]
+        )
+        update.capabilities = isVideoCall ? .video : .playingTones
+
+        // 向系统报告来电（系统自动展示原生来电界面）
+        Task {
+            do {
+                try await conversationManager.reportNewIncomingConversation(uuid: uuid, update: update)
+            } catch {
+                // 报告失败
+            }
+        }
+    }
+}
+
+// MARK: - ConversationManagerDelegate
+extension VoIPPushManager: ConversationManagerDelegate {
+    func conversationManager(_ manager: ConversationManager, perform action: ConversationAction) {
+        if action is JoinConversationAction {
+            // 用户点击"接听"
+            CallStore.shared.accept { result in
+                switch result {
+                case .success:
+                    // 接听成功，可在此跳转到通话页面
+                    break
+                case .failure(let error):
+                    break
+                }
+            }
+        } else if action is EndConversationAction {
+            // 用户点击"挂断"
+            CallStore.shared.hangup { result in
+                switch result {
+                case .success:
+                    break
+                case .failure(let error):
+                    break
+                }
+            }
+        }
+
+        // 必须调用 fulfill() 通知系统操作已完成
+        action.fulfill()
+    }
+}
+```
+
+您可以通过配置 `Conversation.Update` 的参数，自定义来电界面显示的来电者信息、通话类型等内容。
+
+**`Conversation.Update` 参数说明：**
+
+| 参数 | 类型 | 是否必需 | 说明 |
+|------|------|----------|------|
+| `members` | [Handle] | 必需 | 来电者信息数组，支持多人通话场景。每个 Handle 包含：`type`通常使用 `.generic`；`value`来电者唯一标识（建议使用用户 ID）；`displayName`显示在来电界面的名称 |
+| `capabilities` | Conversation.Capabilities | 必需 | 通话类型：`.video`为视频通话（显示视频图标）；`.playingTones`为语音通话（显示语音图标） |
+
+说明：用户点击「接听」或「挂断」后，系统会回调 [ConversationManagerDelegate](https://developer.apple.com/documentation/livecommunicationkit/conversationmanagerdelegate)，您需在回调中处理接听/挂断逻辑（例如跳转通话页、调用 [CallStore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callstore) 等）。
+
+参考资料：[Apple LiveCommunicationKit 文档](https://developer.apple.com/documentation/livecommunicationkit)。
+
+## 发起 VoIP 通话
+
+### 发起通话
+
+`AtomicXCore` 的 `CallStore` 已经默认使用 VoIP 推送，您不需要手动设置 `offlinePushInfo` 参数。`CallStore` 内部会自动配置以下推送信息：
+
+- **推送类型：** `.voIP`
+- **推送标题：** 当前用户 ID
+- **推送描述：** `"You have a new call"`
+- **iOS 铃声：** `phone_ringing.mp3`
+
+```swift
+import AtomicXCore
+
+// 构造通话参数（不需要设置 offlinePushInfo）
+var params = CallParams()
+params.timeout = 30               // 超时时间（秒）
+params.userData = "自定义数据"   // 扩展信息（可选）
+
+// 发起通话
+let userIdList = ["被叫用户的 userID"]
+let mediaType = CallMediaType.video  // .video 视频通话，.audio 语音通话
+
+CallStore.shared.calls(
+    participantIds: userIdList,
+    callMediaType: mediaType,
+    params: params
+) { result in
+    switch result {
+    case .success:
+        // 通话发起成功，可跳转到您自己的通话页面
+        break
+    case .failure(let error):
+        // 通话失败处理
+        break
+    }
+}
+```
+
+> **说明：VoIP 推送降级策略**
+>
+> 当使用 VoIP 推送时，后台会智能判断证书类型，保证用户仍能收到推送通知：
+> - 上传的是 VoIP 证书：发送 VoIP Push
+> - 上传的是 APNs 证书：自动降级为 APNs 推送
+
+### 接听通话
+
+当被叫用户离线时收到 VoIP 推送并点击接听，系统会唤醒您的 App。此时需要监听通话事件并跳转到您自己实现的通话页面。
+
+```swift
+import AtomicXCore
+import Combine
+
+class YourViewController: UIViewController {
+    private var cancellables = Set<AnyCancellable>()
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+
+        CallStore.shared.callEventPublisher
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] event in
+                guard let self = self else { return }
+                switch event {
+                case .onCallReceived(let callId, let mediaType, let userData):
+                    // 收到来电，跳转到您自己的通话页面
+                    self.showCallViewController(callId: callId, mediaType: mediaType, userData: userData)
+                case .onCallEnded(let callId, let mediaType, let reason, let userId):
+                    // 通话结束，返回或更新 UI
+                    self.dismissCallViewController()
+                case .onCallStarted(let callId, let mediaType):
+                    // 通话已开始
+                    break
+                }
+            }
+            .store(in: &cancellables)
+    }
+
+    private func showCallViewController(callId: String, mediaType: CallMediaType, userData: String) {
+        // 跳转到您自己的通话页面
+        let callVC = YourCallViewController()
+        callVC.callId = callId
+        callVC.mediaType = mediaType
+        callVC.userData = userData
+        callVC.modalPresentationStyle = .fullScreen
+        present(callVC, animated: true)
+    }
+
+    private func dismissCallViewController() {
+        // 关闭通话页面
+        dismiss(animated: true)
+    }
+}
+```
+
+## 常见问题
+
+### 获取不到 VoIP Push，如何处理？
+
+1. **检查登录顺序：** 必须先登录 IM SDK，再登录 TUICore，否则 VoIP Token 无法上报（参考步骤 5）。
+2. 检查 App 的运行环境与证书环境是否一致，证书 ID 是否匹配；不一致则无法收到推送。
+3. 确认当前登录账号是否处于离线状态：按 Home 切后台、登录后主动杀进程退出。VoIP Push 目前只支持离线状态下的推送。
+4. 检查**完成工程配置**（步骤 1）是否正确。
+5. **尝试重启测试手机**以清除系统缓存和内存（很重要）。
+6. IM 控制台提供推送排查工具，帮助您快速排查推送问题，使用方式详见：Push 排查工具。（很重要）
+
+### 应用在收到 VoIP 推送后 crash 怎么办？
+
+这通常是因为没有在 5 秒内向系统发送展示通知的请求。请确保在 `didReceiveIncomingPushWith` 回调中立即调用 `reportNewIncomingConversation` 方法。
+
+### 如何自定义来电通知的内容？
+
+您可以通过 `Conversation.Update` 自定义来电通知，包括：
+
+- 来电者信息（`displayName`）
+- 通话类型（`capabilities`：`.video` 或 `.playingTones`）
+- 其他自定义信息
+
+具体用法请参考 [Apple LiveCommunicationKit](https://developer.apple.com/documentation/livecommunicationkit) 官方文档。