Adobe recommends using the SPA Editor for projects that require single page application framework-based client-side rendering (e.g. React). Learn more.
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.
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 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:
This release of AEM supports iOS and Android mobile devices.
To use push notifications in an AEM Mobile app, the following high-level steps must be taken.
Typically, an AEM Developer will:
While an AEM Administrator will:
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.
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:
com.adobe.cq.mobile.weretail.outdoorsapp. (If that does not work, try again with “test.test”.)
Record the Server API Key. This value is entered on the site of your push provider.
AEM is configured to use one of three services for push notifications:
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).
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
Create Access Key and ID
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:
Create a Topic
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:
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
If you do not want to use Pushwoosh, you can skip this step.
To use Pushwoosh:
Register with Pushwoosh
Create an API Access Token
Create a new app
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.
Create two content nodes (one in app-config and one in app-config-dev) called notificationsConfig:
With these properties (.content.xml files) :
<jcr:root xmlns:jcr=" https://www.jcp.org/jcr/1.0" xmlns:nt=" https://www.jcp.org/jcr/nt/1.0"
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.
The push notification client libraries must be added to the app by following these steps:
In CRXDE Lite:
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.
For push notifications, you need to test on an actual device, as emulators are not able to receive push notifications.
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.
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.
Before building and deploying to your configured mobile device, you must configure the notification settings for the messaging service you decided to use.
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.
To create a new notification and send it, follow these steps.
Create a new notification
Send the notification
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:
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.
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.
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:
.To access the Push Notification tile in your dashboard, follow the steps below.
Click the edit on the top right corner of the Manage Cloud Services tile.
Select the Pushwoosh Connection. Click Next.
Enter the details of the properties and click Submit.
One you submit your configuration, the Push Notifications tile displays in the dashboard.
Once the Push Notifications tile displays in your dashboard, use the create notification wizard to add the content:
Click the add symbol on the top right corner of the Push Notifications tile to open the Create Notification Wizard.
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.
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.
Enter the Text Details in the Create Notification Wizard and click Create.
Open the details by clicking on the push notification you created from the Push Notifications tile.
You can edit properties, send notifications, or delete the notification.
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.
Once you understand the details on push notifications for your app, see AEM Mobile Content Personalization.