This page provides an overview and the procedure involved in using push notifications in an AEM Mobile app.

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.

Note:

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.

For Developers

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

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.

Register and Configure a Push Messaging Service

AEM is configured to use one of two services for push notifications - Amazon SNS and Pushwoosh:

Using the Amazon SNS messaging service

If you do not want to use Amazon SNS you can skip this step.

NOTE: 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.

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".

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

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

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 the Create New Access Key button.

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, etc., can be managed on this page.

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, and click Update Policy.

Note: You can create multiple topics for different uses, i.e. dev, test, demo, etc. 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).

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.

Add push support to the app

Add Client Libraries

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

In CRX DE Lite:

Navigate to /etc/designs/phonegap/<app name>/<clientlibs folder>.

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.

If you are using Amazon SNS, you also need to add “cq.mobile.push.amazon”.

Click OK and save the changes.

Prepare a Phone for Testing

Note:

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.

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.

For Administrators

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 are using.

Create the appropriate AEM user-groups for push notifications.

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

Click on the App.

Click on the Settings icon of the "Push Notifications" tile.

From the first drop down list, select Amazon SNS or Pushwoosh as the notification configuration.

Click on the wrench to manage the notification service, this will take you to the Cloud Services page allowing you to create new configurations.

Click on the "+" next to "Available Configurations" and provide the required title, i.e., Amazon SNS Config, and optional name.

You will now be presented with a list of required fields that you got when you configured Amazon or Pushwoosh. Fill them out and be diligent that you are pasting in the correct values.

Click "OK" when done.

Go back to the Apps Command Center from which you opened the cloud configuration page. Select the new configuration you just created from the dropdown and click "update".

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.

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.

Note:

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:

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

Upon receipt of the notification:

Open the app via the notification:

Clicking "Show me!" takes you to the linked destination.

Note:

The Link Button Text is limited to 20 characters.

If the end user doesn't have the latest version of the application and the linked path isn't available, confirming the action of the deep link will bring the user to the main page of the app.

What's Left?

At this point we've seen how AEM administrators, developers and authors combine strengths to create AEM Mobile apps. These apps are dynamic, powerful, and valuable. A successful AEM Mobile app is one that can: