Push Notifications

Being able to instantly alert your AEM Mobile app users with important notifications is crucial to the value of a mobile app and its marketing campaigns. Here, we describe the steps that need to be taken to allow your app to receive push notifications, and how to configure and send pushes from AEM Mobile to the app installed on the phone. Additionally, this section describes how to configure the Deep Linking feature to your push notifications.

Not:

Push notifications are not guaranteed delivery; they are more like announcements. A best effort is made to make sure 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 manage the the notifications 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 in order for these services to execute the push.

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

A push notification is created in AEM, and sent to the service provider (Amazon SNS or Pushwoosh).

The service provider receives it and sends it to the core provider (APNS or GCM).

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 currently available on the device.

The notification displays on the device if the app it is registered for is not running. A user tapping on the notification will start 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

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

Typically, an AEM Developer will:

Register with Apple and Google messaging services

Register with a push messaging service and configure it

Add push support to the app

Prepare a phone for testing

While an AEM Administrator will:

Configure push on AEM apps

Build and deploy the app

Send a Push Notification

Configure deep linking (optional)

Step 1: Register with Apple and Google messaging services

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 will 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

Not:

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.

You will need to follow the steps here to Create a Google API project, Enable the GCM Service, and Obtain an API Key. You will 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 shows a different method of creating GCM API Keys:

Under Android Package Name, enter your app id, i.e. "com.adobe.cq.mobile.weretail.outdoorsapp". (If that does not work, try again with "test.test").

Click Continue To Choose and configure services

Select Cloud Messaging, and then click Enable Google Cloud Messaging.

The new Server API Key and (new or existing) Sender ID will then be displayed.

Not:

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

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

Amazon SNS

Pushwoosh

Adobe Mobile Services

Amazon SNS and Pushwoosh configurations will allow you to send pushed from inside AEM screens.

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

Using the Amazon SNS messaging service

Not:

Information about Amazon SNS, and a link to create a new 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:

Register with Amazon SNS

Record your Account Id. The format should be twelve digits with no spaces or dashes, i.e. "123456789012".

Ensure you are in the "us-east" or "eu" region, as a later step (Identity Pool Creation) requires one of those.

After registering, log into the management console and select SNS (Push Notification Service). Click on "Get Started" if it appears.

Create Access Key and ID

Click on your login name on the upper right of the screen, and choose Security Credentials from the menu.

Click on Access Keys, and in the space below, click Create New Access Key.

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 will get a csv file that contains those same values.

Other security related certificates, and some other, can be managed on this page.

Not:

An Access Key can be used for multiple apps.

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

Click on your login name on the upper right of the screen, and choose My Security Credentials from the menu.

Click on Users in the left list of actions, and choose your user name.

Click on the Security credentials tab.

From here you see your keys and create new keys. Save the keys for later use.

Create a Topic

Click Create Topic and choose a topic name. Record all fields such as Topic ARN, Topic Owner, Region, Display name.

Click Other Topic Actions -> Edit Topic Policy. Under Allow these users to subscribe to this topic, select Everyone.

Click Update Policy.

Not:

You can create multiple topics for different scenarios such as dev, test, demo, and so on. 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.

Create Platform Applications

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 will need to be filled in:

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.

For GCM, an API Key must be entered. This should have been obtained in the step Using the Google Cloud Messaging (GCM) service above.

Repeat the above step once for each platform you will be supporting. To be able to push to both iOS and Android, two Platform Applications must be created.

Create an Identity Pool

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 at this time.

Give it a name, and check the box for "Enable access to unauthenticated identities".

Click on the role created in the previous step, called Cognito_<yourIdentityPoolName>Unauth_Role. Record the "Role ARN" displayed.

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.

Click "Edit Policy". Replace the contents of the Policy Document with this snippet of JSON:

{

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

"Statement": [

{

"Action": [

"mobileanalytics:PutEvents",

"cognito-sync:*",

"SNS:CreatePlatformEndpoint",

"SNS:Subscribe"

],

"Effect": "Allow",

"Resource": [

"*"

]

}

]

}

Click on Apply Policy

Using the Pushwoosh messaging service

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

To use Pushwoosh:

Register with Pushwoosh

Go to pushwoosh.com and create a new account.

Create an API Access Token

On the Pushwoosh site, go to the API Access menu item to generate an API Access Token. You will need to securely record this.

Create a new app

For Android support, you need to provide your GCM API key.

When configuring the app, choose Cordova as the framework.

For iOS support you need to 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.

Pushwoosh will generate an App Id for that app, in the form "XXXXX-XXXXX", where each X is a hexadecimal value (0 through F).

Not:

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

Add ContentSync Configuration

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

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

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

In CRXDE Lite:

Navigate to /etc/designs/phonegap/<app name>/clientlibsall.

Double click on the embed section in the properties pane.

In the dialog that appears, add a new client lib by clicking the + button.

In the new text field, add “cq.mobile.push”, and click OK.

Add one more called cq.mobile.push.amazon, and click OK.

Save the changes.

Not:

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

Not:

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

IOS

For iOS you will need to use a Mac OS computer and you need to 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

To install the app on an Android phone using CLI (see below: 6 - Deploy the app onto your phone), 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

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

Create the appropriate authorization groups for push notifications.

Login to AEM as the appropriate user, click on the Apps tab.

Click on the App.

Find the Manage Cloud Services tile and click on the pencil, to modify your cloud configs.

Enter the provider properties and click Submit to save them, and Done. They are not verified remotely at this stage, except in the case of AMS.

You should now see the config you just entered on the Manage Cloud Services tile.

Step 6: Build and deploy the app

Note: Refer also to our 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.

PhoneGap Build is a service offered by PhoneGap that will build your app for you on their servers, and allow you to download it to your device directly. Refer to the PhoneGap Build documentation to learn how to set up and use PhoneGap Build.

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 to learn how to set up and use PhoneGap CLI.

Step 7: Send a Push Notification

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

Create a new notification

In your AEM Mobile app's dashboard, find the Push Notifications tile.

In the menu on the upper right, choose "Create". Note that this button will not be 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.

Send the notification

In the Apps dashboard, find the Push Notifications tile.

Select the notification, or click on 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 will have one chance to "Cancel" or "Send" the notification on the dialog that appears.

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 will close with no message. In the notification list, the status of that notification will be listed as Sent.

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

Note 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. Since the push registration step happens at startup, Android apps can receive push notifications right away (since it will have started and registered) while iOS apps will not.

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.

Not:

Push notifications are not guaranteed delivery; they are more like announcements. A best effort is made to make sure 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

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 (i.e. "Show me!") to the notification and chooses the page 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 on the new button will make the app go to the specified page within the app. Clicking Dismiss will just dismiss the message.

If the app is not open, the shade will appear as normal. Taking action on the notification in the shade will open the app and then present 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: