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

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

@@ -1,470 +0,0 @@
-本文档将指导您如何基于 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) 官方文档。