react-native-voip-push-notification

Since VoIP pushes are time-sensitive, they may arrive while the React Native JavaScript bridge is still initializing. The didLoadWithEvents event provides a way to catch these missed events.

When this event fires, it returns an array of event objects. Each object contains a name and data. You should check the name against the following constants to process them correctly:

• VoipPushNotification.RNVoipPushRemoteNotificationsRegisteredEvent
• VoipPushNotification.RNVoipPushRemoteNotificationReceivedEvent

VoipPushNotification.addEventListener('didLoadWithEvents', (events) => {
    if (!events || !Array.isArray(events) || events.length < 1) {
        return;
    }
    for (let voipPushEvent of events) {
        let { name, data } = voipPushEvent;
        if (name === VoipPushNotification.RNVoipPushRemoteNotificationsRegisteredEvent) {
            // Manually trigger your registration logic with 'data'
        } else if (name === VoipPushNotification.RNVoipPushRemoteNotificationReceivedEvent) {
            // Manually trigger your notification logic with 'data'
        }
    }
});

The JavaScript API allows you to register for VoIP tokens and handle incoming notifications. Because VoIP pushes are time-sensitive, you should set up your event listeners as early as possible in your application lifecycle (e.g., in componentDidMount of your root component or at a global scope).

Key Methods

• registerVoipToken(): Registers the PushKit delegate. If you have already registered on the native side, this acts as a no-op but will fire the register event if a cached token is available.
• onVoipNotificationCompleted(notification.uuid): Notifies PushKit that the received VoIP push has been handled. This is crucial for managing the system's push lifecycle.

Event Listeners

• 'register': Fired when PushKit provides the latest token. Use this to send the token to your APNs provider server.
• 'notification': Fired when a VoIP push notification is received. Use this to initiate calls or show local notifications.
• 'didLoadWithEvents': Fired when events (like register or notification) occurred before the JavaScript bridge was fully initialized. This allows you to process missed events manually.

import VoipPushNotification from 'react-native-voip-push-notification';

// 1. Subscribe to 'register' to get the token
VoipPushNotification.addEventListener('register', (token) => {
    // Send token to your server
});

// 2. Subscribe to 'notification' to handle incoming calls
VoipPushNotification.addEventListener('notification', (notification) => {
    // Handle the call (e.g., show UI, register VoIP client)
    
    // Tell PushKit the notification is handled
    VoipPushNotification.onVoipNotificationCompleted(notification.uuid);
});

// 3. Handle events that happened before JS bridge was ready
VoipPushNotification.addEventListener('didLoadWithEvents', (events) => {
    if (!events || !Array.isArray(events)) return;
    
    for (let event of events) {
        if (event.name === VoipPushNotification.RNVoipPushRemoteNotificationsRegisteredEvent) {
            // Handle registration
        } else if (event.name === VoipPushNotification.RNVoipPushRemoteNotificationReceivedEvent) {
            // Handle notification
        }
    }
});

// 4. Trigger registration
VoipPushNotification.registerVoipToken();

To handle VoIP pushes, you must modify your AppDelegate.m to import the necessary headers and implement the PushKit delegate methods.

Important: It is highly recommended to call [RNVoipPushNotificationManager voipRegistration] inside didFinishLaunchingWithOptions as early as possible to avoid delays caused by JS initialization.

Critical Requirement: On iOS 13+, you must report incoming VoIP pushes to CallKit immediately upon receipt. Failure to do so will result in the system terminating your app. It is recommended to use react-native-callkeep alongside this module.

#import <PushKit/PushKit.h>
#import "RNVoipPushNotificationManager.h"

// ... inside didFinishLaunchingWithOptions
[RNVoipPushNotificationManager voipRegistration];

// ... implement PushKit delegate methods
- (void)pushRegistry:(PKPushRegistry *)registry didUpdatePushCredentials:(PKPushCredentials *)credentials forType:(PKPushType)type {
  [RNVoipPushNotificationManager didUpdatePushCredentials:credentials forType:(NSString *)type];
}

- (void)pushRegistry:(PKPushRegistry *)registry didReceiveIncomingPushWithPayload:(PKPushPayload *)payload forType:(PKPushType)type withCompletionHandler:(void (^)(void))completion {
  // 1. Extract payload data
  NSString *uuid = payload.dictionaryPayload[@"uuid"];
  // ...

  // 2. Process the push
  [RNVoipPushNotificationManager didReceiveIncomingPushWithPayload:payload forType:(NSString *)type];

  // 3. MANDATORY: Report to CallKit ASAP
  // [RNCallKeep reportNewIncomingCall:...]

  completion();
}

The following native methods are available for use within AppDelegate.m. These are primarily used to handle VoIP pushes immediately, often before the JavaScript bridge is available, which is critical for time-sensitive VoIP tasks.

Use addEventListener(type, handler) to listen for specific VoIP lifecycle events. The library supports one listener per event type at a time; calling addEventListener for an existing type will automatically remove the previous listener to prevent memory leaks.

Supported event types:

• notification: Fired when a remote notification is received. The handler receives the notificationPayload.
• register: Fired when the user registers for remote notifications. The handler receives the deviceToken.
• didLoadWithEvents: Fired when the user has initially subscribed to a listener and the system has cached events that occurred while the app was not running. The handler receives the events array.

import RNVoipPushNotification from 'react-native-voip-push-notification';

// Listen for incoming notifications
RNVoipPushNotification.addEventListener('notification', (notificationPayload) => {
  console.log('Received notification:', notificationPayload);
});

// Listen for device token registration
RNVoipPushNotification.addEventListener('register', (deviceToken) => {
  console.log('VoIP Device Token:', deviceToken);
});

// Listen for cached events
RNVoipPushNotification.addEventListener('didLoadWithEvents', (events) => {
  console.log('Cached events:', events);
});