iOS中Flutter_callkit_incoming分离模式下呼叫通知失效问题

问题根源 #

iOS 系统对后台唤醒有严格限制，普通 Firebase Data 通知无法在应用被彻底清除时唤醒 App，而 CallKit 的来电通知依赖苹果的 VoIP 推送（PushKit） 触发系统级来电界面——这是唯一能在 App 被杀掉后仍能触发系统来电提示的推送类型。你当前使用的 contentAvailable: true 仅能覆盖 App 后台运行（未被杀掉）的场景，无法适配彻底清除的情况。

具体修复步骤 #

1. 切换为 VoIP 推送通道（替代普通 Firebase Data 通知） #

Firebase Messaging 不原生支持 VoIP 推送，需直接通过苹果 APNs 发送 VoIP 推送：

• 登录苹果开发者后台，为你的 App 开启 VoIP 服务，并生成 VoIP 推送证书（或 p8 密钥）。
• 服务器端替换原有 Firebase 推送代码，改用 APNs 发送 VoIP 推送。示例 Node.js 代码：

const apn = require('apn');

// 配置 APNs VoIP 推送参数
const apnOptions = {
  token: {
    key: 'path/to/your-voip-key.p8',
    keyId: 'YOUR_APPLE_KEY_ID',
    teamId: 'YOUR_APPLE_TEAM_ID'
  },
  production: false // 生产环境改为 true
};

const apnProvider = new apn.Provider(apnOptions);

// 构建 VoIP 通知
const voipNotification = new apn.Notification({
  payload: {
    // 携带你的呼叫核心数据
    callId: 'unique-call-identifier',
    callerName: '来电者姓名',
    callerNumber: '138xxxxxxx'
  },
  topic: 'com.your.app.bundle.id.voip' // 格式为 App Bundle ID + .voip
});
voipNotification.pushType = 'voip';

// 发送推送
apnProvider.send(voipNotification, ['user-voip-device-token'])
  .then(result => {
    console.log('VoIP 推送发送状态:', result);
    apnProvider.shutdown();
  });

2. 配置 Flutter 项目的 VoIP 权限与监听 #

• 在 iOS 项目的 Info.plist 中添加 VoIP 相关配置：

<!-- 开启 VoIP 后台模式 -->
<key>UIBackgroundModes</key>
<array>
  <string>voip</string>
</array>

<!-- 配置 CallKit 扩展属性 -->
<key>NSExtension</key>
<dict>
  <key>NSExtensionAttributes</key>
  <dict>
    <key>com.apple.developer.pushkit.environment</key>
    <string>development</string> <!-- 生产环境改为 production -->
  </dict>
  <key>NSExtensionPointIdentifier</key>
  <string>com.apple.callkit.callprovider</string>
</dict>

• 在 Flutter 代码中初始化 PushKit 并监听 VoIP 推送回调：

import 'package:flutter_callkit_incoming/flutter_callkit_incoming.dart';
import 'package:flutter/material.dart';

void initVoipSetup() async {
  // 初始化 PushKit 监听（关键：确保 App 被杀掉后仍能接收 VoIP 推送）
  await FlutterCallkitIncoming.initPushKit();
  
  // 请求 VoIP 推送权限
  await FlutterCallkitIncoming.requestPermissions();
  
  // 获取并上传 VoIP 设备令牌（与普通 APNs 令牌不同，需单独保存到服务器）
  String? voipToken = await FlutterCallkitIncoming.getVoIPToken();
  if (voipToken != null) {
    // 将 voipToken 上传到你的服务器，用于后续发送 VoIP 推送
    // await yourApi.uploadVoipToken(voipToken);
  }
  
  // 监听 VoIP 推送事件，触发 CallKit 来电界面
  FlutterCallkitIncoming.onEvent.listen((event) {
    if (event.event == Event.actionCallIncoming) {
      // 从推送 payload 中解析呼叫参数
      final callParams = event.data;
      // 显示 CallKit 来电界面
      FlutterCallkitIncoming.showCallkitIncoming(callParams);
    }
  });
}

// 在 App 启动时调用初始化方法
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await initVoipSetup();
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'CallKit Demo',
      home: Scaffold(
        appBar: AppBar(title: const Text('CallKit Demo')),
        body: const Center(child: Text('VoIP Push Setup Completed')),
      ),
    );
  }
}

3. 关键注意事项 #

• VoIP 令牌与普通令牌不同：必须单独获取并上传服务器，不能复用普通 APNs 令牌。
• 苹果审核规范：VoIP 推送仅能用于真实的语音/视频呼叫场景，滥用会导致 App 被下架。
• 测试环境验证：测试时需使用真机，模拟器不支持 VoIP 推送。

内容的提问来源于stack exchange，提问作者Vipul waghmare