Using Apple push notifications with Digital Publishing Suite

Learn how to leverage Apple Push Notifications in your app created with Digital Publishing Suite, Enterprise Edition to notify users of new issues becoming available and trigger Newsstand background downloads. Learn about advanced topics such as using third-party push providers, using push notifications to send messages to users, and using server scripts to schedule push notifications.

Apple Push Notifications enable app developers and publishers to send notifications to their iOS apps when the user is not currently using the app. Push notifications are often used to display a message, play a sound, and set a number in a "badge" on the apps icon. In Adobe Digital Publishing apps, a push notification can inform the user that a new issue is available, and also trigger a background download of the new issue if the app is in the iOS Newsstand.

Once a Digital Publishing Suite app is enabled and registered to receive push notifications (described below), a notification can be initiated by a push provider server (either Adobe's DPS Push Provider Server, your own server, or a third-party push provider such as Urban Airship). The notification is sent to Apple's Push Notification Service server, which then forwards the notification to the targeted app on registered devices.

Before an app can receive push notifications, it needs to register with Apple and Adobe's Push Provider Server, as shown in Figure 1.

1. The user opts-in to receive push notifications, and the app registers with Apple's Push Notification Service (APNS)
2. APNS sends a unique device token to the app.
3. The app registers with the push provider (in this case, Apple's DPS Push Provider Server), every time the app is activated.

Once an app is registered for push, push notifications are sent to the app as shown in Figure 2.

1. In Folio Producer, a notification for Newsstand is manually initiated.
2. The Adobe DPS Push provider begins sending notifications for all registered devices immediately, via Apple's APNS. Adobe's Push Provider Service batches notifications containing groupings of device tokens, separated by short intervals to load-balance Newsstand downloading.
3. APNS sends actual notifications to devices, and iOS routes the notification to the app.

The push notification is initiated in Folio Producer as shown in Figure 3. The Adobe DPS Push Provider sends the notification "content-available:1", which indicates that new content is available for this app/viewer.

After receiving the push, a viewer app enabled for Apple Newsstand will initiate a background download via the following process:

1. Fetch a list of all folios published to the fulfillment account.
2. Determine which folio is the most recent. This is the one that will be used for background download.
3. Determine if a valid Apple subscription exists or whether the user is entitled via Direct Entitlement ( renewAuthToken and getEntitlements ). (See Direct Entitlement article for more information.)
4. Fetch the preview image and update the cover in Newsstand.
5. Fetch the folio.
6. Update the "New" sash on the preview within Newsstand upon successful completion.

For push and background downloading to function, a series of things are required.

Requirements for push

The following is required for push notifications to be possible:

1. Your application created in Digital Publishing Suite Viewer Builder must be enabled for Newsstand.
2. Your application must support Apple subscriptions, at a minimum. It can also support direct entitlement.
3. Apple APNS SSL certificates (*.p12 files) must be deployed to Adobe's fulfillment server (or other third-party APNS push provider). To generate a .p12 file:
   1. In Apple's iOS Provisioning Portal, enable the app ID for the Apple Push Notification Service (APNS).
   2. Click to configure Apple Push Notification SSL Certificate—follow Apple's instructions to generate a certificate.
   3. Download the Push SSL Certificate.
   4. Convert the Push SSL Certificate into a .p12 file (see "Publishing Companion Guide for the iPad " available for download on the DPS Dashboard for details)
4. Your application must be signed with Apple provisioning profiles tied to an Apple Bundle ID configured for Push. You must regenerate the mobile provision files after configuring the app ID for Push. To verify that your provisioning profile supports Push, look inside it (with TextEdit). You should see "<key>aps-environment</key>" in the dictionary:

5. You must have access to a working APNS push provider (Push Server). This server needs to format notifications and send and monitor feedback from Apple. Adobe's Digital Publishing Suite Push Provider system provides this.

Requirements for background downloading

A background download is the automatic download and installation of a folio into the application's library. Upon successful download, the cover screen in the Newsstand application will be updated to the new folio and a blue sash will be displayed over the upper-right corner (see Figure 4).

The following is required for background downloading to work:

1. An iPad with iOS 5. Background downloads are not supported on previous versions.
2. The user must opt-in to receive push notification messages. This is only presented the first time the application is installed. However, if the user does opt-in, the viewer/application will attempt to register for push notifications at the APNS provider every time it is activated.
3. The folio to be downloaded must not already be known to the viewer. Once known to the viewer, it will not be available for background download.
4. If using Apple subscriptions, the user must have a valid subscription active and enabled.
5. If using direct entitlements, the user must be signed in and the folio must be entitled to that user.
6. The device must be on WiFi at the time of the push reception. Background downloading will not happen over 3G, nor will the viewer queue it for later download.

Publishers requiring periodic notifications can do so with an API exposed by Adobe's fulfillment service. This is uniquely important to daily publishers, for which fidelity to a schedule must be maintained so as to not run afoul of Apple's 24-hour limitation. (Background downloads are limited to approximately once every 24 hours)

The following sample provides a programmatic method of sending Newsstand notification messages. Text alerts displayed on the user's device are not supported at this time by Adobe's push service; however, see following sections about how to integrate a third-party push server that can support this.

Table 1 explains the parameters of this method.

Table 1. Parameters of the HTTP POST method for sending Newsstand notifications

Using CURL and cron, it is possible to automate this method:

CURL Usage:

Or, you can send the Newsstand notify via this webform that Adobe is providing for your use.

Figure 5 illustrates this method:

Once everything is in place, follow these steps to test your implementation of push notifications and Newsstand background downloading:

1. Install your viewer application.
2. Launch your application and accept push notifications from the dialog box. As noted earlier, this will not show if the user has already opted in. You can verify by inspecting Settings->Notifications on the target device.
3. Make sure that a subscription is active and enabled. For Apple subscriptions, purchase one or choose "Restore Purchases" from the settings menu. For direct entitlement, sign in. Unless notifications are built into a dynamic banner, there really is no way for users to know whether their devices have a subscription that is active and valid.
4. Leave the app. It can be left running in background or forced closed.
5. Open the Newsstand folder.
6. Within iTunesConnect, create an in-app purchase item, assign it a productId and price tier. If testing in the sandbox (not a production app), leave the in-app-purchase item as "Waiting for screenshot".

   Note: Development builds of viewers connect to Apple’s APNS system via the sandbox. Because Adobe’s push server is connected via the production channel to Apple APNS, you will need to create a special productId to test on a development build. Using a productId that begins with ‘dev_test.’, you can use Adobe’s Folio Producer to send a Notify to your development viewer.

7. Within Adobe's Folio Producer, publish some content as "Retail/Public" and assign it the same productID as defined in the step above.
8. At this point, you have published a folio. If you were to open the application on the device and view its library, you would see the new folio as available for download. Do not do this.
9. Send a APNS message containing "content-available:1" to the device. If using Adobe's APNS system, highlight the folio row and press "Notify", or use this webform.
10. It may take a while for Adobe's service to send the push message to all of the registered tokens. Once your device receives the message, it will download it and then update the cover image and sash.

You can also use a third-party push provider such as Urban Airship. This may give you more flexibility and add capabilities such as the ability to send messages to users via push notifications. Publishers can leverage Urban Airship's basic notification framework within Adobe DPS applications with minimal effort.

Visit the Urban Airship site to see more information about Urban Airship's offerings and to sign up for their service.

Requirements

You must host PHP files on a publicly accessible server and have a valid account at Urban Airship.

• Download required files

Implementation

1. Host the uaproxy.php file on a publicly accessible server. The URL to this file, including the filename, should be provided as the "Push URL" when creating the viewer within Viewer Builder. No additional parameters should be provided. Be sure to leave the Use Adobe Push box unchecked.
2. Modify settings.php to contain the values for your Urban Airship account:

• $user : Urban Airship Application Key
• $pass : Urban Airship Application Secret or Master Secret

3. To send messages, you can use the file index.html. This performs a broadcast to all registered devices.
4. Optionally, select the Newsstand Notify checkbox to initiate a background download.

Details

The uaregister.txt file contains a JSON payload that will be sent along with the device registration to UA. The only required property is an alias . Please create your own.

You must create your own Urban Airship account and provision it with a proper APNS certificate from the iOS Provisioning Portal.

Testing

To send a text message, enter one at index.html and press Send Notify Now. You can send as many messages as you like.

For background downloading to work, note that:

1. Only the most recent folio can be downloaded.
2. The user must be entitled either via an Apple subscriptions or direct entitlement (CDS, TCS, PCD, Dovetail, etc.)

Beginning with release 18, enterprise publishers can replace Adobe DPS's APNS server with their own implementation (for example, java-apns). This allows publishers to send text messages and to use any commercially available provider for push.

Two main processes are required to push: Registration and Notification. This document will greatly simplify these processes. For additional information, please see the Apple Push Notification Service.

Registration

Whenever an APNS-enabled, customized viewer is activated, it attempts to register with its APNS provider. This registration is sent as a multi-part HTTP POST with the parameters shown in Table 2:

Table 2. Parameters for the registration HTTP POST method

Sample PHP registration code:

Sample Java registration code:

Notification

APNS messaging is an Apple iOS–level feature. Only in the case of Newsstand notification will the viewer participate in the notification. All messages should be formatted as JSON packages. For examples, please see Examples of JSON Payload in the Apple Developer Center.

Table 3. Parameters for APNS messages

Notes about Newsstand background downloading

1. Background downloads are limited to once every 24 hours, +/- 1 hour (or so). You can send as many alert messages you like, but only background downloading will be throttled.
2. Background downloading will only happen over WiFi connections. If the user is on 3G and the push is received, the background download is lost.
3. A valid subscription via Apple or direct entitlement (CDS, TCS, PCD, Dovetail, or other) must exist.
4. Only the most recent folio will be background-downloaded. The user must be entitled to this content.
5. Apple attempts a number of times to deliver the push payload. As such, the actual download may begin a significant amount of time after it was originally sent or scheduled.

See the following information on push notifications from Apple:

• Apple's detailed documentation about its Push Notifications Service
• Apple's documentation on iOS provisioning