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

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.

Figure 3. Notify button in Folio Producer to initiate a push notification

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 which folio is the most recent. This is the one that will be used for background download.
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.)
Fetch the preview image and update the cover in Newsstand.
Fetch the folio.
Update the "New" sash on the preview within Newsstand upon successful completion.

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 blue sash will be displayed over the upper-right corner (see Figure 4).

Figure 4. Publications in Apple Newsstand. The blue sash 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.
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.
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. Do not do this.
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 sash.

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 generic alert. Note: Alerts are never sent by Adobe DPS APNS

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.

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.

12/17/2012

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

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License. Permissions beyond the scope of this license, pertaining to the examples of code included within this work are available at Adobe.

Using Apple push notifications with Digital Publishing Suite

by Scott Dreier

Content

Modified

Page tools