Handling Incoming Push Notifications in AWS Amplify

AWS Amplify provides two push notification configuration functions to configure how push notifications are handled by your app: onNotification, and onNotificationOpened

This post explores the details of when the handler functions passed to those two configuration functions will be called when an Android push notification is received by your AWS Amplify React Native app. The behavior will be different depending on whether the app is in the foreground, background, or closed, and whether the user clicks the push notification or just opens the app.

For now, this is Android-specific. I have not yet tested how iOS push notifications interact with the push notification handler functions.

The example code for this post uses React Native 61.5 and AWS Amplify 2.2.2, and is at https://github.com/dantasfiles/AmplifyAndroidPush

This post is part of a series:
- Setting up Android Push Notifications with AWS Amplify
- Testing Push Notifications with AWS Amplify & CLI
- Handling Incoming Push Notifications in AWS Amplify
- Customizing the Appearance of Android Push Notifications with AWS Amplify

PushNotification.onNotification

// App.js
PushNotification.onNotification(notification => {
  if (notification.foreground) {
    console.log('onNotification foreground', notification);
  } else {
    console.log('onNotification background or closed',
               notification);
  }
  // extract the data passed in the push notification
  const data = JSON.parse(notification.data['pinpoint.jsonBody']);
  console.log('onNotification data', data);
  // iOS only
  notification.finish(PushNotificationIOS.FetchResult.NoData);
});

If the app is in the foreground or in the background, your PushNotification.onNotification handler function is called when a push notification is received by the app. Your handler function is passed a notification object of the following form:

{
  body: PUSH NOTIFICATION BODY,
  data: {
    "pinpoint.campaign.campaign_id": "_DIRECT",
    "pinpoint.notification.body": PUSH NOTIFICATION BODY,
    "pinpoint.notification.silentPush": "0",
    "pinpoint.notification.title": PUSH NOTIFICATION TITLE,
    "pinpoint.openApp": "true"
    "pinpoint.jsonBody": PUSH NOTIFICATION DATA
    ...
  },
  foreground: IS APP IN FOREGROUND OR BACKGROUND,
  title: PUSH NOTIFICATION TITLE
}

If the app is closed, the PushNotification.onNotification handler function is called by a background service when a push notification is received. The foreground field will be set to false. This process does not open the closed app into your Android Overview/Recents screen, and your React components are not yet rendered until the app is actually launched.

PushNotification.onNotificationOpened

// App.js
PushNotification.onNotificationOpened(notification => {
  console.log('onNotificationOpened', notification);
  // extract the data passed in the push notification
  const data = JSON.parse(notification['pinpoint.jsonBody']);
  console.log('onNotificationOpened data', data);
});

Your PushNotification.onNotificationOpened handler function is called if the app is in the background or closed, and a received push notification is clicked by the user. Your handler function is passed a notification object of the following form:

{
  id: "XXXXXXXXX",
  "pinpoint.campaign.campaign_id": "_DIRECT",
  "pinpoint.notification.body": PUSH NOTIFICATION BODY,
  "pinpoint.notification.silentPush": "0",
  "pinpoint.notification.title": PUSH NOTIFICATION TITLE,
  "pinpoint.openApp": "true",
  "pinpoint.jsonBody": PUSH NOTIFICATION DATA
  userInteraction: false
}

Your handler function will not trigger if the app is open in the foreground. It will also not trigger if a push notification is received while the app is in the background or closed, but the user chooses to open the app by clicking on its icon rather than clicking on the push notification itself.

Special Cases

Here are a few special cases you should be aware of:

• If 1) the app is in the background when a push notification is received, 2) the app is manually closed from the Overview/Recents screen, and 3) the push notification is clicked, then nothing will happen.
• If 1) the app is closed when a push notification is received, 2) the app is opened with its icon, 3) the app is closed from the Overview/Recents screen, and 4) the push notification is clicked, then nothing will happen

This post is part of a series:
- Setting up Android Push Notifications with AWS Amplify
- Testing Push Notifications with AWS Amplify & CLI
- Handling Incoming Push Notifications in AWS Amplify
- Customizing the Appearance of Android Push Notifications with AWS Amplify