Troubleshooting Push with Capacitor

Push Notifications are a great communication method to provide important information and messages to your users, even when your application is in the background.

There are multiple architectural components involved in standing up a working Push Notification implementation; this can make identifying the root cause of Push Notification issues challenging.

This guide walks through the process of registering and receiving Push Notifications with a Capacitor application, defines success criteria at each step, and troubleshooting advice when steps fail.

Architecture

Understanding the architecture of Push Notifications can help identify which piece(s) may be causing the Push Notification process to fail. A typical Push Notification architecture is comprised of the following pieces:

1. Operating System Notification Broker - Both iOS and Android provide their own service responsible for registering Push capabilities for applications and brokers Push Notifications to their respective applications.
   1. Firebase Cloud Messaging (FCM) - This service is responsible for brokering Push Notifications for Android devices.
   2. Apple Push Notification Service (APNS) - This service is responsible for brokering Push Notifications for iOS devices.
2. Push Notification Provider - A non-Operating System service used to dispatch Push Notifications to applications.
3. Capacitor Application - The end receiver of Push Notifications. Facilitates obtaining Device Tokens and handles receiving Push Notifications and error handling at the application level.

Lifecycle

1. The lifecycle of Push Notifications starts with requesting a unique token from APNS/FCM called a Device Token; this token is unique, based on a combination of the device and the requesting application.
2. Once retrieved, the Capacitor application must register the Device Token to the desired Push Notification Provider.
3. Push Notifications will be sent from the Push Notification Provider to the Operating System's Notification Broker using the Device Token as the recipient.
4. The Operating System's Notification Broker forwards the Push Notification to the appropriate device and application based on Device Token.

Troubleshooting

The optimal way to troubleshoot Push Notifications is to work through each step of the Push Notification lifecycle, ensuring each step works before moving to the next.

Capacitor comes with a Push Notification API out-of-the-box. This API provides Operating System functionality; it does not provide the ability to register with any particular Push Notification Provider. You will need to refer to your Push Notification Provider's documentation for information on how to register with their system.

Your Push Notification Provider may supply their own Cordova/Capacitor plugin. Supplied plugins are considered out-of-scope of this guide; in the event you are using a supplied plugin it is best to follow their documentation for Troubleshooting assistance.

iOS Considerations

There are two aspects of Push Notifications that differs between iOS and Android:

1. In order to test Push Notifications on iOS, you will need a paid Apple Developer account and a physical iOS device to test with.
2. APNS provides developers with two environments: Sandbox and Production. It's important as you troubleshoot to ensure that your Capacitor application and Push Notification Provider are both pointing to the same environment.

Troubleshooting Capacitor Push Notification API

Obtaining a Device Token

First, we'll want to verify the first step of the Push Notification lifecycle: Obtaining a Device Token. Once we can verify that the Capacitor application can successfully connect to FCM/APNS and obtain a Device Token we can move to the next step.

Capacitor applications must be enabled for Push Notifications capabilities at the project level before your application code can communicate with FCM/APNS. Please refer to the Enabling Push Notifications Capabilities section of the Capacitor Push Notification API for guidance on how to enable your application for Push Notifications.

Once Push Notification capabilities are enabled, we can programmatically obtain a Device Token. Use the Push Notification API to:

1. Request Push Notification permission from the user.
2. Initiate a request to FCM/APNS to obtain a Device Token.
3. Add an event listener to handle when the registration request has been completed.

Pseudocode for this step will look like this:

import { 
  Plugins, 
  PushNotification, 
  PushNotificationToken, 
  PushNotificationActionPerformed 
} from '@capacitor/core'; 
const { PushNotifications } = Plugins; 
... 
token: PushNotificationToken; 

// Request Push Notification permission. 
const request = await PushNotifications.requestPermission(); 
if(request.granted) { 
  // The user has granted permission to register to APNS/FCM. 
  PushNotifications.register(); 
} else { 
  // The user has rejected our request to register with APNS/FCM. 
} 

// On successful registration, the device will send us the Device Token. 
PushNotifications.addListener('registration', 
  (token: PushNotificationToken) => { 
    alert('Push registration success! Device Token: ' + token.value); 
    this.token = token; 
  } 
); 

// If registration fails, alert the error message. 
PushNotifications.addListener('registrationError', 
  (error: any) => { 
    alert('Error registering for Push: ' + JSON.stringify(error)); 
  } 
);

If you do not receive a Device Token, make sure that:

1. The iOS/Android projects are correctly configured with APNS/FCM.
2. There are no typos or blocking code preventing the listeners from being invoked.

Register with Push Notification Provider

Next, you'll want to verify the second step of the Push Notification lifecycle: Registering the Device Token with a Provider.

Unfortunately, the process to register with your selected Push Notification Provider is out-of-scope of this troubleshooting guide. Each Push Notification Provider will have a unique process on to accomplish this, so it's best to refer to your Push Notification Provider's documentation for registration instructions.

Receiving Push Notifications

Finally, we'll want to verify the last step of the Push Notification lifecycle: Receiving a Push Notification.

Push Notifications will be received whether the Capacitor application is in the foreground or background. This is beneficial while troubleshooting, as we are able to execute custom code once a Push Notification is received, provided that the app is in the foreground.

Use the Push Notification API to:

1. Add an event listener that handles when a Push Notification is received.
2. Inside the handler, alert the contents of the Push Notification payload.

Pseudocode for this step will look like this:

... 
// On Push Notification received, alert the notification payload. 
PushNotifications.addListener('pushNotificationReceived', 
  (notification: PushNotification) => { 
    alert('Push received: ' + JSON.stringify(notification)); 
  } 
);

Send a Push Notification from the admin portal of your Push Notification Provider while your Capacitor application is in the foreground.

If no payload is alerted to the screen after a Push Notification was sent:

1. Check the Push Notification Provider's administration portal for errors.
2. Ensure that the Push Notification Provider's administration portal reflects that the Device Token obtained has been successfully registered.

Once a Push Notification has been received in the foreground, place the application in the background and send another Push Notification.

If there is no visual indication that a Push Notification has arrived, make sure that:

1. The Push Notification was composed in accordance to the Push Notification Provider's schema.
2. Both the title and message properties of the Push Notification are not empty.
3. The Capacitor application is not programmatically unregistering from the Push Notification Provider when placed in the background.

Still Stuck?

Don't feel discouraged, Push Notifications are one of the more difficult mobile features to integrate. Unlike most mobile features, Push Notifications have several dependencies and a wide-range of service providers - which each have their own unique integration instructions.

The Ionic team provides Advisory services that can be purchased to help guide you through integrating Push Notifications with your Capacitor application.