feat: show an incoming call from native code, and observe events natively on iOS

[sboily]

A call push can wake an app whose JavaScript isn't running or isn't ready, yet the call has to ring at once. Luge Mobile shows its calls from native code on both platforms, with this code patched onto 4.4.0. This PR proposes it upstream.

Rebased on master with #904 and #905. #904 is what lets the native path use a foregroundService: the service reads its settings itself and no longer needs the module.

Android (self-managed, Android 8 and later)

• RNCallKeepModule.setupNative(context, options)
  • Stores the settings and registers the phone account as setup() does, without creating a module or a React context.
  • Leaves the service available, the state setup() ends in once the account is registered (setup() sets it unavailable first, then available).
  • Throws IllegalArgumentException unless selfManaged is true on Android 8+.
• RNCallKeepModule.displayIncomingCall(context, uuid, number, callerName, hasVideo)
  • Shows the call with that phone account.
  • Throws IllegalStateException before any setup in the process.
  • The app handles the call from CallKeep's existing local broadcasts. CallKeep keeps a broadcast for JavaScript only when no receiver gets it, so once the app registers its own receiver, those events aren't returned by getInitialEvents() when React Native starts (documented).
• VoiceConnectionService.nativeFocusListener and hasConnectionServiceFocus()
  • They expose Telecom's call focus (Android 9 and later), so native code can start the call's audio before React Native runs, and release it when the focus is lost.
  • Telecom calls no onConnectionServiceFocusLost when the last call ends, so deinitConnection resets the state when the last connection goes.

To get there, initializeTelecomManager, registerPhoneAccount, storeSettings, getApplicationName and isSelfManaged become static and take the context as an argument; the JavaScript path calls them as before.

iOS

sendEventWithNameWrapper also posts each event to NotificationCenter, under its native name (RNCallKeepPerformAnswerCallAction, ...), with the body as userInfo. Native code can then follow the call's actions before a React Native runtime exists, or while JavaScript is busy, as Android's local broadcasts already allow. The JavaScript events are unchanged.

The notification is posted on the thread that sends the event, which can be CallKit's private queue (didDisplayIncomingCall). The docs recommend observing with queue: .main.

Docs

• docs/setup.md: Setup from native code (Android).
• docs/events.md: Listening from native code (iOS), with the notification names and the thread.
• CHANGELOG.md: updated.

Tests

• tests/android/CallKeepNativeSetupTest.kt, run in the example app (React Native 0.87.1) on a Galaxy S24 with Android 16, passes:

  • native setup, and an incoming call with no module;
  • the call focus once the call is active;
  • no focus once it has ended. Without the reset in deinitConnection, it fails with "the call focus outlived the last call".

  It doesn't compile on master, since the API is new.

• Lint and checks: ./gradlew :react-native-callkeep:lintDebug reports no errors, and npm run check passes.

• Luge Mobile: on the same S24, its 8 Android instrumentation classes pass with master plus fix(android): the foreground service keeps an app's channel and starts without the module #904, feat(android): foregroundServiceType and endCallsOnHostDestroy options #905 and this branch (native incoming call, silence, answer, hold, focus loss, end). That run used the first version of these branches.

• After the rebase: this test, CallKeepCallLifetimeOptionsTest and fix(android): the foreground service keeps an app's channel and starts without the module #904's two CallKeepForegroundServiceTest cases pass in the example app.

• iOS:

  • In a test harness, a native observer receives didDisplayIncomingCall, with the callUUID and the payload, before the module exists, and JavaScript still receives it afterwards. On master the observer receives nothing.
  • It is also the code Luge Mobile ships.

🤖 Generated with Claude Code