diff --git a/public/images/push-notifications/cross-platform-lifecycle/pn-lifecycle-background.png b/public/images/push-notifications/cross-platform-lifecycle/pn-lifecycle-background.png new file mode 100644 index 00000000000..9a60d59ceea Binary files /dev/null and b/public/images/push-notifications/cross-platform-lifecycle/pn-lifecycle-background.png differ diff --git a/public/images/push-notifications/cross-platform-lifecycle/pn-lifecycle-foreground.png b/public/images/push-notifications/cross-platform-lifecycle/pn-lifecycle-foreground.png new file mode 100644 index 00000000000..a2ece852be6 Binary files /dev/null and b/public/images/push-notifications/cross-platform-lifecycle/pn-lifecycle-foreground.png differ diff --git a/public/images/push-notifications/cross-platform-lifecycle/pn-lifecycle-terminated.png b/public/images/push-notifications/cross-platform-lifecycle/pn-lifecycle-terminated.png new file mode 100644 index 00000000000..f82557aa457 Binary files /dev/null and b/public/images/push-notifications/cross-platform-lifecycle/pn-lifecycle-terminated.png differ diff --git a/public/images/push-notifications/cross-platform-service-extension/01_new-target.png b/public/images/push-notifications/cross-platform-service-extension/01_new-target.png new file mode 100644 index 00000000000..103bb6adef4 Binary files /dev/null and b/public/images/push-notifications/cross-platform-service-extension/01_new-target.png differ diff --git a/public/images/push-notifications/cross-platform-service-extension/02_target-type.png b/public/images/push-notifications/cross-platform-service-extension/02_target-type.png new file mode 100644 index 00000000000..13d5dee45f5 Binary files /dev/null and b/public/images/push-notifications/cross-platform-service-extension/02_target-type.png differ diff --git a/public/images/push-notifications/cross-platform-service-extension/03_target-name.png b/public/images/push-notifications/cross-platform-service-extension/03_target-name.png new file mode 100644 index 00000000000..4f0b367f9c7 Binary files /dev/null and b/public/images/push-notifications/cross-platform-service-extension/03_target-name.png differ diff --git a/public/images/push-notifications/cross-platform-service-extension/04_extension-info.png b/public/images/push-notifications/cross-platform-service-extension/04_extension-info.png new file mode 100644 index 00000000000..cb8e7a41eaf Binary files /dev/null and b/public/images/push-notifications/cross-platform-service-extension/04_extension-info.png differ diff --git a/public/images/push-notifications/cross-platform-service-extension/05_extension-class.png b/public/images/push-notifications/cross-platform-service-extension/05_extension-class.png new file mode 100644 index 00000000000..31392534787 Binary files /dev/null and b/public/images/push-notifications/cross-platform-service-extension/05_extension-class.png differ diff --git a/src/directory/directory.mjs b/src/directory/directory.mjs index ad1f7e3c175..b00d57a6337 100644 --- a/src/directory/directory.mjs +++ b/src/directory/directory.mjs @@ -11,7 +11,7 @@ export const directory = { }, items: {} }, - "flutter-references": { + 'flutter-references': { productRoot: { title: 'Amplify Libraries for Flutter API References', route: '/flutter-references' @@ -648,11 +648,6 @@ export const directory = { 'push-notifications': { title: 'Push Notifications', items: [ - { - title: 'Overview', - route: '/lib/push-notifications/overview', - filters: ['react-native'] - }, { title: 'Getting started', route: '/lib/push-notifications/getting-started', @@ -668,14 +663,34 @@ export const directory = { route: '/lib/push-notifications/record-notifications', filters: ['ios'] }, + { + title: 'Request permissions', + route: '/lib/push-notifications/request-permissions', + filters: ['react-native'] + }, + { + title: 'Receive device token', + route: '/lib/push-notifications/receive-device-token', + filters: ['react-native'] + }, + { + title: 'Interact with notifications', + route: '/lib/push-notifications/interact-with-notifications', + filters: ['react-native'] + }, { title: 'Identify user', route: '/lib/push-notifications/identify-user', - filters: ['android', 'ios'] + filters: ['android', 'ios', 'react-native'] + }, + { + title: 'App badge count', + route: '/lib/push-notifications/app-badge-count', + filters: ['react-native'] }, { - title: 'Working with API', - route: '/lib/push-notifications/working-with-api', + title: 'Enable rich notifications', + route: '/lib/push-notifications/enable-rich-notifications', filters: ['react-native'] }, { @@ -689,9 +704,14 @@ export const directory = { filters: ['android', 'ios', 'react-native'] }, { - title: 'Setting up push notification services', + title: 'Set up push notification services', route: '/lib/push-notifications/setup-push-service', - filters: ['android', 'ios'] + filters: ['android', 'ios', 'react-native'] + }, + { + title: 'Migrate from previous version', + route: '/lib/push-notifications/migrate-from-previous-version', + filters: ['react-native'] } ] }, diff --git a/src/fragments/lib/push-notifications/android/getting_started/10_pre_req.mdx b/src/fragments/lib/push-notifications/android/getting_started/10_pre_req.mdx index 8edd24cb532..68f2ab33a85 100644 --- a/src/fragments/lib/push-notifications/android/getting_started/10_pre_req.mdx +++ b/src/fragments/lib/push-notifications/android/getting_started/10_pre_req.mdx @@ -1,8 +1,9 @@ -* An Android application targeting at least Android SDK API level 24 with Amplify libraries integrated - * For a full example of creating Android project, please follow the [project setup walkthrough](/lib/project-setup/create-application) +- An Android application targeting at least Android SDK API level 24 with Amplify libraries integrated + - For a full example of creating an Android project, please follow the [project setup walkthrough](/lib/project-setup/create-application) +import fcmPreReq from '/src/fragments/lib/push-notifications/android/getting_started/fcm-pre-req.mdx'; -Push Notifications are delivered via Firebase Cloud Messaging (FCM), In order to use FCM, you need to register your app on the Firebase console. See [Setting up push notification services](/lib/push-notifications/setup-push-service/) for more information. + ## Request Permissions diff --git a/src/fragments/lib/push-notifications/android/getting_started/20_cli_resources.mdx b/src/fragments/lib/push-notifications/android/getting_started/20_cli_resources.mdx index a442c725205..aba2735a473 100644 --- a/src/fragments/lib/push-notifications/android/getting_started/20_cli_resources.mdx +++ b/src/fragments/lib/push-notifications/android/getting_started/20_cli_resources.mdx @@ -1,40 +1,5 @@ -> Prerequisite: [Install and configure the Amplify CLI](/cli/start/install) +import fcmCliResources from '/src/fragments/lib/push-notifications/android/getting_started/fcm-cli-resources.mdx'; - - -Push Notifications requires version **10.8.0+** of the Amplify CLI. You can check your current version by typing `amplify -version` and upgrade to the latest version by typing `amplify upgrade`. - - - -To start provisioning push notifications resources in the backend, go to your project directory and execute the command: - -```sh -amplify add notifications -``` - -Choose *FCM* when promoted: - -```console -? Choose the push notification channel to enable. - APNS |  Apple Push Notifications -❯ FCM | » Firebase Push Notifications - In-App Messaging - Email - SMS - -? Provide your pinpoint resource name: - `yourPinpointResourceName` - -? Apps need authorization to send analytics events. Do you want to allow guests and unauthenticated users to send analytics events? (we recommend you allow this when getting started) (Y/n) - 'Y' - -``` - -The CLI will prompt for your *ApiKey*, paste the **Token** you copied while [setting up push notification services](/lib/push-notifications/setup-push-service/). -Once all your configuration is complete run the following: - -```sh -amplify push -``` + Upon completion, `amplifyconfiguration.json` will be updated to reference the newly provisioned backend push notifications resources. Note that this file should already be generated for you by the Amplify CLI as a part of your project if you followed the [project setup walkthrough](/lib/project-setup/prereq). diff --git a/src/fragments/lib/push-notifications/android/getting_started/fcm-cli-resources.mdx b/src/fragments/lib/push-notifications/android/getting_started/fcm-cli-resources.mdx new file mode 100644 index 00000000000..8bc4a980782 --- /dev/null +++ b/src/fragments/lib/push-notifications/android/getting_started/fcm-cli-resources.mdx @@ -0,0 +1,23 @@ +Choose _FCM_ when promoted: + +```console +? Choose the push notification channel to enable. + APNS |  Apple Push Notifications +❯ FCM | » Firebase Push Notifications + In-App Messaging + Email + SMS + +? Provide your pinpoint resource name: + `yourPinpointResourceName` + +? Apps need authorization to send analytics events. Do you want to allow guests and unauthenticated users to send analytics events? (we recommend you allow this when getting started) (Y/n) + 'Y' + +``` + +The CLI will prompt for your _ApiKey_, paste the **Token** you copied while [setting up push notification services](/lib/push-notifications/setup-push-service/). Once all your configuration is complete run the following: + +```sh +amplify push +``` diff --git a/src/fragments/lib/push-notifications/android/getting_started/fcm-pre-req.mdx b/src/fragments/lib/push-notifications/android/getting_started/fcm-pre-req.mdx new file mode 100644 index 00000000000..ffdec0f5820 --- /dev/null +++ b/src/fragments/lib/push-notifications/android/getting_started/fcm-pre-req.mdx @@ -0,0 +1 @@ +Push Notifications are delivered via Firebase Cloud Messaging (FCM). In order to use FCM, you need to register your app on the Firebase console. See [Setting up push notification services](/lib/push-notifications/setup-push-service/) for more information. diff --git a/src/fragments/lib/push-notifications/android/identify_user/10_get_auth_user.mdx b/src/fragments/lib/push-notifications/android/identify_user/10_get_auth_user.mdx index 3c7560c1ff7..a9b98b4068d 100644 --- a/src/fragments/lib/push-notifications/android/identify_user/10_get_auth_user.mdx +++ b/src/fragments/lib/push-notifications/android/identify_user/10_get_auth_user.mdx @@ -1,3 +1,5 @@ +If the user is signed in through [Amplify.Auth.signIn](/lib/auth/signin), then you can retrieve the current user's ID as shown below: + diff --git a/src/fragments/lib/push-notifications/android/identify_user/30_send_to_pinpoint_profile.mdx b/src/fragments/lib/push-notifications/android/identify_user/30_send_to_pinpoint_profile.mdx index 48db1bc5bf2..1fd715ab4c5 100644 --- a/src/fragments/lib/push-notifications/android/identify_user/30_send_to_pinpoint_profile.mdx +++ b/src/fragments/lib/push-notifications/android/identify_user/30_send_to_pinpoint_profile.mdx @@ -1,3 +1,5 @@ +Alternatively, you can provide additional information about the user by passing a user profile: + diff --git a/src/fragments/lib/push-notifications/android/setup_push_service/handling-actions.mdx b/src/fragments/lib/push-notifications/android/setup_push_service/handling-actions.mdx new file mode 100644 index 00000000000..5be342b1ec7 --- /dev/null +++ b/src/fragments/lib/push-notifications/android/setup_push_service/handling-actions.mdx @@ -0,0 +1,3 @@ +## Handling FCM Push Notifications + +Amazon Pinpoint campaigns can take one of three actions when a user taps a notification: Open your app, Go to a URL, or Open a deep link. Follow these [instructions](https://developer.android.com/training/app-links/deep-linking) to enable your app to open deep links. diff --git a/src/fragments/lib/push-notifications/android/setup_push_service/setup-fcm.mdx b/src/fragments/lib/push-notifications/android/setup_push_service/setup-fcm.mdx index 16715ecfe69..e613a1e7cb0 100644 --- a/src/fragments/lib/push-notifications/android/setup_push_service/setup-fcm.mdx +++ b/src/fragments/lib/push-notifications/android/setup_push_service/setup-fcm.mdx @@ -1,23 +1,20 @@ ## Setting Up FCM for Push Notifications Push notifications for Android apps are sent using Firebase Cloud Messaging (FCM). Before you can send push notifications to Android devices, you must perform the following steps: + - [Create a Firebase project](https://firebase.google.com/docs/cloud-messaging/android/first-message#create_a_firebase_project). - [Register your app with Firebase](https://firebase.google.com/docs/cloud-messaging/android/first-message#register_your_app_with_firebase) - [Add a Firebase configuration file](https://firebase.google.com/docs/cloud-messaging/android/first-message#add_a_firebase_configuration_file) Next, you will need to access your **ServerKey** (Referred to as **ApiKey** in the CLI setup): + - Open the [Firebase console](https://console.firebase.google.com/). - Choose your Firebase project. - Select the gear icon located in the top left hand corner of your screen, then select **Project settings**. - Select the **Cloud Messaging** tab. -- Select the three vertical dots next to **Cloud Messaging API (Legacy)**, then select **Manage API in Google Cloud Console**. -![Firebase Console](/images/push-notifications/firebaseconsole.png) +- Select the three vertical dots next to **Cloud Messaging API (Legacy)**, then select **Manage API in Google Cloud Console**. ![Firebase Console](/images/push-notifications/firebaseconsole.png) - In the new tab, select the **Enable** button. - Return to the previous tab and refresh the page. - Copy the **Token** next to **Server key** Return to [Provisioning resources through CLI](/lib/push-notifications/getting-started/#provisioning-resources-through-cli) with the copied **Token** - -## Handling FCM Push Notifications - -Amazon Pinpoint campaigns can take one of three actions when a user taps a notification: Open your app, Go to a URL, or Open a deep link. Follow these [instructions](https://developer.android.com/training/app-links/deep-linking) to enable your app to open deep links. diff --git a/src/fragments/lib/push-notifications/common/getting-started.mdx b/src/fragments/lib/push-notifications/common/getting-started.mdx index 4967213a658..c6d50145a32 100644 --- a/src/fragments/lib/push-notifications/common/getting-started.mdx +++ b/src/fragments/lib/push-notifications/common/getting-started.mdx @@ -2,21 +2,25 @@ The Push Notifications category allows you to integrate push notifications in yo ## Prerequisites -import ios0 from "/src/fragments/lib/push-notifications/ios/getting_started/10_pre_req.mdx"; +import androidPreReq from '/src/fragments/lib/push-notifications/android/getting_started/10_pre_req.mdx'; +import iosPreReq from '/src/fragments/lib/push-notifications/ios/getting_started/10_pre_req.mdx'; +import reactNativePreReq from '/src/fragments/lib/push-notifications/react-native/getting_started/10_pre_req.mdx'; - + -import android1 from "/src/fragments/lib/push-notifications/android/getting_started/10_pre_req.mdx"; +import iosSetEntitlements from '/src/fragments/lib/push-notifications/ios/getting_started/20_set_entitlements.mdx'; - + -import ios3 from "/src/fragments/lib/push-notifications/ios/getting_started/20_set_entitlements.mdx"; +import iosCreateAppDelegate from '/src/fragments/lib/push-notifications/ios/getting_started/30_create_app_delegate.mdx'; - - -import ios6 from "/src/fragments/lib/push-notifications/ios/getting_started/30_create_app_delegate.mdx"; - - + ## Setup backend resources @@ -25,44 +29,78 @@ To use Push Notifications with Amplify, you have the option to either have the A -import ios9 from "/src/fragments/lib/push-notifications/ios/getting_started/40_cli_resources.mdx"; +> Prerequisite: [Install and configure the Amplify CLI](/cli/start/install) - + -import android4 from "/src/fragments/lib/push-notifications/android/getting_started/20_cli_resources.mdx"; +Push Notifications requires version **10.8.0+** of the Amplify CLI. You can check your current version with `amplify -version` and upgrade to the latest version with `amplify upgrade`. - + - - +To start provisioning push notification resources in the backend, go to your project directory and execute the command: -import ios12 from "/src/fragments/lib/push-notifications/ios/getting_started/50_existing_resources.mdx"; +```sh +amplify add notifications +``` - +import androidCliResources from '/src/fragments/lib/push-notifications/android/getting_started/20_cli_resources.mdx'; +import iosCliResources from '/src/fragments/lib/push-notifications/ios/getting_started/40_cli_resources.mdx'; +import reactNativeCliResources from '/src/fragments/lib/push-notifications/react-native/getting_started/20_cli_resources.mdx'; -import android7 from "/src/fragments/lib/push-notifications/android/getting_started/30_existing_resources.mdx"; + - + + + +import androidExistingResources from '/src/fragments/lib/push-notifications/android/getting_started/30_existing_resources.mdx'; +import iosExistingResources from '/src/fragments/lib/push-notifications/ios/getting_started/50_existing_resources.mdx'; +import reactNativeExistingResources from '/src/fragments/lib/push-notifications/react-native/getting_started/30_existing_resources.mdx'; + + ## Install Amplify Libraries -import ios15 from "/src/fragments/lib/push-notifications/ios/getting_started/60_install_lib.mdx"; +import androidInstallLib from '/src/fragments/lib/push-notifications/android/getting_started/40_install_lib.mdx'; +import iosInstallLib from '/src/fragments/lib/push-notifications/ios/getting_started/60_install_lib.mdx'; +import reactNativeInstallLib from '/src/fragments/lib/push-notifications/react-native/getting_started/40_install_lib.mdx'; - + -import android10 from "/src/fragments/lib/push-notifications/android/getting_started/40_install_lib.mdx"; +import reactNativeIntegrateNativeModule from '/src/fragments/lib/push-notifications/react-native/getting_started/50_integrate_native_modules.mdx'; - + ## Initialize Amplify Push Notifications -import ios18 from "/src/fragments/lib/push-notifications/ios/getting_started/70_init_push_notifications.mdx"; - - - -import android13 from "/src/fragments/lib/push-notifications/android/getting_started/50_init_push_notifications.mdx"; - - +import androidInitPN from '/src/fragments/lib/push-notifications/android/getting_started/50_init_push_notifications.mdx'; +import iosInitPN from '/src/fragments/lib/push-notifications/ios/getting_started/70_init_push_notifications.mdx'; +import reactNativeInitPN from '/src/fragments/lib/push-notifications/react-native/getting_started/60_init_push_notifications.mdx'; + + diff --git a/src/fragments/lib/push-notifications/common/identify-user.mdx b/src/fragments/lib/push-notifications/common/identify-user.mdx index a39ed4cbb1e..226f9bd8316 100644 --- a/src/fragments/lib/push-notifications/common/identify-user.mdx +++ b/src/fragments/lib/push-notifications/common/identify-user.mdx @@ -2,34 +2,35 @@ This call identifies the current user (which could be unauthenticated or authent ## Get the user ID from Amplify Auth -If the user is signed in through [Amplify.Auth.signIn](/lib/auth/signin), then you can retrieve the current user's ID as shown below: - -import android0 from "/src/fragments/lib/push-notifications/android/identify_user/10_get_auth_user.mdx"; - - - -import ios1 from "/src/fragments/lib/push-notifications/ios/identify_user/10_get_auth_user.mdx"; - - +import androidGetUser from '/src/fragments/lib/push-notifications/android/identify_user/10_get_auth_user.mdx'; +import iosGetUser from '/src/fragments/lib/push-notifications/ios/identify_user/10_get_auth_user.mdx'; +import reactNativeGetUser from '/src/fragments/lib/push-notifications/react-native/identify_user/10_get_auth_user.mdx'; + + ## Identify the user to Amazon Pinpoint Once you have a string that identifies the current user (either from the Auth category as shown above or through your own application logic), you can identify the user to Amazon Pinpoint with the following: -import android3 from "/src/fragments/lib/push-notifications/android/identify_user/20_send_to_pinpoint.mdx"; - - - -import ios4 from "/src/fragments/lib/push-notifications/ios/identify_user/20_send_to_pinpoint.mdx"; - - - -Alternatively, you can provide additional information about the user by passing a user profile: - -import android6 from "/src/fragments/lib/push-notifications/android/identify_user/30_send_to_pinpoint_profile.mdx"; +import androidSendToPinpoint from '/src/fragments/lib/push-notifications/android/identify_user/20_send_to_pinpoint.mdx'; +import iosSendToPinpoint from '/src/fragments/lib/push-notifications/ios/identify_user/20_send_to_pinpoint.mdx'; +import reactNativeSendToPinpoint from '/src/fragments/lib/push-notifications/react-native/identify_user/20_send_to_pinpoint.mdx'; - + -import ios7 from "/src/fragments/lib/push-notifications/ios/identify_user/30_send_to_pinpoint_profile.mdx"; +import androidSendWithProfile from '/src/fragments/lib/push-notifications/android/identify_user/30_send_to_pinpoint_profile.mdx'; +import iosSendWithProfile from '/src/fragments/lib/push-notifications/ios/identify_user/30_send_to_pinpoint_profile.mdx'; - +; diff --git a/src/fragments/lib/push-notifications/common/setup-push-service.mdx b/src/fragments/lib/push-notifications/common/setup-push-service.mdx index fabe16d1c03..61d778e1e36 100644 --- a/src/fragments/lib/push-notifications/common/setup-push-service.mdx +++ b/src/fragments/lib/push-notifications/common/setup-push-service.mdx @@ -1,7 +1,15 @@ -import android0 from "/src/fragments/lib/push-notifications/android/setup_push_service/setup-fcm.mdx"; +import androidSetupService from '/src/fragments/lib/push-notifications/android/setup_push_service/setup-fcm.mdx'; +import iosSetupService from '/src/fragments/lib/push-notifications/ios/setup_push_service/setup-apns.mdx'; +import reactNativeSetupService from '/src/fragments/lib/push-notifications/react-native/setup_push_service/setup-push-service.mdx'; - + -import ios1 from "/src/fragments/lib/push-notifications/ios/setup_push_service/setup-apns.mdx"; +import androidHandlingActions from '/src/fragments/lib/push-notifications/android/setup_push_service/handling-actions.mdx'; - + diff --git a/src/fragments/lib/push-notifications/ios/getting_started/10_pre_req.mdx b/src/fragments/lib/push-notifications/ios/getting_started/10_pre_req.mdx index 56633ec45e8..33b380fb826 100644 --- a/src/fragments/lib/push-notifications/ios/getting_started/10_pre_req.mdx +++ b/src/fragments/lib/push-notifications/ios/getting_started/10_pre_req.mdx @@ -1,11 +1,7 @@ -import ios0 from "/src/fragments/lib/ios-prereq-category.mdx"; +import ios0 from '/src/fragments/lib/ios-prereq-category.mdx'; - + -Push Notifications are delivered via the Apple Push Notification service (APNs). In order to use APNs, you need to setup credentials (keys or certificates) and export your credentials to a p12 file. See [Setting up push notification services](/lib/push-notifications/setup-push-service) for more information. +import apnsPreReq from '/src/fragments/lib/push-notifications/ios/getting_started/apns-pre-req.mdx'; - - -Testing with APNs on the iOS simulator requires an Apple Silicon Mac running macOS 13+, Xcode 14+, and iOS simulator 16+. If your development environment does not meet all these requirements, then you must run on a real device to get an APNs token. - - \ No newline at end of file + diff --git a/src/fragments/lib/push-notifications/ios/getting_started/20_set_entitlements.mdx b/src/fragments/lib/push-notifications/ios/getting_started/20_set_entitlements.mdx index 9bffb8e44f3..e9eb773cf1e 100644 --- a/src/fragments/lib/push-notifications/ios/getting_started/20_set_entitlements.mdx +++ b/src/fragments/lib/push-notifications/ios/getting_started/20_set_entitlements.mdx @@ -10,31 +10,9 @@ To add these capabilities: -1. Open your Xcode project, go to project settings, select your main application target, select the **Signing and Capabilities** tab, and click **+ Capability** in the upper left corner of the editor pane to bring up the Capabilities dialog. - -![Add capability](/images/push-notifications/xcode-entitlements/01_add-capability.png) - - - -Xcode can be a little finicky with this step. If the Capabilities dialog is empty, try switching to a different tab and then switching back to **Signing and Capabilities** - - - -2. Type **push** in the filter box and double-click **Push Notifications** to add the capability. - -![Add push](/images/push-notifications/xcode-entitlements/02_add-push.png) - -3. Repeat step 1 to open the Capabilities dialog and then type **back** in the filter box and double-click **Background Modes** to add the capability. - -![Add background](/images/push-notifications/xcode-entitlements/03_add-background.png) - -4. Select **Change All** when prompted. - -5. Under **Background Modes**, select **Remote Notifications** - -![Remote notifications](/images/push-notifications/xcode-entitlements/04_background-remote-notifications.png) +import iosSetEntitlements from '/src/fragments/lib/push-notifications/ios/getting_started/ios-set-entitlements.mdx'; -6. Select **Change All** again when prompted. + diff --git a/src/fragments/lib/push-notifications/ios/getting_started/40_cli_resources.mdx b/src/fragments/lib/push-notifications/ios/getting_started/40_cli_resources.mdx index 36bd99cdea0..c58df3c847f 100644 --- a/src/fragments/lib/push-notifications/ios/getting_started/40_cli_resources.mdx +++ b/src/fragments/lib/push-notifications/ios/getting_started/40_cli_resources.mdx @@ -1,42 +1,5 @@ -> Prerequisite: [Install and configure the Amplify CLI](/cli/start/install) +import apnsCliResources from '/src/fragments/lib/push-notifications/ios/getting_started/apns-cli-resources.mdx'; - - -Push Notifications requires version **10.8.0+** of the Amplify CLI. You can check your current version by typing `amplify -version` and upgrade to the latest version by typing `amplify upgrade`. - - - -To start provisioning push notifications resources in the backend, go to your project directory and execute the command: - -```sh -amplify add notifications -``` - -Choose *APNS* when promoted: - -```console -? Choose the push notification channel to enable. -❯ APNS |  Apple Push Notifications - FCM | » Firebase Push Notifications - In-App Messaging - Email - SMS -``` - -Choose *Certificate* when promoted: - -```console -? Choose authentication method used for APNs -> Certificate -Key -``` - -The CLI will prompt for your *p12 certificate path*, enter it respectively. - -Once all your configuration is complete run the following: - -```sh -amplify push -``` + Upon completion, `amplifyconfiguration.json` will be updated to reference the newly provisioned backend push notifications resources. Note that this file should already be generated for you by the Amplify CLI as a part of your project if you followed the [project setup walkthrough](/lib/project-setup/prereq). diff --git a/src/fragments/lib/push-notifications/ios/getting_started/apns-cli-resources.mdx b/src/fragments/lib/push-notifications/ios/getting_started/apns-cli-resources.mdx new file mode 100644 index 00000000000..0d7e702b7be --- /dev/null +++ b/src/fragments/lib/push-notifications/ios/getting_started/apns-cli-resources.mdx @@ -0,0 +1,26 @@ +Choose _APNS_ when promoted: + +```console +? Choose the push notification channel to enable. +❯ APNS |  Apple Push Notifications + FCM | » Firebase Push Notifications + In-App Messaging + Email + SMS +``` + +Choose _Certificate_ when promoted: + +```console +? Choose authentication method used for APNs +> Certificate +Key +``` + +The CLI will prompt for your _p12 certificate path_, enter it respectively. + +Once all your configuration is complete run the following: + +```sh +amplify push +``` diff --git a/src/fragments/lib/push-notifications/ios/getting_started/apns-pre-req.mdx b/src/fragments/lib/push-notifications/ios/getting_started/apns-pre-req.mdx new file mode 100644 index 00000000000..16b2c22b100 --- /dev/null +++ b/src/fragments/lib/push-notifications/ios/getting_started/apns-pre-req.mdx @@ -0,0 +1,7 @@ +Push Notifications are delivered via the Apple Push Notification service (APNs). In order to use APNs, you need to setup credentials (keys or certificates) and export your credentials to a p12 file. See [Setting up push notification services](/lib/push-notifications/setup-push-service) for more information. + + + +Testing with APNs on the iOS simulator requires an Apple Silicon Mac running macOS 13+, Xcode 14+, and iOS simulator 16+. If your development environment does not meet all these requirements, then you must run on a real device to get an APNs token. + + diff --git a/src/fragments/lib/push-notifications/ios/getting_started/ios-set-entitlements.mdx b/src/fragments/lib/push-notifications/ios/getting_started/ios-set-entitlements.mdx new file mode 100644 index 00000000000..f084835a1f8 --- /dev/null +++ b/src/fragments/lib/push-notifications/ios/getting_started/ios-set-entitlements.mdx @@ -0,0 +1,25 @@ +1. Open your Xcode project, go to project settings, select your main application target, select the **Signing and Capabilities** tab, and click **+ Capability** in the upper left corner of the editor pane to bring up the Capabilities dialog. + +![Add capability](/images/push-notifications/xcode-entitlements/01_add-capability.png) + + + +Xcode can be a little finicky with this step. If the Capabilities dialog is empty, try switching to a different tab and then switching back to **Signing and Capabilities** + + + +2. Type **push** in the filter box and double-click **Push Notifications** to add the capability. + +![Add push](/images/push-notifications/xcode-entitlements/02_add-push.png) + +3. Repeat step 1 to open the Capabilities dialog and then type **back** in the filter box and double-click **Background Modes** to add the capability. + +![Add background](/images/push-notifications/xcode-entitlements/03_add-background.png) + +4. Select **Change All** when prompted. + +5. Under **Background Modes**, select **Remote Notifications** + +![Remote notifications](/images/push-notifications/xcode-entitlements/04_background-remote-notifications.png) + +6. Select **Change All** again when prompted. diff --git a/src/fragments/lib/push-notifications/ios/identify_user/10_get_auth_user.mdx b/src/fragments/lib/push-notifications/ios/identify_user/10_get_auth_user.mdx index ef2a11a9405..023ed40ce07 100644 --- a/src/fragments/lib/push-notifications/ios/identify_user/10_get_auth_user.mdx +++ b/src/fragments/lib/push-notifications/ios/identify_user/10_get_auth_user.mdx @@ -1,3 +1,5 @@ +If the user is signed in through [Amplify.Auth.signIn](/lib/auth/signin), then you can retrieve the current user's ID as shown below: + ```swift let user = try await Amplify.Auth.getCurrentUser().userId ``` diff --git a/src/fragments/lib/push-notifications/ios/identify_user/30_send_to_pinpoint_profile.mdx b/src/fragments/lib/push-notifications/ios/identify_user/30_send_to_pinpoint_profile.mdx index 9c22da9fee3..b0dde94a713 100644 --- a/src/fragments/lib/push-notifications/ios/identify_user/30_send_to_pinpoint_profile.mdx +++ b/src/fragments/lib/push-notifications/ios/identify_user/30_send_to_pinpoint_profile.mdx @@ -1,3 +1,5 @@ +Alternatively, you can provide additional information about the user by passing a user profile: + ```swift let userProfile = BasicUserProfile( name: "Name", diff --git a/src/fragments/lib/push-notifications/ios/setup_push_service/setup-apns.mdx b/src/fragments/lib/push-notifications/ios/setup_push_service/setup-apns.mdx index 74ffe692635..736b1302c22 100644 --- a/src/fragments/lib/push-notifications/ios/setup_push_service/setup-apns.mdx +++ b/src/fragments/lib/push-notifications/ios/setup_push_service/setup-apns.mdx @@ -6,27 +6,27 @@ This section describes how to use the Apple Developer portal to obtain iOS and A After completing the steps in this section, you will have the following items in your Apple Developer account: -* An app ID. -* An SSL certificate, which authorizes you to send push notifications to your app through APNs. -* A registration for your test device, such as an iPhone, with your Apple Developer account. -* An iOS distribution certificate, which enables you to install your app on your test device. -* A provisioning profile, which allows your app to run on your test device. +- An app ID. +- An SSL certificate, which authorizes you to send push notifications to your app through APNs. +- A registration for your test device, such as an iPhone, with your Apple Developer account. +- An iOS distribution certificate, which enables you to install your app on your test device. +- A provisioning profile, which allows your app to run on your test device. Before you begin, you must have an account with the Apple Developer Program as an individual or as part of an organization, and you must have agent or admin privileges in that account. **Topics** -* [Step 1: Create an App ID](#step-1-create-an-app-id) -* [Step 2: Create an APNs SSL Certificate](#step-2-create-an-apns-ssl-certificate) -* [Step 3: Register a Test Device](#step-3-register-a-test-device) -* [Step 4: Create an iOS Distribution Certificate](#step-4-create-an-ios-distribution-certificate) -* [Step 5: Create a Provisioning Profile](#step-5-create-a-provisioning-profile) +- [Step 1: Create an App ID](#step-1-create-an-app-id) +- [Step 2: Create an APNs SSL Certificate](#step-2-create-an-apns-ssl-certificate) +- [Step 3: Register a Test Device](#step-3-register-a-test-device) +- [Step 4: Create an iOS Distribution Certificate](#step-4-create-an-ios-distribution-certificate) +- [Step 5: Create a Provisioning Profile](#step-5-create-a-provisioning-profile) ### Step 1: Create an App ID Create an app ID to identify your app in the Apple Developer portal. You need this ID when you create an SSL certificate for sending push notifications, when you create an iOS distribution certificate, and when you create a provisioning profile. -If you already have an ID assigned to your app, you can skip this step. You can use an existing app ID provided it doesn't contain a wildcard character ("*"). +If you already have an ID assigned to your app, you can skip this step. You can use an existing app ID provided it doesn't contain a wildcard character ("\*"). **To assign an App ID to your app** @@ -55,15 +55,15 @@ If you already have an SSL certificate for your app, you can skip this step. - Choose **Edit**. - Under **Push Notifications**, in the **Production SSL Certificate** section, choose **Create Certificate...**. - In the **About Creating a Certificate Signing Request (CSR)** pane, follow the instructions for creating a Certificate Signing Request (CSR) file. You use the Keychain Access application on your Mac to create the request and save it on your local disk. When you are done, choose **Continue**. -- In the **Generate your certificate** pane, choose Choose **File...**, and then select the CSR file you created and Choose Continue. --When the certificate is ready, choose **Download** to save the certificate to your computer. +- In the **Generate your certificate** pane, choose Choose **File...**, and then select the CSR file you created and Choose Continue. +- When the certificate is ready, choose **Download** to save the certificate to your computer. - Double-click the downloaded certificate to install it to the Keychain on your Mac. - On your Mac, start the Keychain Access application. - In **My Certificates**, find the certificate you just added. The certificate is named "Apple Push Services:`com.my.app.id`", where `com.my.app.id` is the app ID for which the certificate was created. - Context-select the push certificate and then select **Export...** from the context menu to export a file containing the certificate. - Type a name for the certificate that is easy to recognize and save it to your computer. Do not provide an export password when prompted. You need to upload this certificate when creating your app in AWS Mobile Hub. -[Back to top](#setting-up-ios-push-notifications) +[Back to top](#setting-up-apns-for-push-notifications) ### Step 3: Register a Test Device @@ -79,17 +79,17 @@ If you already have a registered device, you can skip this step. - In the **Register Device** section, for **Name**, type a name that is easy to recognize later. - For **UDID**, type the unique device ID. For an iPhone, you can find the UDID by completing the following steps: - - Connect your iPhone to your Mac with a USB cable. - - Open the iTunes app. - - In the top left corner of the iTunes window, a button with an iPhone icon is shown. Choose this button. iTunes displays the summary page for your iPhone. - - In the top box, the summary page provides your iPhone's **Capacity**, **Phone Number**, and **Serial Number**. Click **Serial Number**, and the value changes to **UDID**. - - Context-select your UDID, and choose **Copy**. - - Paste your UDID into the **UDID** field in the Apple Developer website. - - Choose **Continue**. + - Connect your iPhone to your Mac with a USB cable. + - Open the iTunes app. + - In the top left corner of the iTunes window, a button with an iPhone icon is shown. Choose this button. iTunes displays the summary page for your iPhone. + - In the top box, the summary page provides your iPhone's **Capacity**, **Phone Number**, and **Serial Number**. Click **Serial Number**, and the value changes to **UDID**. + - Context-select your UDID, and choose **Copy**. + - Paste your UDID into the **UDID** field in the Apple Developer website. + - Choose **Continue**. - On the **Review and register** pane, verify the details for your device, and choose **Register**. Your device name and identifier are added to the list of devices. -[Back to top](#setting-up-ios-push-notifications) +[Back to top](#setting-up-apns-for-push-notifications) ### Step 4: Create an iOS Distribution Certificate @@ -109,7 +109,7 @@ If you already have an iOS distribution certificate, you can skip this step. - When the certificate is ready, choose **Download** to save the certificate to your computer. - Double-click the downloaded certificate to install it in Keychain on your Mac. -[Back to top](#setting-up-ios-push-notifications) +[Back to top](#setting-up-apns-for-push-notifications) ### Step 5: Create a Provisioning Profile @@ -129,9 +129,9 @@ A provisioning profile allows your app to run on your test device. You create an - Install the provisioning profile by double-clicking the downloaded file. The Xcode app opens in response. - To verify that the provisioning profile is installed, check the list of installed provisioning profiles in Xcode by doing the following: - - In the Xcode menu bar, choose **Xcode** and then choose **Preferences**. - - In the preferences window, choose **Accounts**. - - In the **Accounts** tab, select your Apple ID, and then choose **View Details**. - - Check that your provisioning profile is listed in the **Provisioning Profiles** section. + - In the Xcode menu bar, choose **Xcode** and then choose **Preferences**. + - In the preferences window, choose **Accounts**. + - In the **Accounts** tab, select your Apple ID, and then choose **View Details**. + - Check that your provisioning profile is listed in the **Provisioning Profiles** section. -[Back to top](#setting-up-ios-push-notifications) +[Back to top](#setting-up-apns-for-push-notifications) diff --git a/src/fragments/lib/push-notifications/js/getting-started.mdx b/src/fragments/lib/push-notifications/js/getting-started.mdx deleted file mode 100644 index ad46479186c..00000000000 --- a/src/fragments/lib/push-notifications/js/getting-started.mdx +++ /dev/null @@ -1,219 +0,0 @@ -Setup instructions are provided for Android and iOS, and configuration for both platforms can be included on the same React Native project. - -## Requirements -1. In order to use Amazon Pinpoint you need to setup credentials (keys or certificates) for your targeted mobile platform, e.g. Android and/or iOS. -2. Testing Push Notifications requires a physical device, because simulators or emulators won't be able to handle push notifications. -3. Push Notifications category is integrated with [AWS Amplify Analytics category](/lib/analytics/getting-started) to be able to track notifications. Make sure that you have configured the Analytics category in your app before configuring the Push Notifications category. - -## Setup for Android - -1. Make sure you have a [Firebase Project](https://console.firebase.google.com) and app setup. - -2. Get your push messaging credentials for Android in Firebase console. [Click here for instructions](/sdk/push-notifications/setup-push-service). - -3. Install dependencies: - - ```bash - npm install aws-amplify @aws-amplify/pushnotification - ``` - -4. Add your push messaging credentials (Server key) with Amplify CLI by using the following commands: - - ```bash - amplify add notifications - ``` - - Choose *FCM* when promoted: - - ```console - ? Choose the push notification channel to enable. - APNS - ❯ FCM - Email - SMS - ``` - - The CLI will prompt for your *Firebase credentials*, enter them respectively. - - - You can find said *Firebase credentials* by visiting https://console.firebase.google.com/project/[your-project-id]/settings/cloudmessaging or by navigating to (gear-next-to-project-name) > Project Settings > Cloud Messaging on the Firebase Console. - - Alternatively, you can set up Android push notifications in Amazon Pinpoint Console. [Click here for instructions](https://docs.aws.amazon.com/pinpoint/latest/developerguide/mobile-push-android.html). - -5. Enable your app in Firebase. To do that, follow those steps: - - - If you don't have an existing Firebase project, you need to create one in order to continue. - - - * Visit the [Firebase console](https://console.firebase.google.com), and click the Gear icon next to **Project Overview** and click **Project Settings**. - * Click **Add App**, if you have an existing app you can skip this step - * Choose **Add Firebase to your Android App** - * Add your package name i.e. **com.myProjectName** and click **Register App** - * Download *google-services.json* file and copy it under your `android/app` project folder. - - - - Make sure you have *google-services.json* file in place or you won't pass the build process. - - - -6. Open *android/build.gradle* file and perform following edits: - - - Add `classpath("com.google.gms:google-services:4.3.3")` in the `dependencies` under `buildscript`: - - ```gradle - buildscript { - ... - dependencies { - ... - classpath("com.google.gms:google-services:4.3.3") - ... - } - } - ``` - -7. Open *android/app/build.gradle* and perform following edits: - - - Add firebase libs to the `dependencies` section: - - ```gradle - dependencies { - ... - implementation "com.google.firebase:firebase-core:15.0.2" - implementation "com.google.firebase:firebase-messaging:15.0.2" - ... - } - ``` - - Add following configuration to the bottom of the file: - - ```gradle - apply plugin: "com.google.gms.google-services" - ``` - -8. Open *android/app/src/main/AndroidManifest.xml* file and add the following configuration into `application` element. - - ```xml - - - - - - - - - - - - ``` - -9. Configure Push Notifications category for your app as shown in [Configure your App](#configure-your-app) section. - -10. Run your app: - - ```bash - npx react-native run-android - ``` - -## Setup for iOS - -1. For setting up iOS push notifications, you need to download and install Xcode from [Apple Developer Center](https://developer.apple.com/xcode/). - -2. Setup iOS Push Notifications and create a p12 certificate as instructed here in [Amazon Pinpoint Developer Guide](https://docs.aws.amazon.com/pinpoint/latest/developerguide/apns-setup.html). - -3. Install dependencies and CocoaPods: - - ```bash - npm install aws-amplify @aws-amplify/pushnotification @react-native-community/push-notification-ios - ``` - ```bash - npx pod-install - ``` - -4. Enable notifications and add your p12 certificate with Amplify CLI by using the following commands: - - ```bash - amplify add notifications - ``` - - Choose *APNS* when promoted: - - ```console - ? Choose the push notification channel to enable. - > APNS - FCM - Email - SMS - ``` - - Choose *Certificate* when promoted: - - ```console - ? Choose authentication method used for APNs - > Certificate - Key - ``` - - The CLI will prompt for your *p12 certificate path*, enter it respectively. - -5. Open project in Xcode and make updates for `@react-native-community/push-notification-ios`: - - [Add Capabilities : Background Mode - Remote Notifications](https://github.com/react-native-community/push-notification-ios#add-capabilities--background-mode---remote-notifications) - - [Augment `AppDelegate`](https://github.com/react-native-community/push-notification-ios#augment-appdelegate) - -6. Update General App settings: - - - Set bundle identifier (with the one you create on your Apple Developer Account) - - Make sure you have logged in with your Apple Developer account on Xcode and have a Team selected for the target. - -7. Configure Push Notification module for your app as shown in [Configure your App](#configure-your-app) section. - -8. Run your app: - - ```bash - npx react-native run-ios --device - ``` - -## Configure your App - -The Push Notifications category is integrated with `Analytics` module to be able to track notifications. Make sure that you have configured the Analytics module in your app before configuring Push Notification module. - - - -If you don't have Analytics already enabled, see our [Analytics Developer Guide](/lib/analytics/getting-started) to add Analytics to your app. - - - -```javascript -import { Amplify } from 'aws-amplify'; -import { PushNotification } from '@aws-amplify/pushnotification'; -import PushNotificationIOS from '@react-native-community/push-notification-ios'; -import awsconfig from './aws-exports'; - -Amplify.configure(awsconfig); -``` - -### Configuration Options - -- `requestIOSPermissions` is an optional boolean flag which specifies whether or not to automatically request push notifications permissions in iOS when calling `PushNotification.configure` for the first time. If not provided, it defaults to `true`. When set to `false`, you may later call the method `PushNotification.requestIOSPermissions` at the explicit point in your application flow when you want to prompt the user for permissions. -- `appId` is optional and *only* needed if `aws-exports` doesn't contain `aws_mobile_analytics_app_id` or you are manually configuring each category inside `Amplify.configure()`. - -```javascript -Amplify.configure({ - ...awsconfig, - PushNotification: { - requestIOSPermissions: false - } -}); -``` -```javascript -Amplify.configure({ - Auth: { /* ... */ }, - Analytics: { /* ... */ }, - PushNotification: { - appId: 'XXXXXXXXXXabcdefghij1234567890ab', - requestIOSPermissions: false - } -}); -``` diff --git a/src/fragments/lib/push-notifications/js/overview.mdx b/src/fragments/lib/push-notifications/js/overview.mdx deleted file mode 100644 index 95bdc1c0f6d..00000000000 --- a/src/fragments/lib/push-notifications/js/overview.mdx +++ /dev/null @@ -1,6 +0,0 @@ -The Push Notifications category allows you to integrate push notifications in your app with Amazon Pinpoint targeting, campaign, and journey management support. - -This guide provides step-by-step instructions to start working with push notifications in React Native with Amazon Pinpoint. Amazon Pinpoint helps you to monitor your app's usage, create messaging campaigns and journeys targeted to specific user segments or demographics, and collect interaction metrics with push notifications. - -> Ensure you have [installed and configured the Amplify CLI and library](/cli/start/install). - diff --git a/src/fragments/lib/push-notifications/js/testing.mdx b/src/fragments/lib/push-notifications/js/testing.mdx deleted file mode 100644 index 0968d594ed0..00000000000 --- a/src/fragments/lib/push-notifications/js/testing.mdx +++ /dev/null @@ -1 +0,0 @@ -You can create messaging campaigns and send push notifications to your app with Amazon Pinpoint! Just follow these instructions on [Amazon Pinpoint Developer Guide](https://docs.aws.amazon.com/pinpoint/latest/developerguide/getting-started-sampletest.html) for the next steps. \ No newline at end of file diff --git a/src/fragments/lib/push-notifications/js/working-with-api.mdx b/src/fragments/lib/push-notifications/js/working-with-api.mdx deleted file mode 100644 index d56bc7c4d80..00000000000 --- a/src/fragments/lib/push-notifications/js/working-with-api.mdx +++ /dev/null @@ -1,43 +0,0 @@ -You can use `onNotification`, `onRegister` and `onNotificationOpened` event handlers to work with push notifications in your app: - -```javascript -// get the notification data when notification is received -PushNotification.onNotification((notification) => { - // Note that the notification object structure is different from Android and IOS - console.log('in app notification', notification); - - // required on iOS only (see fetchCompletionHandler docs: https://github.com/react-native-community/push-notification-ios#finish) - notification.finish(PushNotificationIOS.FetchResult.NoData); -}); - -// get the registration token -// This will only be triggered when the token is generated or updated. -PushNotification.onRegister((token) => { - console.log('in app registration', token); -}); - -// get the notification data when notification is opened -PushNotification.onNotificationOpened((notification) => { - console.log('the notification is opened', notification); -}); -``` - - - -The `onRegister` handler will only be triggered once when the token is generated or updated by the push provider i.e. Apple/Google (and when the app opened the first time). - - - -If you have configured your application not to automatically request iOS push notification permissions, you can use the `requestIOSPermissions` method to request them explicitly: - -```javascript -// request iOS push notification permissions -PushNotification.requestIOSPermissions(); - -// request a subset of iOS push notification permissions -PushNotification.requestIOSPermissions({ - alert: true, - badge: true, - sound: false, -}); -``` \ No newline at end of file diff --git a/src/fragments/lib/push-notifications/react-native/app_badge_count/app-badge-count.mdx b/src/fragments/lib/push-notifications/react-native/app_badge_count/app-badge-count.mdx new file mode 100644 index 00000000000..286ef5a1dc1 --- /dev/null +++ b/src/fragments/lib/push-notifications/react-native/app_badge_count/app-badge-count.mdx @@ -0,0 +1,22 @@ +The app badge count, when set, can be seen on your app's icon on a user's device. Amplify provides you with simple helpers to manipulate this number. + + + App badge count helpers are safe to call even when your app is running on + Android but will be ignored. + + +## Get the current badge count + +Use `getBadgeCount` to get the current app badge count. You might need to do this to calculate the value when setting the badge count. + +```js +const count = await Notifications.Push.getBadgeCount(); +``` + +## Update the badge count + +Use `setBadgeCount` to set the current app badge count. Setting the badge count to `0` (zero) will remove the badge from your app's icon. + +```js +Notifications.Push.setBadgeCount(42); +``` diff --git a/src/fragments/lib/push-notifications/react-native/enable_rich_notifications/enable-rich-notifications.mdx b/src/fragments/lib/push-notifications/react-native/enable_rich_notifications/enable-rich-notifications.mdx new file mode 100644 index 00000000000..fc1c5b444f8 --- /dev/null +++ b/src/fragments/lib/push-notifications/react-native/enable_rich_notifications/enable-rich-notifications.mdx @@ -0,0 +1,50 @@ + + On Android, Amplify Push Notifications should already be configured to handle + rich content for you. + + +Amplify currently supports adding images to your notifications, but there are some additional steps required. + +## Create a Notification Service Extension + +1. Open `.xcworkspace` located inside the `/ios` folder of your React Native project with Xcode. + +2. In the Xcode project, select **File > New > Target...** + +![New target](/images/push-notifications/cross-platform-service-extension/01_new-target.png) + +3. Select **Notification Service Extension > Next**. + +![Target type](/images/push-notifications/cross-platform-service-extension/02_target-type.png) + +4. Enter a name for your service extension (e.g. MyNotificationServiceExtension) and select **Finish**. + +![Target name](/images/push-notifications/cross-platform-service-extension/03_target-name.png) + +## Provide the extension with the Amplify service class + +1. Open `Podfile` located inside the `/ios` folder of your React Native project with a text editor. + +2. Add `AmplifyUtilsNotifications` to the extension you created above. + +```ruby +target 'MyNotificationServiceExtension' do # Replace with your service extension + pod "AmplifyUtilsNotifications" +end +``` + +3. Install the new pods by running the following command at the root of your React Native project. + +```bash +npx pod-install +``` + +4. Open `.xcworkspace` located inside the `/ios` folder of your React Native project with Xcode. + +5. Find your extension folder in the Project navigator pane and select the **Info** Property List. + +![Extension info](/images/push-notifications/cross-platform-service-extension/04_extension-info.png) + +6. Update the `NSExtensionPrincipalClass` property with the value `AmplifyUtilsNotifications.AUNotificationService`. + +![Extension class](/images/push-notifications/cross-platform-service-extension/05_extension-class.png) diff --git a/src/fragments/lib/push-notifications/react-native/getting_started/10_pre_req.mdx b/src/fragments/lib/push-notifications/react-native/getting_started/10_pre_req.mdx new file mode 100644 index 00000000000..440f9830da1 --- /dev/null +++ b/src/fragments/lib/push-notifications/react-native/getting_started/10_pre_req.mdx @@ -0,0 +1,35 @@ +You should have [completed the CLI and project setup steps.](/lib/project-setup/prereq) + + + + +A React Native application with a minimum target of iOS 13.0, using Xcode 13.4 or later. + +import apnsPreReq from '/src/fragments/lib/push-notifications/ios/getting_started/apns-pre-req.mdx'; + + + +### Set Entitlements + +Using Amplify Push Notifications with APNs requires the following capabilities: + +- Push Notifications +- Background Processing -> Remote Notifications + +To add these capabilities: + +import iosSetEntitlements from '/src/fragments/lib/push-notifications/ios/getting_started/ios-set-entitlements.mdx'; + + + + + + +A React Native application targeting at least Android SDK API level 24. + +import fcmPreReq from '/src/fragments/lib/push-notifications/android/getting_started/fcm-pre-req.mdx'; + + + + + diff --git a/src/fragments/lib/push-notifications/react-native/getting_started/20_cli_resources.mdx b/src/fragments/lib/push-notifications/react-native/getting_started/20_cli_resources.mdx new file mode 100644 index 00000000000..39c92225e16 --- /dev/null +++ b/src/fragments/lib/push-notifications/react-native/getting_started/20_cli_resources.mdx @@ -0,0 +1,20 @@ + + + +import apnsCliResources from '/src/fragments/lib/push-notifications/ios/getting_started/apns-cli-resources.mdx'; + + + +Upon completion, `aws-exports.js` will be updated to reference the newly provisioned backend push notifications resources. Note that this file should already be generated for you by the Amplify CLI as a part of your project if you followed the [project setup walkthrough](/lib/project-setup/prereq). + + + + +import fcmCliResources from '/src/fragments/lib/push-notifications/android/getting_started/fcm-cli-resources.mdx'; + + + +Upon completion, `aws-exports.js` will be updated to reference the newly provisioned backend push notifications resources. Note that this file should already be generated for you by the Amplify CLI as a part of your project if you followed the [project setup walkthrough](/lib/project-setup/prereq). + + + diff --git a/src/fragments/lib/push-notifications/react-native/getting_started/30_existing_resources.mdx b/src/fragments/lib/push-notifications/react-native/getting_started/30_existing_resources.mdx new file mode 100644 index 00000000000..c31eb7c3e8c --- /dev/null +++ b/src/fragments/lib/push-notifications/react-native/getting_started/30_existing_resources.mdx @@ -0,0 +1,17 @@ +Existing Amazon Pinpoint resources can be used with Amplify Push Notifications by configuring it with **Application ID** and **Region**. + +```js +Amplify.configure({ + Notifications: { + Push: { + AWSPinpoint: { + appId: '', + region: '' + } + } + } +}); +``` + +- **appId**: Amazon Pinpoint application ID +- **region**: AWS Region where the resources are provisioned (e.g. `us-east-1`) diff --git a/src/fragments/lib/push-notifications/react-native/getting_started/40_install_lib.mdx b/src/fragments/lib/push-notifications/react-native/getting_started/40_install_lib.mdx new file mode 100644 index 00000000000..8c95874208e --- /dev/null +++ b/src/fragments/lib/push-notifications/react-native/getting_started/40_install_lib.mdx @@ -0,0 +1,14 @@ +In your application directory, you should first install the necessary dependencies for using Amplify Push Notifications. + +```bash +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 +``` + +You will also need to add the crypto.getRandomValues and URL polyfills to your application's entry point file (in most React Native apps this will be the top level `index.js`). + +```js +// Example index.js +import 'react-native-get-random-values'; +import 'react-native-url-polyfill/auto'; +... +``` diff --git a/src/fragments/lib/push-notifications/react-native/getting_started/50_integrate_native_modules.mdx b/src/fragments/lib/push-notifications/react-native/getting_started/50_integrate_native_modules.mdx new file mode 100644 index 00000000000..3db4fac5b55 --- /dev/null +++ b/src/fragments/lib/push-notifications/react-native/getting_started/50_integrate_native_modules.mdx @@ -0,0 +1,41 @@ +## Integrate native modules + + + On Android, there should be no additional integration steps after the + prerequisites above have been completed. + + +Since push notifications require interaction with the native platform, there are some additional steps required to integrate your React Native app with the Amplify Push Notifications native module. + +### Link the module + +You should have already installed the native module in an earlier step, now you need to link it. In your React Native app's root directory run the following command. + +```bash +npx pod-install +``` + +### Update your Application Delegate + +Locate and open your `AppDelegate.m` or `AppDelegate.mm` file in your text editor. You should find it in your React Native project under `/ios/` + +At the top of your `AppDelegate`, import Amplify Push Notifications: + +```objective-c +#import "AppDelegate.h" +#import "AmplifyPushNotification.h" + +... +``` + +In the body of your `AppDelegate`, add the following two methods: + +```objective-c +- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken { + [AmplifyPushNotification didRegisterForRemoteNotificationsWithDeviceToken:deviceToken]; +} + +- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult result))completionHandler { + [AmplifyPushNotification didReceiveRemoteNotification:userInfo withCompletionHandler:completionHandler]; +} +``` diff --git a/src/fragments/lib/push-notifications/react-native/getting_started/60_init_push_notifications.mdx b/src/fragments/lib/push-notifications/react-native/getting_started/60_init_push_notifications.mdx new file mode 100644 index 00000000000..bcad043f57e --- /dev/null +++ b/src/fragments/lib/push-notifications/react-native/getting_started/60_init_push_notifications.mdx @@ -0,0 +1,41 @@ +To initialize the Amplify Push Notifications, you will first need to configure Amplify. + +Import and load the configuration file in your app. It's recommended you add the Amplify configuration step to your app's root entry point. For example, `index.js` + +```js +// Example index.js +... +import { Amplify, Notifications } from 'aws-amplify'; +import awsconfig from './src/aws-exports'; + +Amplify.configure(awsconfig); +... +``` + +Next, enable Amplify Push Notifications. You should do this in your app's root entry point after configuring Amplify as push notifications can occur even while your app is in a terminated state. + +```js +// Example index.js +... +Notifications.Push.enable(); +... +``` + +Your resulting entry file should look something like the following + +```js +import 'react-native-get-random-values'; +import 'react-native-url-polyfill/auto'; + +import { AppRegistry } from 'react-native'; +import App from './App'; +import { name as appName } from './app.json'; + +import { Amplify, Notifications } from 'aws-amplify'; +import awsconfig from './src/aws-exports'; + +Amplify.configure(awsconfig); +Notifications.Push.enable(); + +AppRegistry.registerComponent(appName, () => App); +``` diff --git a/src/fragments/lib/push-notifications/react-native/identify_user/10_get_auth_user.mdx b/src/fragments/lib/push-notifications/react-native/identify_user/10_get_auth_user.mdx new file mode 100644 index 00000000000..00aaa127395 --- /dev/null +++ b/src/fragments/lib/push-notifications/react-native/identify_user/10_get_auth_user.mdx @@ -0,0 +1,8 @@ +If the user is signed in through [Auth.signIn](/lib/auth/emailpassword#sign-in), then you can retrieve the current user's ID as shown below: + +```js +const user = await Auth.currentAuthenticatedUser(); + +// sub is a unique identifier of the authenticated user +const userId = user.attributes.sub; +``` diff --git a/src/fragments/lib/push-notifications/react-native/identify_user/20_send_to_pinpoint.mdx b/src/fragments/lib/push-notifications/react-native/identify_user/20_send_to_pinpoint.mdx new file mode 100644 index 00000000000..f8d87ab6773 --- /dev/null +++ b/src/fragments/lib/push-notifications/react-native/identify_user/20_send_to_pinpoint.mdx @@ -0,0 +1,9 @@ +```js +const userInfo = { + attributes: { + hobbies: ['cooking', 'knitting'] + } +}; + +await Notifications.Push.identifyUser(userId, userInfo); +``` diff --git a/src/fragments/lib/push-notifications/react-native/interact_with_notifications/interact-with-notifications.mdx b/src/fragments/lib/push-notifications/react-native/interact_with_notifications/interact-with-notifications.mdx new file mode 100644 index 00000000000..ad51eae98d6 --- /dev/null +++ b/src/fragments/lib/push-notifications/react-native/interact_with_notifications/interact-with-notifications.mdx @@ -0,0 +1,17 @@ +Push notifications are powerful engagement tools for your users as they can be delivered even when your app is not in the active foreground. As a result, there are many cases where it is helpful (or perhaps necessary) to interact with notification events differently depending upon your app's state. + +- **Foreground state**: Your app is running, active and visible. +- **Background state**: Your app is still running but is not currently active and visible. The user is usually on the home screen or in another app. +- **Terminated state**: Your app is no longer running, even in the background. The user can initiate this by swiping your app away in the app switcher. + +import notificationLifecycle from '/src/fragments/lib/push-notifications/react-native/interact_with_notifications/notification-lifecycle.mdx'; + + + +import notificationReceived from '/src/fragments/lib/push-notifications/react-native/interact_with_notifications/notification-received.mdx'; + + + +import notificationOpened from '/src/fragments/lib/push-notifications/react-native/interact_with_notifications/notification-opened.mdx'; + + diff --git a/src/fragments/lib/push-notifications/react-native/interact_with_notifications/notification-lifecycle.mdx b/src/fragments/lib/push-notifications/react-native/interact_with_notifications/notification-lifecycle.mdx new file mode 100644 index 00000000000..d5df5e44b54 --- /dev/null +++ b/src/fragments/lib/push-notifications/react-native/interact_with_notifications/notification-lifecycle.mdx @@ -0,0 +1,30 @@ +## Notification lifecycle + +Before delving into details about the various functions Amplify provides, it can be helpful to better understand the lifecycle of a notification as it moves through your app in its various states once you've integrated Amplify Push Notifications. + +For the purposes of this guide, we will simplify the terminology as follows + +- **Native layer** - This is the native (i.e. iOS or Android) application layer on top of which React Native apps are built. +- **Application layer** - This is your React Native app. + +### In a foreground state + +![Foreground state lifecycle](/images/push-notifications/cross-platform-lifecycle/pn-lifecycle-foreground.png) + +- Notifications are not displayed when received in foreground +- It is possible for notifications to arrive in your user's notification center but not be opened until a later time +- Since it is possible to interact with the notification center at any time on a device, your user could even open a notification while your app is in the active foreground + +### In a background state + +![Background state lifecycle](/images/push-notifications/cross-platform-lifecycle/pn-lifecycle-background.png) + +- _Notification A_ represents an example of a notification which was received but never interacted with +- Recall that, in a background state, your app is still running and therefore does not need to be launched — only brought back into the foreground + +### In a terminated state + +![Terminated state lifecycle](/images/push-notifications/cross-platform-lifecycle/pn-lifecycle-terminated.png) + +- _Notification A_ represents an example of a notification which was received but never interacted with +- Recall that, in a terminated state, your app is no longer running and therefore needs to be launched diff --git a/src/fragments/lib/push-notifications/react-native/interact_with_notifications/notification-opened.mdx b/src/fragments/lib/push-notifications/react-native/interact_with_notifications/notification-opened.mdx new file mode 100644 index 00000000000..c78c99bea3d --- /dev/null +++ b/src/fragments/lib/push-notifications/react-native/interact_with_notifications/notification-opened.mdx @@ -0,0 +1,42 @@ +## Respond to a notification being opened + +When a user taps on a notification displayed on their device, your app will be either launched or brought to the foreground. Knowing the contents of the notification the user interacted with can help you take further action (e.g. follow a deep link) or glean additional insight into your user engagement. + +To help you with this, Amplify provides two ways of handling notifications being opened. It is recommended that you handle both to ensure your users the most consistent and seamless experience. + +| App state | Handle with | +| :---------------------: | :---------------------: | +| Foreground / Background | `onNotificationOpened` | +| Terminated | `getLaunchNotification` | + +### onNotificationOpened + +Add `onNotificationOpened` listeners to respond to a push notification being opened while your app is in a foreground **or** background state. + +```js +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 +``` + +### getLaunchNotification + +When your app is launched from a terminated state, you must call `getLaunchNotification` to obtain the notification which launched your app. + +Calling `getLaunchNotification` _consumes_ the launch notification and will yield a `null` result if: + +- You called it more than once (i.e. subsequent calls will be `null`) +- Another notification was opened while your app was running (either in foreground or background) +- Your app was brought back to the foreground by some other means (e.g. user tapped the app icon) + +```js +const launchNotification = await Notifications.Push.getLaunchNotification(); + +... // Take further action with the `launchNotification` +``` diff --git a/src/fragments/lib/push-notifications/react-native/interact_with_notifications/notification-received.mdx b/src/fragments/lib/push-notifications/react-native/interact_with_notifications/notification-received.mdx new file mode 100644 index 00000000000..ed5bee921aa --- /dev/null +++ b/src/fragments/lib/push-notifications/react-native/interact_with_notifications/notification-received.mdx @@ -0,0 +1,59 @@ +## Respond to a notification being received + +Push notifications received by your users are useful engagement tools but they also provide a data delivery mechanism to your app! + +Your app will likely need to respond to notifications being received in different ways depending on its state, namely while it is either actively in the foreground (where your app may respond by updating UI) or not (where your app may respond by performing tasks to ensure your app experience is up to date). + +| App state | Handle with | +| :---------------------: | :----------------------------------: | +| Foreground | `onNotificationReceivedInForeground` | +| Background / Terminated | `onNotificationReceivedInBackground` | + +### Notification received in foreground + +Notifications received while your app is in the foreground state do not get displayed. But their contents may be useful for updating your app (e.g. updating the UI to reflect a new inbox message). + +Add `onNotificationReceivedInForeground` listeners to respond to a push notification being received while your app is in a foreground state. + +```js +const myNotificationReceivedHandler = (notification) => { + // Respond to the received push notification message in realtime +}; + +const listener = Notifications.Push.onNotificationReceivedInForeground( + myNotificationReceivedHandler +); + +listener.remove(); // Remember to remove the listener when it is no longer needed +``` + +### Notification received in background + +You may be able to improve your users' experience by having your app perform tasks in the background (e.g. fetching data) so they will have the most up-to-date experience when they next launch your app. + +Add `onNotificationReceivedInBackground` listeners to respond to a push notification being received while your app is in a background **or** terminated state. + +For background notifications to be handled while your app is terminated, it is important to note: + +1. You should add this listener to your app's root entry point, i.e. _before_ registering your app component because it will be run via React Native's [Headless JS](https://reactnative.dev/docs/headless-js-android) and your app will not mount/render. +2. Notifications received in a terminated state will be considered low priority by Android unless you increase the priority of the payload by setting the `priority` to `high` (you will need to create a _Raw Message_ in Amazon Pinpoint to set this priority). + +```js +// Example index.js +... +Amplify.configure(config); +Notifications.Push.enable(); + +// 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 +}; + +// 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 +); + +AppRegistry.registerComponent(appName, () => App); +``` diff --git a/src/fragments/lib/push-notifications/react-native/migrate_from_previous_version/migrate-from-previous-version.mdx b/src/fragments/lib/push-notifications/react-native/migrate_from_previous_version/migrate-from-previous-version.mdx new file mode 100644 index 00000000000..2c544ee35bb --- /dev/null +++ b/src/fragments/lib/push-notifications/react-native/migrate_from_previous_version/migrate-from-previous-version.mdx @@ -0,0 +1,170 @@ +If you were previously using the now deprecated version of Amplify Push Notifications for React Native (@aws-amplify/pushnotification), you will need to migrate to the new version by following the steps outlined here. + +## Update your configuration + +1. Make sure you are using the latest version of the Amplify CLI. + +```bash +amplify upgrade +``` + +2. Pull your project (even if there are no changes) to update your configuration. + +```bash +amplify pull +``` + +## Replace your dependency + +1. Remove the old dependency from your project. + +```bash +npm uninstall @aws-amplify/pushnotification +``` + +2. Add the new native module to your project. + +```bash +npm install @aws-amplify/rtn-push-notification +``` + +## Update build configurations + + + + +### Update your `Podfile` + +Amplify Push Notifications now requires a minimum target of iOS 13.0. + +1. Open `Podfile` located inside the `/ios` folder of your React Native project with a text editor. + +2. Update `platform :ios` to at least `13.0`. + +```ruby +platform :ios, '13.0' +``` + +3. Install the new pods by running the following command at the root of your React Native project. + +```bash +npx pod-install +``` + +### Update your Application Delegate + +1. Reverse the steps previously taken to [augment your `AppDelegate`](https://github.com/react-native-push-notification/ios#augment-appdelegate) + +2. Locate and open your `AppDelegate.m` or `AppDelegate.mm` file in your text editor. You should find it in your React Native project under `/ios/` + +3. At the top of your `AppDelegate`, import Amplify Push Notifications: + +```objective-c +#import "AppDelegate.h" +#import "AmplifyPushNotification.h" + +... +``` + +4. In the body of your `AppDelegate`, add the following two methods: + +```objective-c +- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken { + [AmplifyPushNotification didRegisterForRemoteNotificationsWithDeviceToken:deviceToken]; +} + +- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult result))completionHandler { + [AmplifyPushNotification didReceiveRemoteNotification:userInfo withCompletionHandler:completionHandler]; +} +``` + + + + +### Update gradle scripts + +Amplify Push Notifications now requires a minimum target of Android SDK API level 24. + +1. Open `build.gradle` located inside the `/android` folder of your React Native project with a text editor. + +2. Update the `minSdkVersion` value in the `buildscript` block to at least `24`. + +```groovy +buildscript { + ext { + ... + minSdkVersion = 24 + ... + } +} +``` + +3. Open the application `build.gradle` located inside the `/android/app` folder of your React Native project with a text editor. + +4. Remove firebase dependencies from the `dependencies` block. + +```diff +dependencies { + ... +- implementation "com.google.firebase:firebase-core:15.0.2" +- implementation "com.google.firebase:firebase-messaging:15.0.2" + ... +} +``` + +### Update the manifest + +5. Open `AndroidManifest.xml` located inside the `/android/app/src/main` folder. + +6. Remove the old service block from the `application`. + +```diff + + ... +- +- +- +- +- +- +- + ... + +``` + + + + +## Update your application code + +### Add required polyfills + +You need to add the crypto.getRandomValues and URL polyfills to your application's entry point file (in most React Native apps this will be the top level `index.js`). + +```js +// Example index.js +import 'react-native-get-random-values'; +import 'react-native-url-polyfill/auto'; +... +``` + +### Remove Analytics (Optional) + +If you **do not** use Amplify Analytics in your application but have previously imported it in your code just to implement Amplify Push Notifications, you should be able to remove it now. Analytics is no longer required to be configured in your frontend application to use Amplify Push Notifications. + +### Replace APIs + +Please refer to the [Getting started](/lib/push-notifications/getting-started) portion of this guide to start learning more about the new Amplify Push Notifications. + +A brief mapping of your APIs to their replacements is as follows: + +| Previous API | Replaced by | +| :---------------------: | :----------------------------------------------------------------------------: | +| `onRegister` | `onTokenReceived` | +| `onNotificationOpened` | `onNotificationOpened` | +| `onNotification` | `onNotificationReceivedInForeground`
`onNotificationReceivedInBackground` | +| `requestIOSPermissions` | `requestPermissions` | + +We _strongly_ recommend you take the time to explore all the ways the new version of Amplify Push Notifications are different and all the new features that have been added. This will help you to make the best decision about how to adopt these changes for your unique use cases. diff --git a/src/fragments/lib/push-notifications/react-native/receive_device_token/receive-device-token.mdx b/src/fragments/lib/push-notifications/react-native/receive_device_token/receive-device-token.mdx new file mode 100644 index 00000000000..4306662f232 --- /dev/null +++ b/src/fragments/lib/push-notifications/react-native/receive_device_token/receive-device-token.mdx @@ -0,0 +1,20 @@ +Push notifications are delivered to your user's devices through a device token which uniquely identifies your app. Although Amplify will automatically register this token with Amazon Pinpoint, it can still be useful to have access to this token for your app's use cases (e.g. to send direct notifications to a specific device). + +### onTokenReceived + +Add `onTokenReceived` listeners to respond to a token being received by your app. + +A token will be received by your app: + +- On every app launch, including the first install +- When a token changes (this may happen if the service invalidates the token for any reason) + +```js +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 +``` diff --git a/src/fragments/lib/push-notifications/react-native/request_permissions/request-permissions.mdx b/src/fragments/lib/push-notifications/react-native/request_permissions/request-permissions.mdx new file mode 100644 index 00000000000..f2a573a9e69 --- /dev/null +++ b/src/fragments/lib/push-notifications/react-native/request_permissions/request-permissions.mdx @@ -0,0 +1,83 @@ +Depending on your users' platform and operating system version, it is likely that you will need to request their permission to display push notifications. + +To learn more about the platform-specific guidances for requesting permissions, you can visit the respective documentations for [iOS](https://developer.apple.com/documentation/usernotifications/asking_permission_to_use_notifications) and [Android](https://developer.android.com/develop/ui/views/notifications/notification-permission). To best aid you in giving your users a good permission experience with platform idiomatic flows, Amplify provides the functionality below. + +## Get permission status + +The first step to request permissions from your user is to understand the current status of permissions. Your app may behave differently in response to these possible statuses below. + +- **SHOULD_REQUEST** - No permissions have been requested yet. It is idiomatic at this time to simply request for permissions from the user. +- **SHOULD_EXPLAIN_THEN_REQUEST** - It is recommended at this time to provide some context or rationale to the user explaining why you are requesting permission to display notifications to them before then requesting for permissions. +- **GRANTED** - Permissions have been granted by the user. No further actions are needed and their app is ready to display notifications. +- **DENIED** - Permissions have been denied by the user. Further attempts to request permissions will no longer trigger a permission dialog. Your app should now either degrade gracefully or prompt your user to grant the permissions needed in their device settings. + + + If you use TypeScript for your development, the string values returned can be + represented as PushNotificationPermissionStatus enum members as well. + + +```js +const status = await Notifications.Push.getPermissionStatus(); +// 'SHOULD_REQUEST' | 'SHOULD_EXPLAIN_THEN_REQUEST' | 'GRANTED' | 'DENIED' +``` + +## Request permissions + +Once you have determined if the current permission status requires you to request permissions from the user, you can call `requestPermissions()` to make that request. + +Amplify requests all supported notification permissions by default. But you can also choose not to request specific permissions. + + + It is recommended that you specify these permissions if needed but it is + important to note that they are ignored by Android + + +- **Alert**: When set to true, requests the ability to display notifications to the user. +- **Sound**: When set to true, requests the ability to play a sound in response to notifications. +- **Badge**: When set to true, requests the ability to update the app's badge. + +```js +const permissions = { + // permissions are true by default + // alert: true + sound: false, + badge: false +}; + +const result = await Notifications.Push.requestPermissions(permissions); +// true if granted (or already granted), false otherwise +``` + +## Sample permissions flow + +Use `getPermissionStatus()` and `requestPermissions()` together to handle permission request flows. Below is a sample implementation of the expected logic. + + + Remember, if you use TypeScript for your development, you can use the + PushNotificationPermissionStatus enum for comparison as well! + + +```js +function handlePermissions() { + const status = await Notifications.Push.getPermissionStatus(); + if (status === 'GRANTED') { + // no further action is required, user has already granted permissions + return; + } + if (status === 'DENIED') { + // further attempts to request permissions will no longer do anything + myFunctionToGracefullyDegradeMyApp(); + return; + } + if (status === 'SHOULD_REQUEST') { + // go ahead and request permissions from the user + await Notifications.Push.requestPermissions(); + } + if (status === 'SHOULD_EXPLAIN_THEN_REQUEST') { + // you should display some explanation to your user before requesting permissions + await myFunctionExplainingPermissionsRequest(); + // then request permissions + await Notifications.Push.requestPermissions(); + } +} +``` diff --git a/src/fragments/lib/push-notifications/react-native/setup_push_service/setup-push-service.mdx b/src/fragments/lib/push-notifications/react-native/setup_push_service/setup-push-service.mdx new file mode 100644 index 00000000000..cb61d77d189 --- /dev/null +++ b/src/fragments/lib/push-notifications/react-native/setup_push_service/setup-push-service.mdx @@ -0,0 +1,16 @@ + + + +import apnsSetup from '/src/fragments/lib/push-notifications/ios/setup_push_service/setup-apns.mdx'; + + + + + + +import fcmSetup from '/src/fragments/lib/push-notifications/android/setup_push_service/setup-fcm.mdx'; + + + + + \ No newline at end of file diff --git a/src/fragments/lib/react-native-polyfills.mdx b/src/fragments/lib/react-native-polyfills.mdx index 6a20338d27c..320b51330e6 100644 --- a/src/fragments/lib/react-native-polyfills.mdx +++ b/src/fragments/lib/react-native-polyfills.mdx @@ -4,7 +4,7 @@ npm install aws-amplify @react-native-community/netinfo @react-native-async-storage/async-storage react-native-get-random-values react-native-url-polyfill ``` -The AWS SDK requires React Native applications to polyfill `crypto.getRandomValues` and `URL`. Import it at the top of your application's root entry point (in most React Native apps this will be the top level `index.js`). +You need to add the crypto.getRandomValues and URL polyfills to your application's entry point file (in most React Native apps this will be the top level index.js). ```js // Example index.js diff --git a/src/fragments/lib/reactnative.mdx b/src/fragments/lib/reactnative.mdx index d06d5c43e98..5b4d6ab7b57 100644 --- a/src/fragments/lib/reactnative.mdx +++ b/src/fragments/lib/reactnative.mdx @@ -10,6 +10,6 @@ What's next? Here are some things you can add to your app: - [Serverless APIs](/lib/graphqlapi/getting-started) - [Analytics](/lib/analytics/getting-started) - [AI/ML](/lib/predictions/getting-started) -- [In-app Messaging](/lib/in-app-messaging/getting-started) -- [Push Notification](/lib/push-notifications/getting-started) +- [In-App Messaging](/lib/in-app-messaging/getting-started) +- [Push Notifications](/lib/push-notifications/getting-started) - [PubSub](/lib/pubsub/getting-started) diff --git a/src/fragments/sdk/analytics/android/getting-started.mdx b/src/fragments/sdk/analytics/android/getting-started.mdx index ef0b8a8ce78..40b0429d02f 100644 --- a/src/fragments/sdk/analytics/android/getting-started.mdx +++ b/src/fragments/sdk/analytics/android/getting-started.mdx @@ -12,8 +12,10 @@ Amazon Pinpoint is a fully managed AWS service that you can use to engage with y The Amplify CLI helps setup and configure Pinpoint within your application and connect with the AWS Mobile SDK. -Prerequisite: [Install and configure the Amplify CLI](/cli/start/install) -
Recommendation: [Complete the Getting Started guide](/start) + + Prerequisite: + [Install and configure the Amplify CLI](/cli/start/install)
+Recommendation: [Complete the Getting Started guide](/start) ## Set Up Your Backend @@ -178,4 +180,4 @@ Build and run your app to see usage metrics in Amazon Pinpoint. When you run the ![getting-started-analytics](/images/getting-started-analytics.png) -Analytics events can be grouped into segments, and you can engage your users more deeply by tying their app usage behavior to Push Notification, email, or SMS messaging campaigns. Read more about this in the [messaging section](/sdk/push-notifications/messaging-campaign) or [click here to learn more about Amazon Pinpoint](http://docs.aws.amazon.com/pinpoint/latest/developerguide/welcome.html). +Analytics events can be grouped into segments, and you can engage your users more deeply by tying their app usage behavior to push notification, email, or SMS messaging campaigns. Read more about this in the [messaging section](/sdk/push-notifications/messaging-campaign) or [click here to learn more about Amazon Pinpoint](http://docs.aws.amazon.com/pinpoint/latest/developerguide/welcome.html). diff --git a/src/fragments/sdk/analytics/ios/getting-started.mdx b/src/fragments/sdk/analytics/ios/getting-started.mdx index e859c892a99..af1582bc4bd 100644 --- a/src/fragments/sdk/analytics/ios/getting-started.mdx +++ b/src/fragments/sdk/analytics/ios/getting-started.mdx @@ -146,4 +146,4 @@ amplify console analytics ![getting-started-analytics](/images/getting-started-analytics.png) -Analytics events can be grouped into segments, and you can engage your users more deeply by tying their app usage behavior to Push Notification, email, or SMS messaging campaigns. Read more about this in the [messaging section](/sdk/push-notifications/messaging-campaign) or [click here to learn more about Amazon Pinpoint](http://docs.aws.amazon.com/pinpoint/latest/developerguide/welcome.html). +Analytic events can be grouped into segments, allowing you to engage your users more deeply by tying their app usage behavior to push notification, email, or SMS messaging campaigns. Read more about this in the [messaging section](/sdk/push-notifications/messaging-campaign) or [click here to learn more about Amazon Pinpoint](http://docs.aws.amazon.com/pinpoint/latest/developerguide/welcome.html). diff --git a/src/fragments/start/getting-started/reactnative/nextsteps.mdx b/src/fragments/start/getting-started/reactnative/nextsteps.mdx index 81843b52589..6cae9a2a818 100644 --- a/src/fragments/start/getting-started/reactnative/nextsteps.mdx +++ b/src/fragments/start/getting-started/reactnative/nextsteps.mdx @@ -3,8 +3,8 @@ - [User File Storage](/lib/storage/getting-started) - [Serverless APIs](/lib/graphqlapi/getting-started) - [Analytics](/lib/analytics/getting-started) -- [AI/ML](/lib/predictions/getting-started) +- [AI/ML](/lib/predictions/getting-started) - [In-App Messaging](/lib/in-app-messaging/overview) -- [Push Notification](/lib/push-notifications/getting-started) +- [Push Notifications](/lib/push-notifications/getting-started) - [PubSub](/lib/pubsub/getting-started) -- [AR/VR](/lib/xr/getting-started) \ No newline at end of file +- [AR/VR](/lib/xr/getting-started) diff --git a/src/pages/lib/push-notifications/app-badge-count/q/platform/[platform].mdx b/src/pages/lib/push-notifications/app-badge-count/q/platform/[platform].mdx new file mode 100644 index 00000000000..2de8149440e --- /dev/null +++ b/src/pages/lib/push-notifications/app-badge-count/q/platform/[platform].mdx @@ -0,0 +1,8 @@ +export const meta = { + title: `App badge count`, + description: `Get and set the application badge count.` +}; + +import reactNativeRoute from '/src/fragments/lib/push-notifications/react-native/app_badge_count/app-badge-count.mdx'; + + diff --git a/src/pages/lib/push-notifications/enable-rich-notifications/q/platform/[platform].mdx b/src/pages/lib/push-notifications/enable-rich-notifications/q/platform/[platform].mdx new file mode 100644 index 00000000000..0207c2c64af --- /dev/null +++ b/src/pages/lib/push-notifications/enable-rich-notifications/q/platform/[platform].mdx @@ -0,0 +1,8 @@ +export const meta = { + title: `Enable rich notifications`, + description: `Enable rich notifications for you app.` +}; + +import reactNativeRoute from '/src/fragments/lib/push-notifications/react-native/enable_rich_notifications/enable-rich-notifications.mdx'; + + diff --git a/src/pages/lib/push-notifications/getting-started/q/platform/[platform].mdx b/src/pages/lib/push-notifications/getting-started/q/platform/[platform].mdx index 0ab8521de03..2f398e18e2d 100644 --- a/src/pages/lib/push-notifications/getting-started/q/platform/[platform].mdx +++ b/src/pages/lib/push-notifications/getting-started/q/platform/[platform].mdx @@ -1,16 +1,14 @@ export const meta = { title: `Getting started`, - description: `Use of Push Notifications of Amplify` + description: `Use of Amplify Push Notifications` }; -import reactnative0 from '/src/fragments/lib/push-notifications/js/getting-started.mdx'; +import commonRoute from '/src/fragments/lib/push-notifications/common/getting-started.mdx'; - - -import android1 from "/src/fragments/lib/push-notifications/common/getting-started.mdx"; - - - -import ios2 from "/src/fragments/lib/push-notifications/common/getting-started.mdx"; - - + diff --git a/src/pages/lib/push-notifications/identify-user/q/platform/[platform].mdx b/src/pages/lib/push-notifications/identify-user/q/platform/[platform].mdx index fba80ba03c1..f0de75c942c 100644 --- a/src/pages/lib/push-notifications/identify-user/q/platform/[platform].mdx +++ b/src/pages/lib/push-notifications/identify-user/q/platform/[platform].mdx @@ -1,12 +1,14 @@ export const meta = { title: `Identify user to Amazon Pinpoint`, - description: `Provide information about a user to Amazon Pinpoint.`, + description: `Provide information about a user to Amazon Pinpoint.` }; -import android0 from "/src/fragments/lib/push-notifications/common/identify-user.mdx"; +import commonRoute from '/src/fragments/lib/push-notifications/common/identify-user.mdx'; - - -import ios1 from "/src/fragments/lib/push-notifications/common/identify-user.mdx"; - - + diff --git a/src/pages/lib/push-notifications/interact-with-notifications/q/platform/[platform].mdx b/src/pages/lib/push-notifications/interact-with-notifications/q/platform/[platform].mdx new file mode 100644 index 00000000000..f77ae412342 --- /dev/null +++ b/src/pages/lib/push-notifications/interact-with-notifications/q/platform/[platform].mdx @@ -0,0 +1,8 @@ +export const meta = { + title: `Interact with notifications`, + description: `Interact with push notifications through various events.` +}; + +import reactNativeRoute from '/src/fragments/lib/push-notifications/react-native/interact_with_notifications/interact-with-notifications.mdx'; + + diff --git a/src/pages/lib/push-notifications/migrate-from-previous-version/q/platform/[platform].mdx b/src/pages/lib/push-notifications/migrate-from-previous-version/q/platform/[platform].mdx new file mode 100644 index 00000000000..ce9b5447435 --- /dev/null +++ b/src/pages/lib/push-notifications/migrate-from-previous-version/q/platform/[platform].mdx @@ -0,0 +1,8 @@ +export const meta = { + title: `Migrate from previous version`, + description: `Migrate from the deprecated to the new version of Amplify Push Notifications.` +}; + +import reactNativeRoute from '/src/fragments/lib/push-notifications/react-native/migrate_from_previous_version/migrate-from-previous-version.mdx'; + + diff --git a/src/pages/lib/push-notifications/overview/q/platform/[platform].mdx b/src/pages/lib/push-notifications/overview/q/platform/[platform].mdx deleted file mode 100644 index b552fc65f37..00000000000 --- a/src/pages/lib/push-notifications/overview/q/platform/[platform].mdx +++ /dev/null @@ -1,8 +0,0 @@ -export const meta = { - title: `Overview`, - description: `The Push Notifications category allows you to integrate push notifications in your app with Amazon Pinpoint targeting and campaign management support.` -}; - -import reactnative0 from '/src/fragments/lib/push-notifications/js/overview.mdx'; - - diff --git a/src/pages/lib/push-notifications/receive-device-token/q/platform/[platform].mdx b/src/pages/lib/push-notifications/receive-device-token/q/platform/[platform].mdx new file mode 100644 index 00000000000..d1522bf841f --- /dev/null +++ b/src/pages/lib/push-notifications/receive-device-token/q/platform/[platform].mdx @@ -0,0 +1,8 @@ +export const meta = { + title: `Receive device token`, + description: `Receive a device token for use with push notifications.` +}; + +import reactNativeRoute from '/src/fragments/lib/push-notifications/react-native/receive_device_token/receive-device-token.mdx'; + + diff --git a/src/pages/lib/push-notifications/request-permissions/q/platform/[platform].mdx b/src/pages/lib/push-notifications/request-permissions/q/platform/[platform].mdx new file mode 100644 index 00000000000..ccff99ec102 --- /dev/null +++ b/src/pages/lib/push-notifications/request-permissions/q/platform/[platform].mdx @@ -0,0 +1,8 @@ +export const meta = { + title: `Request permissions`, + description: `Request permissions to display push notifications to users.` +}; + +import reactNativeRoute from '/src/fragments/lib/push-notifications/react-native/request_permissions/request-permissions.mdx'; + + diff --git a/src/pages/lib/push-notifications/setup-push-service/q/platform/[platform].mdx b/src/pages/lib/push-notifications/setup-push-service/q/platform/[platform].mdx index b1876975468..571486e3dc3 100644 --- a/src/pages/lib/push-notifications/setup-push-service/q/platform/[platform].mdx +++ b/src/pages/lib/push-notifications/setup-push-service/q/platform/[platform].mdx @@ -1,12 +1,14 @@ export const meta = { title: `Setting up push notification services`, - description: `Learn how to setup the various push notification services for your mobile app.`, + description: `Learn how to setup the various push notification services for your mobile app.` }; -import android0 from "/src/fragments/lib/push-notifications/common/setup-push-service.mdx"; +import commonRoute from '/src/fragments/lib/push-notifications/common/setup-push-service.mdx'; - - -import ios1 from "/src/fragments/lib/push-notifications/common/setup-push-service.mdx"; - - + diff --git a/src/pages/lib/push-notifications/testing/q/platform/[platform].mdx b/src/pages/lib/push-notifications/testing/q/platform/[platform].mdx index 28416a4dc92..51d366c978a 100644 --- a/src/pages/lib/push-notifications/testing/q/platform/[platform].mdx +++ b/src/pages/lib/push-notifications/testing/q/platform/[platform].mdx @@ -1,16 +1,14 @@ export const meta = { title: `Testing`, - description: `Overview of testing your Push Notifications` + description: `Overview of testing your push notifications` }; -import reactnative0 from '/src/fragments/lib/push-notifications/js/testing.mdx'; +import commonRoute from '/src/fragments/lib/push-notifications/common/testing.mdx'; - - -import android1 from '/src/fragments/lib/push-notifications/common/testing.mdx'; - - - -import ios2 from '/src/fragments/lib/push-notifications/common/testing.mdx'; - - + diff --git a/src/pages/lib/push-notifications/working-with-api/q/platform/[platform].mdx b/src/pages/lib/push-notifications/working-with-api/q/platform/[platform].mdx deleted file mode 100644 index 0b1c066ddf6..00000000000 --- a/src/pages/lib/push-notifications/working-with-api/q/platform/[platform].mdx +++ /dev/null @@ -1,8 +0,0 @@ -export const meta = { - title: `Working with API`, - description: `Breakdown of using the Push Notifications API in Amplify` -}; - -import reactnative0 from '/src/fragments/lib/push-notifications/js/working-with-api.mdx'; - -