Prerequisite knowledge
 
 
Additional required other products
  • Urban Airship development account http://urbanairship.com/
  • PHP 5.2.0 or above (requires ‘json_decode’)
  • MySQL 5.x or above
Original publication date: 12/14/2012
 
Modified: 07/22/2013 (Change log)
 
Required products Sample files
Archive.zip
By downloading software from the Adobe Web site you agree to the terms of our license agreement. Please read it before downloading.
(File last updated on 08/05/2013)
Urban Airship provides services for sending Push Notifications to a variety of devices including Apple, Blackberry, Android and Windows.  This article describes how to leverage Urban Airship’s resources to send DPS alert notifications and trigger Newsstand downloads to iOS devices.
 
Visit the Urban Airship site to see more information about Urban Airship's offerings and to sign up for their service.
 

 
How it works

The connector distributed with this article captures device registrations from your DPS Application and then registers each device with Urban Airship.  Alert Notifications can be sent with either Urban Airship’s dashboard OR with the form provided with this distribution.  Regardless of which dashboard is used, the Alert Notification is sent immediately to all devices.

For Newsstand Notifications, you must use the provided form.  Upon initiation of the notification, the distribution will fetch a block of devices from UA’s database and queue them for notification.  This is done repeatedly until all the registered devices have been sent for delivery.  In order to provide adequate service to these devices, this connector will not broadcast all registered devices immediately.  Rather, groups of devices are sent periodically (every minute) until all the device notifications have been sent.

Note: Upon receipt of a Newsstand notification, a DPS application will immediately contact Adobe’s fulfillment services to begin the download of content (assuming that the device is on Wi-Fi).  Since these notifications are quite small, they can be broadcast to a significant number of devices nearly instantaneously.  In order to provide adequate service to these devices, this connector will not broadcast all registered devices immediately.  Rather, groups of devices are sent periodically (every minute) until all the device notifications have been sent.
 
 
Device Registration
Whenever a DPS application is activated (comes to the foreground), it attempts to register it’s device token.  Doing this frequently ensures that Apple’s Push Notification Service (APNS) keeps the token fresh and active.
 
The distribution included within this article will capture device registrations from the DPS application and then register the device at Urban Airship.  Along with the device registration, a ‘tag’ is associated with the device type.  Current tags are “ipad”, “ipad3”, and “iphone”.  Using the push console at Urban Airship OR modifying ‘index.php’, the publisher can choose to send targeted push messages (either Alert or Newsstand) to the specified ‘tag’.  For instance, you could message only iPhone devices or provide different messages to iPad3 and iPad2 devices.
 
Figure 1: Device Registration

Figure 1: Device Registration

 

 
Sending Notifications
This distribution supports 2 types of push notification – Alerts (text) and Newsstand (background). These are mutually exclusive, but can be sequenced. Apple’s Push Notification System (APNS) will only deliver the most recent notification payload – cancelling any previous notifications. The distribution will not allow you to send a new notification until the current (Newsstand) completes.
 
Alert Notifications are broadcast immediately to Apples delivery network.
 
Newsstand notifications are sent in the following manner:
 
  1. The product ID associated with the notification is stored in the database.
  2. A long running background thread is started:
    1. Grab a new block of devices from UA (usually ~2000)
    2. Send the Newsstand Notification with product ID to only these devices.
    3. Sleep
    4. Repeat until all registered devices have been notified.
  3. Progress can be monitored with ‘status.php’. It can also be reset/terminated from this web form.
  4. While the long running Newsstand notification is being processed, no new notifications can be sent.
Figure 2: Device Notification

Figure 2: Device Notification

 
System Performance Considerations

Upon receipt of a Newsstand notification, a DPS application will immediately contact Adobe’s fulfillment services to begin the download of content (assuming that the device is on Wi-Fi).  Since the notification payload is quite small, many can be broadcast to a significant number of devices nearly instantaneously.  Indeed, this is a feature of using Urban Airship’s broadcast API.  However, this can generate a number of simultaneous requests for folio downloads that exceeds Adobe’s infrastructure’s ability to accommodate.  When this happens, devices will timeout and no background download will happen.
 
Therefore, the device notifications are sent to Urban Airship in blocks (~1500/minute).
 
Please contact your Adobe DPS Enterprise representative before modifying these values.
 
While there are no such performance implications with sending solely an Alert notification, these are also sent in the same manner for consistency.  If you require immediate, broadcast delivery, you can do so via the Urban Airship push console or by making modifications to the distribution.
 

 
Installation and Setup

Installation is easy…
 
  1. Unzip the distribution and upload to your web server. The URL to this file “uaproxy.php”, 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. Configure a MySQL database.
  3. Modify ‘settings.php’ to contain the connection information to MySQL.
    1. ‘$db_host’ – The hostname of the server that is running the MySQL instance (e.g. ‘localhost’).
    2. $db_user – The username for MySQL (e.g. ‘root’)
    3. $db_pass – The password for the above.
    4. ‘db_name’ – The name of the database.  This is up to you.  The distribution uses ‘magazines’, but you can use any.  The tables will be created/dropped as needed.
    5. ‘appId’ – A human readable identifier that is used for display in ‘index.php’ and ‘status.php’.
  4. Modify ‘settings.php’ to contain your account information from Urban Airship.
    1. $user – The “Application Key” from your Urban Airship application.
    2. $pass – The “Application Master Secret” from your Urban Airship application.

 
Testing

Testing Newsstand downloads with Urban Airship is super easy.
 
  1. Publish some content as Public.  It can be either free or retail.
  2. Have the user purchase an Apple subscription (again either free or paid) to ensure that they are entitled to the folio.  Alternatively, use direct entitlement.  The only key is that the folio must be in the download state.
  3. View your library.  Is the folio available for download?  If so, then its entitled.
  4. Exit your app so you are looking at the Newsstand.
  5. With ‘index.php’, select ‘Newsstand’ and provide the ‘productId’ for the folio you want to have background downloaded by Newsstand.  It need not be the most recent.
  6. Press send.
  7. Wait a few minutes for the 400 device notifications/minute to cycle through.
  8. You should see the blue sash and the folio is downloaded.
  9. Too easy.

 
Where to go from here

See the following information on push notifications from Apple:
 
Change Log
 
Updated connector to make the interface with Urban Airship more robust and more scaleable for publications with large numbers of subscribers. Also made the installation process easier.
 

Comments are currently closed as we migrate to a new commenting system.  In the interim, please provide any feedback using our feedback form. Thank you for your patience.