Flutter开发：iOS端CallKeep在APP后台时不显示来电界面的修复方案

Hey there! Let's tackle this iOS background call notification issue together—super common with CallKeep + FCM setups, so we'll go through the critical checks step by step.

First, let's break down why this happens: iOS has strict background execution rules, so even if FCM delivers the push, your app needs the right permissions and setup to trigger CallKeep when in the background. Here's what to check:

1. Use the Correct FCM Push Payload #

FCM sends two types of pushes: notification messages and data messages. For background triggers, you need a data-only message (or a combined message with content_available: true).

• If you send a standard notification message, iOS will handle it directly and won't wake your app to trigger CallKeep.
• Make sure your FCM payload includes these key fields:

  {
    "to": "DEVICE_TOKEN",
    "content_available": true,
    "priority": "high",
    "data": {
      "call_id": "unique-call-identifier",
      "caller_name": "Jane Smith",
      "caller_number": "+1234567890",
      // Add other call-related data here
    }
  }
  

  The content_available: true flag tells iOS to wake your app in the background to process the message.

2. Enable Required iOS Capabilities in Xcode #

Your Xcode project needs specific capabilities to run CallKeep in the background:

• Open your Flutter project's ios/Runner.xcworkspace in Xcode.
• Select your target, go to the Signing & Capabilities tab.
• Add and configure these capabilities:
  • Background Modes: Check "Voice over IP" and "Remote notifications"
  • Push Notifications: Enable this (it adds the necessary entitlements)
  • VoIP: This is non-negotiable for CallKit/CallKeep to work in the background—don't skip it!

3. Configure CallKeep for Background Execution #

In your Flutter code, ensure CallKeep is initialized with iOS-specific settings that support background calls:

• Example initialization code:

  await FlutterCallKeep.instance.setup(
    'com.your.app.bundleid',
    iosOptions: IOSOptions(
      appName: 'Your App Name',
      supportsVideo: true,
      maximumCallGroups: 1,
    ),
    androidOptions: AndroidOptions(
      // Your existing Android settings
    ),
  );
  

• Make sure you're listening to the onIncomingCall stream and handling it immediately—this listener should work even when the app is backgrounded.

4. Handle FCM Messages in the Background Isolate #

Flutter's firebase_messaging uses a separate isolate for background message handling, so you need to trigger CallKeep correctly from this context:

• Create a top-level background handler function (it can't be inside a class):

  Future<void> _firebaseMessagingBackgroundHandler(RemoteMessage message) async {
    await Firebase.initializeApp();
    // Extract call data from the message payload
    final callId = message.data['call_id'];
    final callerName = message.data['caller_name'];
    
    // Trigger the CallKeep incoming call UI
    await FlutterCallKeep.instance.displayIncomingCall(
      callId,
      callerName,
      handle: message.data['caller_number'],
      hasVideo: true,
    );
  }
  
  void main() async {
    WidgetsFlutterBinding.ensureInitialized();
    await Firebase.initializeApp();
    // Register the background handler
    FirebaseMessaging.onBackgroundMessage(_firebaseMessagingBackgroundHandler);
    // Rest of your app setup
  }
  

  This ensures your app wakes up in the background to process the push and show the CallKeep UI.

5. Verify iOS Permissions #

Make sure your app has all required permissions granted:

• Request push notification permissions:

  final settings = await FirebaseMessaging.instance.requestPermission(
    alert: true,
    badge: true,
    sound: true,
    provisional: false,
  );
  

• Check CallKit permissions (CallKeep handles this, but you can verify):

  final hasPermissions = await FlutterCallKeep.instance.hasPhonePermissions();
  if (!hasPermissions) {
    // Request permissions if needed
  }
  

  Without these permissions, iOS won't allow CallKeep to show the incoming call UI in the background.

6. Test on a Physical iOS Device #

iOS simulators don't support background push notifications or CallKit properly. Always test on a real device to replicate the issue accurately.

7. Confirm FCM Message Delivery #

Check if the FCM message is actually reaching your app in the background. You can add logging in the background handler (note: background logs might not show up in the Xcode console, so use Firebase Analytics or a local logging service to verify).

If you work through all these steps, your iOS app should trigger the CallKeep incoming call UI even when in the background. Let me know if you hit any snags with specific steps!

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