Using Apple push notifications with Digital Publishing Suite

ANNOUNCEMENT:

Reminder - Digital Publishing Suite (DPS) will End of Life on August 31st, 2019.

Show details ›

by Scott Dreier

Overview of Apple Push Notifications
How Adobe Digital Publishing Suite push notifications work
Requirements for push and Newsstand background downloading
Scheduling Adobe push notifications
How to test push notifications and background downloading
How to use your own push server or other third-party push provider
Where to go from here

Created

14 September 2013

Additional required other products

Access to the Apple iOS Provisioning Portal for your app (sign-in required)

If not using the Adobe Digital Publishing Suite push provider server, you will need access to a third-party push provider, or create a push provider on your own server
Java open-source push server: java-apns

User level: All

Original publication date: 03/15/2012

Modified: 09/14/2013 (Change log)

Adobe products

Digital Publishing Suite, Enterprise Edition

Note: See Using Urban Airship as a Push Provider for server-side code and specific integration instructions for using the Urban Airship push provider.

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.

Overview of Apple 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.

How Adobe Digital Publishing Suite push notifications work

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

Figure 1. Push Notifications—App registration

The user opts-in to receive push notifications, and the app registers with Apple's Push Notification Service (APNS)
APNS sends a unique device token to the app.
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.

In Folio Producer, a notification for Newsstand is manually initiated.
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.
APNS sends actual notifications to devices, and iOS routes the notification to the app.

Figure 2. Basic push process to initiate a Newsstand background download

Supported Push Notifications

With release V28 of the Digital Publishing Suite, both Alert and Newsstand Notifications are now supported directly from the Digital Publishing Suite Dashboard.

To send an Alert (text) Notification, choose Notifications from the left navigation area of the DPS Dashboard. To send notifications to ONLY production apps – choose the ‘Distribution’ from the Application Type chooser. Likewise, choose ‘Developer’ to send ONLY to development/sandbox applications.

Figure 3. Dashboard with notifications

In order to trigger a Newsstand/Background download, select a published folio and choose Notify from the right navigation area. This will send a ‘content-available:1’ with the associated ‘productID’ to all production apps. Adobe limits the rate at which these notifications are sent out so as to not wake all devices simultaneously. It may take several hours to notify all of your devices. It is not necessary to select Notify for each rendition.

Figure 4: Newsstand Notify

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

Fetch a list of all folios published to the fulfillment account.
Determine if the user is entitled to the folio specified. A folio is entitled by either a valid Apple subscription or Direct Entitlement.
(See Direct Entitlement article for more information.)
Fetch the preview image and update the cover in Newsstand.
Fetch the folio.
Displays a light blue dot underneath the new thumbnail within the newsstand application.

Requirements for push and Newsstand background downloading

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:

Your application created in Digital Publishing Suite Viewer Builder must be enabled for Newsstand.
Your application must support Apple subscriptions, at a minimum. It can also support direct entitlement.
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)
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:

<dict>
    <key>application-identifier</key>
    <string>W8E2YLRAWL.com.adobe.sdreier.dpsdev</string>
    <key>aps-environment</key>
    <key>get-task-allow</key>
    <false/>
    <key>keychain-access-groups</key>
    <array>
        <string>W8E2YLRAWL.*<string>
    </array>
</dict>

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 light blue dot will be displayed underneath the updated cover. (see Figure 4).

Figure 5. Publications in Apple Newsstand. The light blue dot will persist until the user has opened the folio for reading.

The following is required for background downloading to work:

An iPad with iOS 5. Background downloads are not supported on previous versions.
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.
If using Apple subscriptions, the user must have a valid subscription active and enabled.
If using direct entitlements, the user must be signed in and the folio must be entitled to that user.
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.

Scheduling Adobe push notifications

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.

URL (HTTP POST): http://lighthouse.adobe.com/dps/push/notify.php
Parameters: adobeID, password, productId

Table 1 explains the parameters of this method.

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

Parameter	Format	Descriptions
`adobeID`	`emailAddress`	The AdobeID corresponding to the fulfillment account for the targeted application.
`password`		The password for the above.
`productId`	`string`	The published Product ID for which a push notification should be sent. Note: At the moment, only the most recently published folio will be background-downloaded.

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

CURL Usage:

> curl -d "adobeid=<youradobeid>" -d "password=<yourpassword>" -d "productid=<a_product_id>" -X POST http://lighthouse.adobe.com/dps/push/notify.php

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

Figure 5 illustrates this method:

Figure 5. One method for scheduling notifications

How to test push notifications and background downloading

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

Install your viewer application.
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.
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.
Leave the app. It can be left running in background or forced closed.
Open the Newsstand folder.
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.
Within Adobe's Folio Producer, publish some content as "Retail/Public" and assign it the same productID as defined in the step above.
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.
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.
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 light blue dot.
It is possible to initiate a background download to a FREE folio. The application must still be in Newsstand though.

How to use your own push server or other third-party push provider

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

Property	value(s)	Description
`newsstandEnabled`	0 \| 8	Registers for Newsstand notifications (8) or not (0)
`badgeEnabled`	1	Registers for badge updates.
`accountId`	`<GUID>`	Uniquely identifies the account that owns this viewer
`token`	`<encodedToken>`	Apple encoded version of the `"devId"`. This is to be used for all communications with APNS.
`soundEnabled`	2	Only default sounds are supported
`devId`	`<UUID>`	Application specific identifier for the device.
`targetDimension`	`<deviceWidth`>x<`deviceHeight`> (eg 1024x768, 2048x1536)	Describes the dimensions of the device registering for push notification.
`alertEnabled`	4	Registers for Text Alerts.

Sample PHP registration code:

<?php 

include 'settings.php';
 
// get base64 encoded device token from POST message
$token = $_POST['token'];
$token = $_POST['newsstandEnabled'];

// Get binary token value
$decodedToken = base64_decode($token);

// Convert to a 64 character string representation
$hexToken = "";
for ($i = 0; $i < 32; $i++) {
  $hexToken = $hexToken . bin2hex($decodedToken[$i]);
}
error_log("hexToken:" . $hexToken);
?>

Sample Java registration code:

package com.adobe.sdreier.push;

import java.io.IOException;
import java.io.OutputStreamWriter;
import java.net.Authenticator;
import java.net.HttpURLConnection;
import java.net.PasswordAuthentication;
import java.net.URL;
import java.util.*;

import javax.servlet.*;
import javax.servlet.http.*;

import org.apache.tomcat.util.http.fileupload.*;
import sun.misc.BASE64Decoder;
/**
 * Servlet implementation class register
 */
public class Register extends HttpServlet {
    private static final long serialVersionUID = 1L;
       
    public void doGet(HttpServletRequest request, HttpServletResponse response)
    throws IOException, ServletException
    {
      String deviceId="";
      String token="";
      Boolean soundEnabled=false;
      Boolean alertEnabled=false;
      Boolean badgeEnabled=false;
      
      if (request.getContentType().indexOf(FileUploadBase.MULTIPART_FORM_DATA)>=0) {
          try {
              DiskFileUpload upload = new DiskFileUpload();
              List items = upload.parseRequest(request);
              
              Iterator itr = items.iterator();
    
              while(itr.hasNext()) {
                  FileItem item = (FileItem) itr.next();
                      
                  // check if the current item is a form field or an uploaded file
                  if(item.isFormField()) {
                    // get the name of the field
                      String fieldName = item.getFieldName();
                      if (fieldName.compareTo("devId")==0) {
                          deviceId = item.getString();
                      }
                      else
                      if (fieldName.compareTo("token")==0) {
                          token = item.getString();
                      }
                      else
                      if (fieldName.compareTo("badgeEnabled")==0) {
                          badgeEnabled = item.getString().compareTo("0")!=0;
                      }
                      else
                      if (fieldName.compareTo("soundEnabled")==0) {
                          soundEnabled = item.getString().compareTo("0")!=0;
                      }
                      else
                      if (fieldName.compareTo("alertEnabled")==0) {
                          alertEnabled = item.getString().compareTo("0")!=0;
                      }
                  }
              }
          }
          catch(Exception e) {
              
          }
          
      }
      else {
          deviceId     = request.getParameter("devId");
          token        = request.getParameter("token");
          badgeEnabled = request.getParameter("badgeEnabled").compareTo("0")!=0;
          soundEnabled = request.getParameter("soundEnabled").compareTo("0")!=0;
          alertEnabled = request.getParameter("alertEnabled").compareTo("0")!=0;
      }
      System.out.println("device: "+deviceId);
      System.out.println("token : "+token);
      System.out.println("badge : "+badgeEnabled);
      System.out.println("sound : "+soundEnabled);
      System.out.println("alert : "+alertEnabled);
      
      BASE64Decoder decoder = new BASE64Decoder();
      byte[] decodedBytes = decoder.decodeBuffer(token);
      String tokenString="";
      
      for (Integer i=0; i<decodedBytes.length; i++) {
          //System.out.println("Token["+i+"] = "+Integer.toHexString(decodedBytes[i]));
          tokenString += Integer.toHexString((decodedBytes[i] >> 4)&0xf);
          tokenString += Integer.toHexString (decodedBytes[i]      &0xf);
      }
      //Database db = new Database();
      //db.insertDevice(new Device(deviceId, tokenString, soundEnabled, alertEnabled, badgeEnabled) );
    }

    public void doPost(HttpServletRequest request, HttpServletResponse response)
    throws IOException, ServletException
    {
        doGet(request, response);
    }

}

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 example, this is a JSON payload to trigger a background download of folio 'foobar': {"aps":{"content-available":1},"productId":"foobar"}.

Table 3. Parameters for APNS messages

Property	value	description
`alert`	`<string>`	The text message to display to the user. No localization arguments are supported.
`badge`	`<number>`	If non-zero, it displays the number on the icon of the application. If zero, no number is displayed.
`content-available`	0 \| 1	Non-zero indicates a Newsstand push message. The receipt of this will wake the viewer to begin a background download. See Notes.
`sound`	`"default"`	Only the default notification sound is supported.
`productID`	`<string>`	Product.
`Id`	`<string>`	Push message identifier. Adobe DPS will send a time tag in msec.

Notes about Newsstand background downloading

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.
Background downloading will only happen over WiFi connections. If the user is on 3G and the push is received, the background download is lost.
A valid subscription via Apple or direct entitlement (CDS, TCS, PCD, Dovetail, or other) must exist.
Only the most recent folio will be background-downloaded. The user must be entitled to this content.
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.

Where to go from here

See the following information on push notifications from Apple:

See Using Urban Airship as a Push Provider for server-side code and specific integration instructions for using the Urban Airship push provider.

09/14/2013

Updated article for the v28 DPS release (September 2013) and added information about new support for text alerts.

12/17/2012

Removed instructions for using the Urban Airship push provider and directed reader to Using Urban Airship as a Push Provider.