Prerequisite knowledge
 
This article requires that the reader have a knowledge of custom storefronts in DPS. In addition, the user should have a knowledge of Apple Push Notification system protocols and how to use a third party push provider such as Urban Airship.
 
User level: Intermediate
 
Required Adobe products
 
  • Adobe DPS Enterprise account
  • iOS DPS App with custom storefront

Additional required other products
 
By downloading software from the Adobe Web site you agree to the terms of our license agreement. Please read it before downloading.
 
Note: If you have questions about this article, use the comments feature at the bottom of the article. Please don’t contact technical support with questions about Adobe Developer Connection articles.
 

 
Introduction

Many brand owners want to leverage push notifications in their DPS apps to deliver relevant information to their readers when the readers are not using the app. While many publishers use push to inform readers of new issues, others use push to warn readers of inclement weather or breaking news. Adobe provides an interface to let brand owners compose and send Newsstand push messages for new issue availability. Recently, Adobe introduced a text messaging interface that lets brand owners send text messages to their apps regardless of whether they are in the Newsstand. The DPS built-in push notification solution  only allows users to send text and Newsstand push messages, but Apple provides for more options. This article will explore how to trigger custom sounds in your iOS DPS app via push notifications. You will need a DPS Enterprise account and an app that features at least one custom storefront.
 

 
Push Primer

Apple provides a method in iOS to send push notices to apps. These messages can be sent by the app to itself or can be sent by an outside source to the app in order to trigger some event. The apps need to be prepared in a special way in order to prepare them to receive these messages, and this preparation happens in the iOS Developer portal. Once properly configured, the app can then respond to push messages. How the app responds depends on how the developer has coded their app to handle incoming push notices.
 
DPS apps can handle basic push notifications when the notices are sent from outside of the app. You can use badging (numbers that appear on the app icon), text messages (messages that appear in your notification tray when the app is out of focus or when the device is asleep), and custom sounds. Push notifications can also trigger background downloading of folios in a Newsstand app, but we are not going to cover that use case in this article. To learn more about Newsstand push and DPS, please read Bob Bringhurst’s article about setting up a Newsstand app in iTunes and Scott Dreier’s article about setting up Push Notifications.
 
Once your app is configured to receive push notices and your app is deployed through iTunes, you can then begin to send messages to the app. While you can use Adobe’s push notification server for text messaging, you need to use a third party provider to take advantage of badging or custom sounds. For this article, we will use Urban Airship and will reference Scott Dreier’s article about using Urban Airship as a push provider. In addition, we will provide a modified form for use with Scott’s example UA server to enable sound and badging.
 
 
Preparing for Push
Apple prevents us from showing screen shots of the Apple Developer portal, so we can not provide step by step instructions for preparing your app for push notifications. Nevertheless, the following is a set of steps you can follow to enable push notifications in your app. In addition, you should read Apple’s documentation at the iOS Developer Portal to ensure completeness around the various interdependent parts.
 
You need to add Push Notifications to your App. For detailed instructions from Urban Airship, see their documentation. In lieu of reading that, follow these abbreviated instructions for creating the required certificates for Push Notifications.
 
Go to the Certificates, Identiers and Profiles section and choose Identifiers. If you are making a new app, click the plus sign to add an app. If you are adding Push to an existing app, then select it from the list. Under App Services at the bottom, you will see Push Notifications. Enable it and follow the instructions to create your Development and Production Push certificates. You will need both. Once you have your Push certificates (they have a .cer extension), you will need to add them to your Keychain so that you can export them to a .p12. You can double click the .cer to add it to your keychain or use File>Import Items… to add them to your Keychain.
 
Push Certificates only last one year, so you will need to return to the Developer Portal and create new Push certificates at least once per year. This will also mean new Mobileprovision files and also a new app that will need to go through Apple review if you want to continue to use push beyond that first year.
 
Once the certificates are in your Keychain, they will appear in “My Certificates.” There will be two certificates: one called Apple Development iOS Push Services and one called Apple Production iOS Push Services. You will need each of these in order to communicate with your app using push notices, and the key to this communication is a .p12 file that will be stored in the proxy server.
 
To create the necessary .p12 files, select each certificate (not the identites that were used to make them), right click or control-click, and choose Export. Save each .p12, being careful to include the word “development” or “dev” in the Development .p12, and the word “production” or “prod” in the Production .p12. This will help you identify them later. Also, DO NOT FORGET THE PASSWORD YOU USED TO CREATE EACH OF THESE .P12 FILES. You will need the password later! You should create a folder to store all of the iOS Developer files to make them easier to locate when you need them.
 
Exporting the proper certificates from the Keychain as .p12 files
Figure 1. Exporting the proper certificates from the Keychain as .p12 files
 
 
Now, return to the iOS Develper Center and create Mobileprovision files for your app. Be sure to choose the push-enabled AppID when you create your new Mobileprovision files. If you already have an app, then you will need to re-create your mobileprovision files. Download your Development and Distribution mobileprovision files and save them in the folder with your Push .p12 files.
 
 
Creating an app at Urban Airship
Urban Airship will act at the broker between your app and Apple. In addition, we will configure our app to talk to a proxy that will keep Urban Airship informed about the devices that are ready to receive push notifications. In addition, we can use this proxy to send messages through Urban Airship to Apple, and then to our apps on iPads.  For our proxy, we will use Scott Dreier’s UAProxy code from his comprehensive article about using Urban Airship as a third party push provider. If you haven’t read that, go read it now.
 
Urban Airship allows you to create one or more apps within its system. You need to have an Urban Airship account, which is free for users who send less than a minimum number of push notices per month. As of this writing, the threshold is 1 million pushes, so if you will send less than 1 million pushes per month, then the service will be free. You will need to provide a credit card number when you set up the account, in case you go over.
In Urban Airship, click the + New App button to add a new app.
 
Creating a new app in Urban Airship
Figure 2. Creating a new app in Urban Airship
 
 
Provide an Application Name, set its Production Status, and select a category for the app. If you like, you can also include your App’s icon so that you will be able to more easily identify your apps in the Urban Airship dashboard. Once you have configured these options, click Add.
 
Fill in the form with information about your app, and click Add.
Figure 3. Fill in the form with information about your app, and click Add.
 
 
Once you have created your app, you need to configure it. Click Configure Now to add your Push .p12 and get your app keys from Urban Airship.
 
Click Configure Now to add your push certificates and get your API Keys
Figure 4. Click Configure Now to add your push certificates and get your API Keys
 
 
You will see a long list of available services. Only iOS DPS apps are wired to receive Push notices at this time, so we only need to configure Apple Push Notification Services, or APNS. Click the Configure button next to APNS to continue.
 
Configure your Apple Push Notification Services (APNS) settings
Figure 5. Configure your Apple Push Notification Services (APNS) settings
 
Do you remember when we told you not to forget your passwords for your .p12 files? Here is where you will need to know that password, since you need to store it in your Urban Airship configuration. Be sure that you load the Production .p12 into your Production app, and your Development .p12 into your Development app. Urban Airship requires that you have separate apps for Development and Production, so you wil llikely make two apps. When you have entered the required password and .p12, click Save.
 
Add your .p12, enter the password, and click Save.
Figure 6. Add your .p12, enter the password, and click Save.
 
When complete, you will see that the APNS section of the services panel will be black instead of gray, and you will see an indicator of when your certificate will expire.
 
Services are now properly configured
Figure 7. Services are now properly configured
 
Once your certificate and password are stored, you can fetch your API keys that you will need for Scott’s UAProxy. Click the API Keys button in the Settings panel on the left hand side of the screen to see your API Keys. You should copy the App Key and the App Master Secret, which will be required in the UAProxy app.
 
Copy your App Key and App Master Secret for use in the UA Proxy code from Scott Dreier
Figure 8. Copy your App Key and App Master Secret for use in the UA Proxy code from Scott Dreier
 
 
Setting up the UAProxy
If you haven’t already done so, go download Scott Dreier’s UAProxy code from his Using Urban Airship article. While we supply a version of that code as the example code for this article, you should check with Scott’s article to ensure that you have the latest underlying code. The example code we provide with this article has been modified to allow you to send badges and sounds, so if you do go get Scott’s code, be sure to update the index.php file to include the form fields for badge and sound, and also to update lines 133 and 137:

 
Line 133: if (!empty($_POST['message']) OR !empty($_POST['badge']) OR !empty($_POST['sound'])) { Line 137: $json['aps'] = array("alert"=>$_POST['message'],"badge"=>$_POST['badge'],"sound"=>$_POST['sound']); Lines 188-209: <fieldset> <legend>Create Notification(<span class="app-label"> <?php echo $appId; ?></span> )</legend> <p> <label>Newsstand:</label> <input id="newsstand" name="newsstand" type="checkbox" onchange="onNewstandChange(this)" /><br/> <label>Folio/ProductId:</label> <input id="productId" name="productId" value="" type="text" size="40" maxlength="40" /> <br/><br/> <span font-size="8">&nbsp;&nbsp;&nbsp;or</span> <br/><br/> <label>Alert Message:</label> <textarea id="message" name="message" wrap="soft" value="" size="236" maxlength="236" cols="77" rows="4" placeholder="Enter notification text here..." ></textarea> </p> <label>Badge:</label> <input name="badge" type="text" id="badge" placeholder="Enter auto, +1, -1 or a number" size="40" /> <br/> <label>Sound file name:</label> <input name="sound" type="text" id="sound" placeholder="Enter a file name here" size="60" /> <br/> </fieldset>
 
Having acquired the example code from this article or having modified updated code from Scott’s arricle, you now need to add your API keys to the settings file. Open settings.php in a text editor and replace the UA Application Key and UA Master Secret with the Key and Secret from your app at UA. Save and close the settings file.
 
Figure 9. Paste your UA Application Key and UA Master Secret into the settings.php file for deployment
Figure 9. Paste your UA Application Key and UA Master Secret into the settings.php file for deployment
 
Once you have adjusted the settings, you can upload the entire uaproxy folder to a publicly available web site. You will need to have a unique path to uaproxy.php for each app you create, so be prepared to make multiple copies of the uaproxy folder if you have multiple apps. Also, you will need to upload settings for your Development app, and then replace them with the Production settings once you have done your testing. You may also want to put a login in front of the index page to prevent unauthorized users from sending push notices to your apps without your permission. Make note of the URL to the uaproxy.php file for each app, as you will need that when you make your app in App Builder.
 

 
Sounds and Badges

Apple Push Notifications can be text messages, badges, sounds, and can even tell the app to perform some action or could deliver content to the app. Newsstand leverages push to send a new folio to the app when the iPad is closed. In this article, we are interested in badges and sounds, however, so we will look a little more closely at those two items.
 
When you compose a push, the actual push payload is a json encoded array that tells the push notification system what message to send to which devices. Urban Airship acts as a proxy for us, keeping track of all of the devices that have our app installed and which ones have agreed to let us send them push notices. The payload can consist of many different key value pairs, but the ones we’ll focus on are “badge,” “alert,” and “sound.” Learn more about push payloads at Apple’s Local and Push Notification Programming Guide.
 
 
We don’ need no stinkin’ badges!
Well, maybe your app does need a badge. Badges are the numbers that appear on the app icon on your iPad’s home screen. The numbers can increment automatically in respond to repeated pushes (like a newspaper that might send down breaking news items to readers through push) or can be set to specific values or reset altogether. Adobe DPS built-in push does not support badging outside of Newsstand, but Urban Airship does support badging.
 
To send a badge using Urban Airship, you need to include the key “badge” with a value attached to it in the “aps” entry in the payload. With Urban Airship, the value can be an integer value, “auto” to enable auto incrementing values, +1 to auto increment, -1 to auto decrement, or 0 to clear the badge. The form from our example index.php file includes a field for a badge, so you can send either of the aforementioned values to your app and badge the heck out of it.
 
 
Do you hear what I hear?
Push notices can also trigger sounds to play. The sounds need to be embedded in your app, and you need to know the path to the sound file relative to the root of your app. Sounds can be in aiff, wav, or caf files. Also, they need to be 30 seconds or less. According to Apple’s Preparing Custom Alert Sounds page, you can use the afconvert command line tool to create properly formatted sound files using the following command:
 
afconvert /System/Library/Sounds/Submarine.aiff ~/Desktop/sub.caf -d ima4 -f caff -v
 
If you are a Creative Cloud customer, you can use Adobe Audition CC to convert sounds to caf format. Open your sound file, trim it to under 30 seconds, and choose File>Export>Export File… Select Apple Audio Toolbox as the format, and confirm that the format settings read CAF. Click OK to export your sound.
 
From Adobe Audition CC, choose Apple Audio Toolbox as the file format from the Export dialog
Figure 10. From Adobe Audition CC, choose Apple Audio Toolbox as the file format from the Export dialog
 

 
Let’s Put this Show on the road!

Now, we need to get the sound into our DPS app and configure the app to receive push notifications. In order to get the sound into a known location in the app, the sound needs to be stored in a custom storefront. Since iPhone apps can only use one custom storefront slot, we recommend putting your sound files into the first custom storefront slot of an iPhone/iPad app. We will use the App Builder to put all of the pieces in place.
 
Your sound needs to be in a known location with respect to the root of the app on the device. Assuming that you have a custom storefront, put your sound file(s) adjacent to the index file of your custom storefront. When you zip the storefront, ensure to select the sound files as well as the index.html, css, images and js files.

 
In this example, there are three sound files bundles along with the rest of the custom storefront. The sound files (yep.caf, lookatme.caf, and bells_01.caf) are at the root level of the storefront, whose index page is called “page1.html”
Figure 11. In this example, there are three sound files bundles along with the rest of the custom storefront. The sound files (yep.caf, lookatme.caf, and bells_01.caf) are at the root level of the storefront, whose index page is called “page1.html”
 
 
When you build your app with App Builder, replace the existing Custom Storefront in slot one with this new Custom Storefront that includes your custom sound(s). When you place your sounds in slot one, then the path to your sound file (for triggering the sound with Apple Push Notification) is: /global/ui-extensions/toolbar-buttons/1/your_sound.caf
 
In addition to including the sound files in the storefront slot, you also need to include the path to your uaproxy.php in the Push Notifications section of App Builder. Ensure that you  load your NEW mobileprovision files into App Builder, then check Enable push notifications and include the full URL to your uaproxy.php. You will notice that there is only one path to uaproxy.php, so you should deploy settings for your Development app first, do your testing, and then replace the values in settings.php with the Production values when you release your app in iTunes Connect.
 
Enable push notifications in App Builder and be sure to include the path to your published uaproxy.php page
Figure 12. Enable push notifications in App Builder and be sure to include the path to your published uaproxy.php page
 
 
Once you have built your Developer and Distribution apps, you can test and ultimately deploy your app to iTunes Connect.
 
 
Triggering badges and sounds
When you use the form in the UA Proxy index.php, you can then include the full path to the sound file in the payload (/global/ui-extensions/toolbar-buttons/1/your_sound.caf). This will trigger the sound to play when your app receives the notice. You can also set a badge or send a text message. Apple recommends not overusing your power of push, however, as it is easy to annoy your reader with too many messages. Ensure that your messages are relevant, timely and add to the overall app experience that you are trying to create.
 
With the form filled out as below, the expected result when we click “Send notification” is:
 
  • The message “Welcome to push notices with sound!” will appear in the notification center
  • The badge number will increment by one
  • The sound “bells_01.caf” will play

Using the modified push notification form accessible from index.php that is included with the example files
Figure 13. Using the modified push notification form accessible from index.php that is included with the example files
 

 
Where to go from here

DPS apps can receive push notifications via Apple Push services. While Adobe DPS customers can use Adobe’s built-in notifications service, richer options are available through third party providers. While we have explored badges and sounds in addition to text messages, there are other options you may wish to explore, such as scheduling, reader segmentation for messaging, and more. Our example is built on V1/V2 of the Urban Airship API, and there are additional options available with V3.  Learn more about the Urban Airship API options in their API Reference.
 
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.