Migrate from v5 to v6

This guide will help you migrate Amplify JavaScript v5's Push Notifications APIs to the new v6's Push Notifications APIs.

Installation

With the introduction of v6, JavaScript polyfills and core native modules are a part of the @aws-amplify/react-native package. The necessary dependencies have changed as follows:

Instructions for React Native version 0.72 and below

@aws-amplify/react-native requires a minimum iOS deployment target of 13.0 if you are using react-native version less than or equal to 0.72. Open the Podfile located in the ios directory and update the target value:

1- platform :ios, min_ios_version_supported
2 + platform :ios, 13.0

amazon-cognito-identity-js, @react-native-community/netinfo are no longer required for Push Notifications.
react-native-url-polyfill no longer needs to be installed separately.
@aws-amplify/react-native is now required.

1npm install aws-amplify @aws-amplify/react-native @aws-amplify/rtn-push-notification @react-native-async-storage/async-storage react-native-get-random-values

1npm install aws-amplify @aws-amplify/rtn-push-notification amazon-cognito-identity-js @react-native-community/netinfo @react-native-async-storage/async-storage react-native-get-random-values react-native-url-polyfill

Additionally, polyfill imports no longer need to be added to your application's entry point file.

1// Example index.js
2- import 'react-native-get-random-values';
3- import 'react-native-url-polyfill/auto';

Push.enable

The enable API has been renamed to initializePushNotifications in v6 to add clarity to the API's functionality but has otherwise not changed in behavior. This API is exported from the aws-amplify/push-notifications path.

1import { Amplify } from 'aws-amplify';
2import amplifyconfig from './amplifyconfiguration.json';
3import { initializePushNotifications } from 'aws-amplify/push-notifications';
4
5Amplify.configure(amplifyconfig);
6initializePushNotifications();

1import { Amplify, Notifications } from 'aws-amplify';
2import awsconfig from './src/aws-exports';
3
4Amplify.configure(awsconfig);
5Notifications.Push.enable();

Requesting permissions

Push.getPermissionStatus

The getPermissionStatus API in v6 has not changed in behavior; however, this API is now exported from the aws-amplify/push-notifications path and the statuses returned have been updated as follows:

Statuses have been changed from a SCREAMING_SNAKE_CASE convention to camelCase.
Returned status is now a string instead of a PushNotificationPermissionStatus enumeration.

Output

1PushNotificationPermissionStatus.SHOULD_REQUEST
2PushNotificationPermissionStatus.SHOULD_EXPLAIN_THEN_REQUEST
3PushNotificationPermissionStatus.GRANTED
4PushNotificationPermissionStatus.DENIED

1'shouldRequest' | 'shouldExplainThenRequest' | 'granted' | 'denied'

1import { getPermissionStatus } from 'aws-amplify/push-notifications';
2
3const status = await getPermissionStatus();

1import { Notifications } from 'aws-amplify';
2
3const status = await Notifications.Push.getPermissionStatus();

Push.requestPermissions

The requestPermissions API in v6 has not changed in behavior; however, it is now exported from the aws-amplify/push-notifications path.

1import { requestPermissions } from 'aws-amplify/push-notifications';
2
3const permissions = {
4  sound: false,
5  badge: false
6};
7
8const arePermissionsGranted = await requestPermissions(permissions);

1import { Notifications } from 'aws-amplify';
2
3const permissions = {
4  sound: false,
5  badge: false
6};
7
8const arePermissionsGranted = await Notifications.Push.requestPermissions(permissions);

Push.onTokenReceived

The onTokenReceived API in v6 has not changed in behavior; however, it is now exported from the aws-amplify/push-notifications path.

1import { onTokenReceived } from 'aws-amplify/push-notifications';
2
3const myTokenReceivedHandler: OnTokenReceivedInput = (token) => {
4  // Do something with the received token
5};
6
7const listener = onTokenReceived(myTokenReceivedHandler);
8
9listener.remove(); // Remember to remove the listener when it is no longer needed

1import { Notifications } from 'aws-amplify';
2
3const myTokenReceivedHandler = (token) => {
4  // Do something with the received token
5};
6
7const listener = Notifications.Push.onTokenReceived(myTokenReceivedHandler);
8
9listener.remove(); // Remember to remove the listener when it is no longer needed

Interacting with notifications

Interactions with push notifications in v6 have not changed in behavior. You will continue to use the onNotificationReceivedInForeground, onNotificationReceivedInBackground, onNotificationOpened and getLaunchNotification APIs to interact with them. However, these APIs are now exported from the aws-amplify/push-notifications path.

Push.onNotificationReceivedInForeground

1import { onNotificationReceivedInForeground } from 'aws-amplify/push-notifications';
2
3const myNotificationReceivedHandler = (notification) => {
4  // Respond to the received push notification message in real time
5};
6
7const listener = onNotificationReceivedInForeground(myNotificationReceivedHandler);
8
9listener.remove(); // Remember to remove the listener when it is no longer needed

1import { Notifications } from 'aws-amplify';
2
3const myNotificationReceivedHandler = (notification) => {
4  // Respond to the received push notification message in real time
5};
6
7const listener = Notifications.Push.onNotificationReceivedInForeground(
8  myNotificationReceivedHandler
9);
10
11listener.remove(); // Remember to remove the listener when it is no longer needed

Push.onNotificationReceivedInBackground

1import { onNotificationReceivedInForeground } from 'aws-amplify/push-notifications';
2
3const myNotificationReceivedHandler = (notification) => {
4  // Process the received push notification message in the background
5};
6
7const listener = onNotificationReceivedInBackground(myNotificationReceivedHandler);
8
9listener.remove(); // Depending on your use case, you may not need to remove this listener

1import { Notifications } from 'aws-amplify';
2
3const myNotificationReceivedHandler = (notification) => {
4  // Process the received push notification message in the background
5};
6
7const listener = Notifications.Push.onNotificationReceivedInBackground(
8  myNotificationReceivedHandler
9);
10
11listener.remove(); // Depending on your use case, you may not need to remove this listener

Push.onNotificationOpened

1import { onNotificationOpened } from 'aws-amplify/push-notifications';
2
3const myNotificationOpenedHandler = (notification) => {
4  // Take further action with the opened push notification message
5};
6
7const listener = onNotificationOpened(myNotificationOpenedHandler);
8
9listener.remove(); // Remember to remove the listener when it is no longer needed

1import { Notifications } from 'aws-amplify';
2
3const myNotificationOpenedHandler = (notification) => {
4  // Take further action with the opened push notification message
5};
6
7const listener = Notifications.Push.onNotificationOpened(
8  myNotificationOpenedHandler
9);
10
11listener.remove(); // Remember to remove the listener when it is no longer needed

Push.getLaunchNotification

1import { getLaunchNotification } from 'aws-amplify/push-notifications';
2
3const launchNotification = await getLaunchNotification();

1import { Notifications } from 'aws-amplify';
2
3const launchNotification = await Notifications.Push.getLaunchNotification();

Push.identifyUser

The identifyUser API in v6 has not changed in behavior; however, it is now exported from the aws-amplify/push-notifications path. Additionally, the input parameters have been updated as follows:

Instead of two position positional parameters (corresponding to userId and userInfo), there are now three named parameters: userId, userProfile and options (i.e. a single input object containing these properties).
The attributes property previously found under userInfo has been renamed to customProperties and can now be found under userProfile.
A new userAttributes property can be found under options.
New convenience properties name, email and plan can be found under userProfile. These properties are automatically merged into customProperties.

Input

1userId: string;
2userInfo: {
3  attributes?: Record<string, string[]>;
4  demographic?: {
5    appVersion?: string;
6    locale?: string;
7    make?: string;
8    model?: string;
9    modelVersion?: string;
10    platform?: string;
11    platformVersion?: string;
12    timezone?: string;
13  };
14  location?: {
15    city?: string;
16    country?: string;
17    latitude?: number;
18    longitude?: number;
19    postalCode?: string;
20    region?: string;
21  };
22  metrics?: Record<string, number>;
23}

1input: {
2  userId: string;
3  userProfile: {
4    customProperties?: Record<string, string[]>;
5    demographic?: {
6      appVersion?: string;
7      locale?: string;
8      make?: string;
9      model?: string;
10      modelVersion?: string;
11      platform?: string;
12      platformVersion?: string;
13      timezone?: string;
14    };
15    email?: string;
16    location?: {
17      city?: string;
18      country?: string;
19      latitude?: number;
20      longitude?: number;
21      postalCode?: string;
22      region?: string;
23    };
24    metrics?: Record<string, number>;
25    name?: string;
26    plan?: string;
27  };
28  options?: { userAttributes?: Record<string, string[]>; };
29}

1import { identifyUser } from 'aws-amplify/in-app-messaging';
2
3const identifyUserInput = {
4  userId: 'user-id',
5  userProfile: {
6    email: 'example@service.com',
7    name: 'User A',
8    plan: 'Standard'
9    customProperties: {
10      hobbies: ['cooking', 'knitting'],
11    },
12    demographic: {
13      appVersion: '1.0.0',
14      locale: 'en_US',
15      make: 'Apple',
16      model: 'iPhone',
17      modelVersion: '13',
18      platform: 'iOS',
19      platformVersion: '15',
20      timezone: 'Americas/Los_Angeles'
21    },
22    location: {
23      city: 'Seattle',
24      country: 'US',
25      postalCode: '98121',
26      region: 'WA',
27      latitude: 0.0,
28      longitude: 0.0
29    },
30    metrics: {
31      logins: 157
32    },
33  },
34};
35
36await identifyUser(identifyUserInput);

1import { Notifications } from 'aws-amplify';
2const { InAppMessaging } = Notifications;
3
4const userId = 'user-id';
5const userInfo = {
6  address: 'example@service.com',
7  attributes: {
8    hobbies: ['cooking', 'knitting'],
9  },
10  demographic: {
11    appVersion: '1.0.0',
12    locale: 'en_US',
13    make: 'Apple',
14    model: 'iPhone',
15    modelVersion: '13',
16    platform: 'iOS',
17    platformVersion: '15',
18    timezone: 'Americas/Los_Angeles'
19  },
20  location: {
21    city: 'Seattle',
22    country: 'US',
23    postalCode: '98121',
24    region: 'WA',
25    latitude: 0.0,
26    longitude: 0.0
27  },
28  metrics: {
29    logins: 157
30  },
31  optOut: 'NONE'
32};
33
34await InAppMessaging.identifyUser(userId, userInfo);

Adding app badge count

Getting and updating app badge count in v6 have not changed in behavior. You will continue to use the getBadgeCount, and setBadgeCount APIs. However, these APIs are now exported from the aws-amplify/push-notifications path.

Push.getBadgeCount

1import { getBadgeCount } from 'aws-amplify/push-notifications';
2
3const count = await getBadgeCount();

1import { Notifications } from 'aws-amplify';
2
3const count = await Notifications.Push.getBadgeCount();

Push.setBadgeCount

1import { setBadgeCount } from 'aws-amplify/push-notifications';
2
3setBadgeCount(42);

1import { Notifications } from 'aws-amplify';
2
3Notifications.Push.setBadgeCount(42);

Set up push notification services