Using Urban Airship as a DPS Push Provider

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.

The connector distributed with this article captures device registrations from your DPS Application and then registers each device with Urban Airship.  When sending a push message (either for Newsstand or an Alert), devices are retrieved from your application at Urban Airship, stored in a MySQL database; and then periodically sent back to Urban Airship in chunks.

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.

Sending Notifications

This distribution supports 2 types of push notifications – Text Alerts and Newsstand.  These are mutually exclusive, but can be sequenced.  We block sending both in the same payload because it can cause problems with Newsstand downloads if the user taps an Alert notification which causes the application to open.

When a push notification is requested, the following process is commenced.

1. All registered device tokens are requested from Urban Airship.  Any that are ‘active’ are stored to a database table named ‘devices’.  This table is dropped and created for every new push request.
2. The message and/or the productId for Newsstand background download are written to the same database and stored in the table ‘notification’.
3. A cron entry is created.  This entry will call ‘sender.php’ every minute.  Output from this process is logged to ‘/tmp/cron.log’.
4. The cron process ‘sender.php’ will attempt to send ‘n’ devices (currently ‘n’=400) every time it is invoked.  This will continue every minute until all active devices have been messaged the notification.
5. Once complete, the cron entry is removed. Specifically, the entire cron table for the owner of the PHP process (e.g. apache, www) is removed.

When a notification sequence is in process (i.e., there are pending devices to be delivered), no new notification is possible.

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 devices notifications are sent to Urban Airship in blocks (currently 400 at a time) every 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 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.
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 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.

See the following information on push notifications from Apple:

• Apple's detailed documentation about its Push Notifications Service
• Apple's documentation on iOS provisioning
• Adobe DPS iOS Publishing Companion Guide