iOS端flutter_callkit_incoming呼叫弹窗不显示，APN集成后交互异常

以下是针对实体iPhone上呼叫仅显示小图标、无法交互问题的排查和修复步骤：

• 确认PushKit相关权限与配置

  1. 在Info.plist中添加VoIP权限描述：

     <key>NSVoIPUsageDescription</key>
     <string>用于接收VoIP呼叫通知</string>
     

  2. 打开Xcode的Signing & Capabilities面板，确保已添加Push Notifications能力，并在Background Modes中勾选Voice over IP选项。实体设备上缺少这些配置会导致VoIP推送无法触发CallKit界面。

• 验证APNs推送负载格式
  必须使用符合VoIP规范的推送负载，普通远程推送格式无法触发CallKit。正确的负载示例：

  {
    "aps": {
      "content-available": 1
    },
    "callData": {
      "id": "unique_call_id",
      "nameCaller": "呼叫方名称",
      "handle": "13800138000",
      "type": 0,
      "duration": 30000
    }
  }
  

  注意：content-available:1是必填项，自定义呼叫数据需放在顶层而非aps内部，否则PushKit无法正确识别为VoIP呼叫。

• 检查原生回调逻辑
  在iOS原生代码的PushKitDelegate实现中，确保收到推送后正确调用flutter_callkit_incoming的显示方法，且必须调用completion回调：

  func pushRegistry(_ registry: PKPushRegistry, didReceiveIncomingPushWith payload: PKPushPayload, for type: PKPushType, completion: @escaping () -> Void) {
      guard let callData = payload.dictionaryPayload["callData"] as? [String: Any] else {
          completion()
          return
      }
      FlutterCallkitIncoming.sharedInstance.displayCall(callData)
      completion()
  }
  

  未调用completion()会导致系统判定推送处理失败，后续推送可能被限制。

• 排查设备端设置

  1. 进入iPhone设置->通知->你的应用，确保开启通知权限，且横幅样式设置为临时或持久（不能是仅通知中心），同时开启声音、标记选项。
  2. 检查设置->专注模式，确认当前启用的专注模式未屏蔽该应用的通知和VoIP呼叫。
  3. 关闭低电量模式，该模式会限制后台推送处理能力。

• 确认APNs推送环境
  实体设备需使用生产环境APNs证书推送（除非设备已添加到开发者账号的测试设备列表，才可使用开发环境证书）。可通过curl命令测试生产环境推送：

  curl -v -d '{"aps":{"content-available":1},"callData":{"id":"test_call","nameCaller":"测试呼叫","handle":"123456","type":0}}' -H "apns-topic: 你的应用BundleID.voip" -H "apns-push-type: voip" -H "apns-expiration: 0" -H "apns-priority: 5" --http2 --cert 生产证书.pem:证书密码 https://api.push.apple.com/3/device/设备Token
  

• 升级flutter_callkit_incoming版本
  旧版本可能存在实体设备适配问题，执行以下命令升级到最新版本：

  flutter pub upgrade flutter_callkit_incoming
  

内容的提问来源于stack exchange，提问作者Nitesh Neupane