diff --git a/src/fragments/lib-v1/push-notifications/react-native/interact_with_notifications/on-foreground-notification.mdx b/src/fragments/lib-v1/push-notifications/react-native/interact_with_notifications/on-foreground-notification.mdx index 8f9a25e3088..beae80e0a70 100644 --- a/src/fragments/lib-v1/push-notifications/react-native/interact_with_notifications/on-foreground-notification.mdx +++ b/src/fragments/lib-v1/push-notifications/react-native/interact_with_notifications/on-foreground-notification.mdx @@ -1,6 +1,6 @@ ```js const myNotificationReceivedHandler = (notification) => { - // Respond to the received push notification message in realtime + // Respond to the received push notification message in real time }; const listener = Notifications.Push.onNotificationReceivedInForeground( diff --git a/src/fragments/lib/push-notifications/react-native/interact_with_notifications/on-background-notification.mdx b/src/fragments/lib/push-notifications/react-native/interact_with_notifications/on-background-notification.mdx index 9eb934cf5c1..89fcfdba45f 100644 --- a/src/fragments/lib/push-notifications/react-native/interact_with_notifications/on-background-notification.mdx +++ b/src/fragments/lib/push-notifications/react-native/interact_with_notifications/on-background-notification.mdx @@ -40,7 +40,7 @@ AppRegistry.registerComponent(appName, () => App); // Example index.js import { initializePushNotifications, - onNotificationReceivedInForeground + onNotificationReceivedInBackground } from 'aws-amplify/push-notifications'; // ... diff --git a/src/pages/[platform]/build-a-backend/push-notifications/push-notifications-migration-guide/index.mdx b/src/pages/[platform]/build-a-backend/push-notifications/push-notifications-migration-guide/index.mdx index 18b5dbebb08..b2cf735c650 100644 --- a/src/pages/[platform]/build-a-backend/push-notifications/push-notifications-migration-guide/index.mdx +++ b/src/pages/[platform]/build-a-backend/push-notifications/push-notifications-migration-guide/index.mdx @@ -19,142 +19,522 @@ export function getStaticProps(context) { }; } -## Initialize, request permissions, and receive device tokens +This guide will help you migrate Amplify JavaScript v5's Push Notifications APIs to the new v6's Push Notifications APIs. -As of v6 of Amplify JavaScript, you will now import the functional API’s directly from the `aws-amplify/push-notifications` path as shown in the code block. You can also see the differences in APIs for initializing push notifications, asking for the permission or its status and finally how to obtain the device token. +## Installation -Note: Red lines of code are v5 and Green lines are v6. +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: + +- `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. + + + + ```sh + npm install aws-amplify @aws-amplify/react-native @aws-amplify/rtn-push-notification @react-native-async-storage/async-storage react-native-get-random-values + ``` + + + + ```sh + npm 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. ```diff +// Example index.js +- import 'react-native-get-random-values'; +- import 'react-native-url-polyfill/auto'; +``` -- import { Notifications } from 'aws-amplify'; +## Push.enable -+ import { -+ initializePushNotifications, -+ getPermissionStatus, -+ requestPermissions, -+ onTokenReceived, -+ } from 'aws-amplify/push-notifications'; +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. -import { Amplify } from 'aws-amplify'; -import awsconfig from './src/aws-exports'; + + + ```ts + import { Amplify, Notifications } from 'aws-amplify'; + import awsconfig from './src/aws-exports'; -Amplify.configure(awsconfig); + Amplify.configure(awsconfig); + Notifications.Push.enable(); + ``` -- Notifications.Push.enable(); -+ initializePushNotifications(); + + + ```ts + import { Amplify } from 'aws-amplify'; + import amplifyconfig from './amplifyconfiguration.json'; + import { initializePushNotifications } from 'aws-amplify/push-notifications'; -- const status = await Notifications.Push.getPermissionStatus(); -+ const status = await getPermissionStatus(); + Amplify.configure(amplifyconfig); + initializePushNotifications(); + ``` -const permissions = { - // permissions are true by default - // alert: true - sound: false, - badge: false -}; + + -- const result = await Notifications.Push.requestPermissions(permissions); -+ const arePermissionsGranted = await requestPermissions(permissions); +## Requesting permissions -const myTokenReceivedHandler = (token) => { - // Do something with the received token -}; +### Push.getPermissionStatus -- Notifications.Push.onTokenReceived(myTokenReceivedHandler); -+ onTokenReceived(myTokenReceivedHandler); +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. -## Interaction with notifications -APIs related to interaction with notifications remains largely the same expect the functional approach in using them. + + +
+ **V5** -```diff -- import { Notifications } from 'aws-amplify'; + ``` + PushNotificationPermissionStatus.SHOULD_REQUEST + PushNotificationPermissionStatus.SHOULD_EXPLAIN_THEN_REQUEST + PushNotificationPermissionStatus.GRANTED + PushNotificationPermissionStatus.DENIED + ``` -+ import { -+ initializePushNotifications, -+ onNotificationReceivedInBackground, -+ onNotificationReceivedInForeground, -+ onNotificationOpened, -+ getLaunchNotification, -+ } from 'aws-amplify/push-notifications'; +
+
+ **V6** -Amplify.configure(config); + ``` + 'shouldRequest' | 'shouldExplainThenRequest' | 'granted' | 'denied' + ``` -- Notifications.Push.enable(); -+ initializePushNotifications(); +
+
+
-// Note: This handler does not *need* to be async, but it can be! -const myAsyncNotificationReceivedHandler = async (notification) => { - // Process the received push notification message in the background -}; + + + ```ts + import { getPermissionStatus } from 'aws-amplify/push-notifications'; -// It is recommended that you add this before registering your app component. -// You also shouldn't need to remove this listener if it is added here. -- Notifications.Push.onNotificationReceivedInBackground(myAsyncNotificationReceivedHandler); -+ onNotificationReceivedInBackground(myAsyncNotificationReceivedHandler); + const status = await getPermissionStatus(); + ``` -AppRegistry.registerComponent(appName, () => App); + + + ```ts + import { Notifications } from 'aws-amplify'; -const myNotificationReceivedHandler = (notification) => { - // Respond to the received push notification message in realtime -}; + const status = await Notifications.Push.getPermissionStatus(); + ``` -- const listener = Notifications.Push.onNotificationReceivedInForeground( -- myNotificationReceivedHandler -- ); + + -+ const listener = onNotificationReceivedInForeground( -+ myNotificationReceivedHandler -+ ); +### Push.requestPermissions -const myNotificationOpenedHandler = (notification) => { - // Take further action with the opened push notification message -}; +The `requestPermissions` API in v6 has not changed in behavior; however, it is now exported from the `aws-amplify/push-notifications` path. -- const listener = Notifications.Push.onNotificationOpened( -- myNotificationOpenedHandler -- ); + + + ```ts + import { requestPermissions } from 'aws-amplify/push-notifications'; -+ const listener = onNotificationOpened( -+ myNotificationOpenedHandler -+ ); + const permissions = { + sound: false, + badge: false + }; -- await Notifications.Push.getLaunchNotification(); -+ const launchNotification = await getLaunchNotification(); + const arePermissionsGranted = await requestPermissions(permissions); + ``` -``` -## IdentityUser + + + ```ts + import { Notifications } from 'aws-amplify'; -Differences in identifying a user is as shown below. The input type change is identical to the changes made for the `identifyUser` of the In App Messaging category mentioned above. + const permissions = { + sound: false, + badge: false + }; -```diff -- import { Notifications } from 'aws-amplify'; -+ import { identifyUser } from 'aws-amplify/push-notifications'; + const arePermissionsGranted = await Notifications.Push.requestPermissions(permissions); + ``` -- await Notifications.Push.identifyUser(userId, userInfo); -+ await identifyUser(identifyUserInput); -``` + + -## Badge count customization -Badge count management on iOS has the following changes, -```diff -- import { Notifications } from 'aws-amplify'; +## Push.onTokenReceived -+ import { -+ getBadgeCount, -+ GetBadgeCountOutput, -+ setBadgeCount, -+ SetBadgeCountInput -+ } from 'aws-amplify/push-notifications'; +The `onTokenReceived` API in v6 has not changed in behavior; however, it is now exported from the `aws-amplify/push-notifications` path. -- const count = await Notifications.Push.getBadgeCount(); -+ const count: GetBadgeCountOutput = await getBadgeCount(); + + + ```ts + import { onTokenReceived } from 'aws-amplify/push-notifications'; -const count: SetBadgeCountInput = 42; + const myTokenReceivedHandler: OnTokenReceivedInput = (token) => { + // Do something with the received token + }; -- Notifications.Push.setBadgeCount(count); -+ setBadgeCount(count); + const listener = onTokenReceived(myTokenReceivedHandler); -``` + listener.remove(); // Remember to remove the listener when it is no longer needed + ``` + + + + ```ts + import { Notifications } from 'aws-amplify'; + + const myTokenReceivedHandler = (token) => { + // Do something with the received token + }; + + const listener = Notifications.Push.onTokenReceived(myTokenReceivedHandler); + + listener.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 + + + + ```ts + import { onNotificationReceivedInForeground } from 'aws-amplify/push-notifications'; + + const myNotificationReceivedHandler = (notification) => { + // Respond to the received push notification message in real time + }; + + const listener = onNotificationReceivedInForeground(myNotificationReceivedHandler); + + listener.remove(); // Remember to remove the listener when it is no longer needed + ``` + + + + ```ts + import { Notifications } from 'aws-amplify'; + + const myNotificationReceivedHandler = (notification) => { + // Respond to the received push notification message in real time + }; + + const listener = Notifications.Push.onNotificationReceivedInForeground( + myNotificationReceivedHandler + ); + + listener.remove(); // Remember to remove the listener when it is no longer needed + ``` + + + + +### Push.onNotificationReceivedInBackground + + + + ```ts + import { onNotificationReceivedInForeground } from 'aws-amplify/push-notifications'; + + const myNotificationReceivedHandler = (notification) => { + // Process the received push notification message in the background + }; + + const listener = onNotificationReceivedInBackground(myNotificationReceivedHandler); + + listener.remove(); // Depending on your use case, you may not need to remove this listener + ``` + + + + ```ts + import { Notifications } from 'aws-amplify'; + + const myNotificationReceivedHandler = (notification) => { + // Process the received push notification message in the background + }; + + const listener = Notifications.Push.onNotificationReceivedInBackground( + myNotificationReceivedHandler + ); + + listener.remove(); // Depending on your use case, you may not need to remove this listener + ``` + + + + +### Push.onNotificationOpened + + + + ```ts + import { onNotificationOpened } from 'aws-amplify/push-notifications'; + + const myNotificationOpenedHandler = (notification) => { + // Take further action with the opened push notification message + }; + + const listener = onNotificationOpened(myNotificationOpenedHandler); + + listener.remove(); // Remember to remove the listener when it is no longer needed + ``` + + + + ```ts + import { Notifications } from 'aws-amplify'; + + const myNotificationOpenedHandler = (notification) => { + // Take further action with the opened push notification message + }; + + const listener = Notifications.Push.onNotificationOpened( + myNotificationOpenedHandler + ); + + listener.remove(); // Remember to remove the listener when it is no longer needed + ``` + + + + +### Push.getLaunchNotification + + + + ```ts + import { getLaunchNotification } from 'aws-amplify/push-notifications'; + + const launchNotification = await getLaunchNotification(); + ``` + + + + ```ts + import { Notifications } from 'aws-amplify'; + + const 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`. + + + +
+ **V5** + + ``` + userId: string; + userInfo: { + attributes?: Record; + demographic?: { + appVersion?: string; + locale?: string; + make?: string; + model?: string; + modelVersion?: string; + platform?: string; + platformVersion?: string; + timezone?: string; + }; + location?: { + city?: string; + country?: string; + latitude?: number; + longitude?: number; + postalCode?: string; + region?: string; + }; + metrics?: Record; + } + ``` + +
+
+ **V6** + + ``` + input: { + userId: string; + userProfile: { + customProperties?: Record; + demographic?: { + appVersion?: string; + locale?: string; + make?: string; + model?: string; + modelVersion?: string; + platform?: string; + platformVersion?: string; + timezone?: string; + }; + email?: string; + location?: { + city?: string; + country?: string; + latitude?: number; + longitude?: number; + postalCode?: string; + region?: string; + }; + metrics?: Record; + name?: string; + plan?: string; + }; + options?: { userAttributes?: Record; }; + } + ``` + +
+
+
+ + + + ```ts + import { identifyUser } from 'aws-amplify/in-app-messaging'; + + const identifyUserInput = { + userId: 'user-id', + userProfile: { + email: 'example@service.com', + name: 'User A', + plan: 'Standard' + customProperties: { + hobbies: ['cooking', 'knitting'], + }, + demographic: { + appVersion: '1.0.0', + locale: 'en_US', + make: 'Apple', + model: 'iPhone', + modelVersion: '13', + platform: 'iOS', + platformVersion: '15', + timezone: 'Americas/Los_Angeles' + }, + location: { + city: 'Seattle', + country: 'US', + postalCode: '98121', + region: 'WA', + latitude: 0.0, + longitude: 0.0 + }, + metrics: { + logins: 157 + }, + }, + }; + + await identifyUser(identifyUserInput); + ``` + + + + ```ts + import { Notifications } from 'aws-amplify'; + const { InAppMessaging } = Notifications; + + const userId = 'user-id'; + const userInfo = { + address: 'example@service.com', + attributes: { + hobbies: ['cooking', 'knitting'], + }, + demographic: { + appVersion: '1.0.0', + locale: 'en_US', + make: 'Apple', + model: 'iPhone', + modelVersion: '13', + platform: 'iOS', + platformVersion: '15', + timezone: 'Americas/Los_Angeles' + }, + location: { + city: 'Seattle', + country: 'US', + postalCode: '98121', + region: 'WA', + latitude: 0.0, + longitude: 0.0 + }, + metrics: { + logins: 157 + }, + optOut: 'NONE' + }; + + await 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 + + + + ```ts + import { getBadgeCount } from 'aws-amplify/push-notifications'; + + const count = await getBadgeCount(); + ``` + + + + ```ts + import { Notifications } from 'aws-amplify'; + + const count = await Notifications.Push.getBadgeCount(); + ``` + + + + +### Push.setBadgeCount + + + + ```ts + import { setBadgeCount } from 'aws-amplify/push-notifications'; + + setBadgeCount(42); + ``` + + + + ```ts + import { Notifications } from 'aws-amplify'; + + Notifications.Push.setBadgeCount(42); + ``` + + +