Push Notifications push-notifications

NOTE
Adobe recommends using the SPA Editor for projects that require single page application framework-based client-side rendering (for example, React). Learn more.

Being able to instantly alert your Adobe Experience Manager (AEM) Mobile app users with important notifications is crucial to the value of a mobile app and its marketing campaigns. Here, steps are described that must be taken to let your app receive push notifications. You also learn how to configure and send pushes from AEM Mobile to the app installed on the phone. Also, this section describes how to configure the Deep Linking feature to your push notifications.

NOTE
Push notifications are not guaranteed delivery; they are more like announcements. A best effort is made to make sure that everyone receives them but they are not a guaranteed delivery mechanism. Also, the time to deliver a push can vary from less than a second to up to half an hour.

Using push notifications with AEM requires a few different technologies. First, a push notification service provider must be used to managethenotifications and devices (AEM does not do this, yet). Two providers are configured out-of-the-box with AEM: Amazon Simple Notification Service (or SNS), and Pushwoosh. Second, the push technology for the given mobile OS must go through the appropriate service — Apple’s Push Notification Service (or APNS) for iOS devices; and Google Cloud Messaging (or GCM) for Android™ devices. Although AEM does not communicate with these platform-specific services directly, some related configuration information must be provided by AEM along with the notifications for these services to execute the push.

Once installed and configured (as explained below) it works like this:

  1. A push notification is created in AEM, and sent to the service provider (Amazon SNS or Pushwoosh).
  2. The service provider receives it and sends it to the core provider (APNS or GCM).
  3. The core provider pushes the notification to all devices registered for that push. For each device, it uses the cellular data network or WiFi, whichever is available on the device.
  4. The notification displays on the device if the app that it is registered for, is not running. A user tapping on the notification starts the app and display the notification within the app. In the case that the application is already running, only the in-app notification is displayed.

This release of AEM supports iOS and Android™ mobile devices.

Overview and Procedure overview-and-procedure

To use push notifications in an AEM Mobile app, the following high-level steps must be taken.

Typically, an Experience Manager Developer does the following:

  1. Register with Apple and Google messaging services
  2. Register with a push messaging service and configure it
  3. Add push support to the app
  4. Prepare a phone for testing

While an Experience Manager Administrator does the following:

  1. Configure push on AEM apps
  2. Build and deploy the app
  3. Send a Push Notification
  4. Configure deep linking (optional)

Step 1: Register with Apple and Google messaging services step-register-with-apple-and-google-messaging-services

Using the Apple Push Notification Service (APNS) using-the-apple-push-notification-service-apns

Go to the Apple page here to become familiar with the Apple Push Notification Service.

To use APNs, you need a Certificate file (a .cer file), a push Private Key (a .p12 file), and a Private Key Password from Apple. Instructions on how to do that can be found here.

Using the Google Cloud Messaging (GCM) service using-the-google-cloud-messaging-gcm-service

NOTE
Google is replacing GCM with a similar service called Firebase Cloud Messaging (FCM). For more information on FCM, click here.

Go to the Google page here to become familiar with Google Cloud Messaging for Android™.

Follow these steps to Create a Google API project, Enable the GCM Service, and Obtain an API Key. You need the API Key to send push notifications to Android™ devices. Also, record your Project Number, which is also sometimes called a GCM Sender Id.

The following steps show a different method of creating GCM API Keys:

  1. Log into google and go to the Google’s Developer page.
  2. Choose your app from the list (or create one).
  3. Under Android™ Package Name, enter your app id, that is, com.adobe.cq.mobile.weretail.outdoorsapp. (If that does not work, try again with “test.test”.)
  4. Click Continue To Choose and configure services
  5. Select Cloud Messaging, and then click Enable Google Cloud Messaging.
  6. The new Server API Key and (new or existing) Sender ID will then be displayed.
NOTE
Record the Server API Key. This value is entered on the site of your push provider.

Step 2: Register and Configure a Push Messaging Service step-register-and-configure-a-push-messaging-service

AEM is configured to use one of three services for push notifications:

  • Amazon SNS
  • Pushwoosh
  • Adobe Mobile Services

Amazon SNS and Pushwoosh configurations let you send pushed from inside AEM screens.

Adobe Mobile Services configuration lets you configure and send push notifications from within Adobe Mobile Services using an Adobe Analytics account (but the app must be built with this config set to enable AMS push notifications).

Using the Amazon SNS messaging service using-the-amazon-sns-messaging-service

NOTE
Information about Amazon SNS, and a link to create an AWS account, can be found here. You can get a free account for a year.

If you do not want to use Amazon SNS, you can skip these steps.

Follow these steps to set up Amazon SNS for push notifications:

  1. Register with Amazon SNS

    1. Record your Account Id. The format should be 12 digits with no spaces or dashes, that is, “123456789012”.
    2. Ensure you are in the “us-east” or “eu” region, as a later step (Identity Pool Creation) requires one of those.
    3. After registering, log in to the management console and select SNS (Push Notification Service). Click “Get Started” if it appears.
  2. Create Access Key and ID

    1. Click your login name on the upper right of the screen, and choose Security Credentials from the menu.
    2. Click Access Keys, and in the space below, click Create New Access Key.
    3. Click Show Access Key, and copy and save the Access Key ID and Secret Access Key shown. If you choose the option to download the keys, you get a csv file that contains those same values.
    4. Other security-related certificates, and some other, can be managed on this page.
    note note
    NOTE
    An Access Key can be used for multiple apps.

    For organizations, which use an “AWS Sandbox” account, the steps are similar, and outlined here:

    1. Click your login name on the upper right of the screen, and choose My Security Credentials from the menu.
    2. Click Users in the left list of actions, and choose your user name.
    3. Click the Security credentials tab.
    4. From here, you see your keys and create new keys. Save the keys for later use.
  3. Create a Topic

    1. Click Create Topic and choose a topic name. Record all fields such as Topic ARN, Topic Owner, Region, Display name.
    2. Click Other Topic Actions > Edit Topic Policy. Under Allow these users to subscribe to this topic, select Everyone.
    3. Click Update Policy.
    note note
    NOTE
    You can create multiple topics for different scenarios such as dev, test, and demo. The rest of the SNS configuration can remain the same. Build the app with the different topic; push notifications sent to that topic will only be received by the app built with that topic.
  4. Create Platform Applications

    1. Click Applications, then Create Platform Application. Choose a name and select a platform (APNS for iOS, GCM for Android™). Depending on the platform. other fields must be filled in:

      1. For APNS, a P12 file, a Password, a Certificate, and a Private Key must all be entered. These should have been obtained in the step Using the Apple Push Notification Service (APNS) above.
      2. For GCM, an API Key must be entered. This should have been obtained in the step Using the Google Cloud Messaging (GCM) service above.
    2. Repeat the above step once for each platform that you are supporting. To be able to push to both iOS and Android™, two Platform Applications must be created.

  5. Create an Identity Pool

    1. Use Cognito to create an Identity Pool, which will store basic data of unauthenticated users. Note, only “us-east” and “eu” regions are supported by Amazon Cognito currently.
    2. Give it a name, and check the box for “Enable access to unauthenticated identities”.
    3. On the next page (“Your Cognito identities require access to your resources”) click Allow.
    4. On the upper right of the page, click the link "Edit identity pool". The Identity Pool Id is shown. Save this text for later.
    5. On the same page, choose the drop-down next to “Unauthenticated role” and ensure it has the role Cognito_<pool name>UnauthRole selected. Save your changes.
  6. Configure Access

    1. Log in to Identity and Access Management (IAM).
    2. Select Roles.
    3. Click the role created in the previous step, called Cognito_<yourIdentityPoolName>Unauth_Role. Record the “Role ARN” displayed.
    4. Open “Inline Policies” if it is not already opened. You should see a policy there with a name like oneClick_Cognito_<yourIdentityPoolName>Unauth_Role_1234567890123.
    5. Click “Edit Policy”. Replace the contents of the Policy Document with this snippet of JSON:
    table 0-row-1 html-authored no-header

    {

    "Version": "2012-10-17",

    "Statement": [

    {

    "Action": [

    "mobileanalytics:PutEvents",

    "cognito-sync:*",

    "SNS:CreatePlatformEndpoint",

    "SNS:Subscribe"

    ],

    "Effect": "Allow",

    "Resource": [

    "*"

    ]

    }

    ]

    }

    1. Click Apply Policy.

Using the Pushwoosh messaging service using-the-pushwoosh-messaging-service

If you do not want to use Pushwoosh, you can skip this step.

To use Pushwoosh:

  1. Register with Pushwoosh

    1. Go to pushwoosh.com and create an account.
  2. Create an API Access Token

    1. On the Pushwoosh site, go to the API Access menu item to generate an API Access Token. Securely record this token.
  3. Create an app

    1. For Android™ support, you must provide your GCM API key.
    2. When configuring the app, choose Cordova as the framework.
    3. For iOS support you must provide the Certificate file (.cer), Push Certificate (.p12) and private key password; these should have been obtained from Apple’s APNS site. For Framework, choose Cordova.
    4. Pushwoosh will generate an App Id for that app, in the form “XXXXX-XXXXX”, where each X is a hexadecimal value (0 through F).
NOTE
If a second app is configured in AEM with the same App Id (and other related values: API Access Token, and GCM Id), any push notifications sent via the second app on AEM will go to any other app with that App Id.

Step 3: Add push support to the app step-add-push-support-to-the-app

Add ContentSync Configuration add-contentsync-configuration

Create two content nodes (one in app-config and one in app-config-dev) called notificationsConfig:

  • /content/<your app>/shell/jcr:content/pge-app/app-config-dev/notificationsConfig
  • /content/<your app>/shell/jcr:content/pge-app/app-config/notificationsConfig

With these properties (.content.xml files) :
<jcr:root xmlns:jcr=" https://developer.adobe.com/experience-manager/reference-materials/spec/jcr/1.0/index.html" xmlns:nt=" https://developer.adobe.com/experience-manager/reference-materials/spec/jcr/1.0/index.html"
jcr:primaryType=“nt:unstructured”
excludeProperties=“[appAPIAccessToken]”
path=“https://experienceleague.adobe.com/?lang=en”
targetRootDirectory=“www”
type=“notificationsconfig”/>

NOTE
The content sync handler looks for those nodes, and if they are not there, it does not write out the pge-notifications-config.json file.

Add Client Libraries add-client-libraries

The push notification client libraries must be added to the app by following these steps:

In CRXDE Lite:

  1. Navigate to /etc/designs/phonegap/<app name>/clientlibsall.
  2. Double-click the embed section in the properties pane.
  3. In the dialog box that appears, add a client lib by clicking the + button.
  4. In the new text field, add “cq.mobile.push”, and click OK.
  5. Add one more called cq.mobile.push.amazon, and click OK.
  6. Save the changes.
NOTE
If push notifications are removed, or are not used, for space considerations on the app, and to avoid console error messages, remove these clientlibs from your app.

Step 4: Prepare a Phone for Testing step-prepare-a-phone-for-testing

NOTE
For push notifications, you must test on an actual device, as emulators are not able to receive push notifications.

IOS ios

For iOS, use a macOS computer and join the iOS Developer Program. Some corporations have corporate licenses which may be available to all developers.

With XCode 8.1, before using Push Notifications you must go to the Capabilities tab in your project, and toggle the Push Notifications toggle ON.

Android™ android

To install the app on an Android™ phone using CLI (see below: Step 6 - Build and deploy the app), you first must put the phone in “developer mode.” See Enabling On-device Developer Options for details on doing this.

Step 5: Configure push on AEM apps step-configure-push-on-aem-apps

Before building and deploying to your configured mobile device, you must configure the notification settings for the messaging service you decided to use.

  1. Create the appropriate authorization groups for push notifications.
  2. Log in to AEM as the appropriate user, click the Apps tab.
  3. Click the App.
  4. Find the Manage Cloud Services tile and click the pencil, to modify your cloud configs.
  5. Select Amazon SNS Connection, Pushwoosh Connection, or Adobe Mobile Services, as the notification configuration.
  6. Enter the provider properties and click Submit to save them, and Done. They are not verified remotely at this stage, except if there is AMS.
  7. You should now see the config you just entered on the Manage Cloud Services tile.

Step 6: Build and deploy the app step-build-and-deploy-the-app

Note: See the instructions here on building PhoneGap applications.

There are two ways to build and deploy your app using PhoneGap.

Note: For push notification testing, emulators will not suffice because push notifications use a distinct protocol between the push provider (Apple or Google) and the device. Current Mac/PC hardware and emulators do not support this.

  1. PhoneGap Build is a service offered by PhoneGap that will build your app for you on their servers, and let you download it to your device directly. See PhoneGap Build documentation at https://build.phonegap.com/ to learn how to set up and use PhoneGap Build.

  2. PhoneGap Command Line Interface (CLI) lets you use a rich set of PhoneGap commands on your command line to build, debug, and deploy your app. Refer to the PhoneGap developer documentation (https://docs.phonegap.com/en/edge/guide_cli_index.md.html#The%20Command-Line%20Interface) to learn how to set up and use PhoneGap CLI.

Step 7: Send a Push Notification step-send-a-push-notification

To create a notification and send it, follow these steps.

  1. Create a notification

    • In your AEM Mobile app’s dashboard, find the Push Notifications tile.
    • In the menu on the upper right, choose “Create”. This button is not available until the cloud config is first set.
    • In the Create Notification Wizard, enter in a title and a message, then click the “Create” button. Your notification is now ready to send immediately or later. It can be edited and the message and/or title can be changed and saved.
  2. Send the notification

    • In the Apps dashboard, find the Push Notifications tile.
    • Select the notification, or click the details button on the bottom right (. . .), to show the list of notifications. This list also indicates if a notification is ready to be sent, has already been sent, or if an error occurred during sending.
    • Select the checkbox for one notification (only) and click the “Send Notification” button above the list. You have one chance to “Cancel” or “Send” the notification on the dialog that appears.
  3. Dealing with the results

    • If the push notification service (Amazon SNS or Pushwoosh) receives the Send request, confirms it as valid, and sends it to the native providers (APNS and GCM) successfully, the Send dialog box closes with no message. In the notification list, the status of that notification is listed as Sent.

    • If the push send fails, the dialog box shows a message indicating the problem. In the notification list, the status of that notification is listed as Error, but if the problem is rectified, the notification can be sent again. If there is an error, additional error information should appear in the server error log.

    • Note that there are some platform differences between iOS and Android™ push notifications. Among them:

      • Building with CLI will start the app after it is deployed on Android™. On iOS, you have to start it manually. Because the push registration step happens at startup, Android™ apps can receive push notifications right away (because it has already started and registered), while iOS apps cannot.
      • On Android™, the OK button text is in all caps (and in any other buttons added on the in-app notification), while in iOS it is not.

For AMS Push Notifications, notifications must be composed and sent from the AMS server. AMS provides additional push notification capabilities beyond those provided by AEM’s notifications with AWS and Pushwoosh.

NOTE
Push notifications are not guaranteed delivery; they are more like announcements. A best effort is made to make sure that everyone hears it but they are not a guaranteed delivery mechanism. Also, the time to deliver a push can vary from less than a second to up to half an hour.

Configuring Deep Linking with Push Notifications configuring-deep-linking-with-push-notifications

What is Deep Linking? In the context of a push notification, it is a means to allow an app to be opened or directed (if open) to a specified location inside the app.

How does it work? The author of a push notification optionally adds a button label (that is, “Show me!”) to the notification and chooses the page that they would like linked in the notification, via a visual path browser. When sent, the push occurs as normal except that in the in-app message, the OK button is replaced by a “Dismiss” button, and the new button specified (“Show me!”) also appears. Clicking the new button makes the app go to the specified page within the app. Clicking Dismiss expels the message.

If the app is not open, the shade appears as normal. Taking action on the notification in the shade opens the app and then presents the user the deep link buttons based on what was configured in the push notification.

Create the notification, add a button text and link path for the optional deep link:

CAUTION
To access the Push Notification tile in your dashboard, follow the steps below.
  1. Click the edit on the top-right corner of the Manage Cloud Services tile.

    chlimage_1-108

  2. Select the Pushwoosh Connection. Click Next.

    chlimage_1-109

  3. Enter the details of the properties and click Submit.

    chlimage_1-110

    One you submit your configuration, the Push Notifications tile displays in the dashboard.

    chlimage_1-111

Create Notification Wizard create-notification-wizard

Once the Push Notifications tile displays in your dashboard, use the create notification wizard to add the content:

  1. Click the add symbol on the top-right corner of the Push Notifications tile to open the Create Notification Wizard.

    chlimage_1-112

  2. Clicking the browse icon in the link path, presents the user with the content structure of the app.

    Once you select the path, click the check icon.

    chlimage_1-113

    note note
    NOTE
    The Link Button Text is limited to 20 characters.
    If the end user does not have the latest version of the application and the linked path is not available, confirming the action of the deep link will bring the user to the main page of the app.
  3. Enter the Text Details in the Create Notification Wizard and click Create.

    chlimage_1-114

    Open the details by clicking the push notification that you created from the Push Notifications tile.

    You can edit properties, send notifications, or delete the notification.

    chlimage_1-115

NOTE
Additional Information:
Pushwoosh and Amazon SNS will be not be supported after 6.4 Release and will be available as an add-on from the Package Share.

The Next Steps the-next-steps

Once you understand the details on push notifications for your app, see AEM Mobile Content Personalization.

recommendation-more-help
2eeeb575-8007-40cc-a72d-206fbc4ddd4b