Prerequisite knowledge
 
User level: Intermediate
 
Required products
 
Additional required other products
 
Source Distribution
 
The Amazon AMI is pre-loaded with a fully functional example implementation.  This Java Web App archive is provided for extending and customizing.
 
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 DPS forum. Please don’t contact technical support with questions about Adobe Developer Connection articles.

 

 
Introduction

With Adobe DPS, push notifications can be used to trigger background downloads of folios, as well as broadcast messages to all of your readers. This can help drive engagement and improve subscription and single issue sales. It would be even more powerful if you could send custom push notifications to a specific segment of your readers – for example, only to readers who have not opened your app in the past 6 weeks. Adobe will be adding a segmented push feature to DPS in the near future, but this example implementation may be useful to you if you want to experiment today. Notification Station presents an example implementation combining consumer data collection, Apple iOS Push Services and Omniture Web Services into a single Amazon Managed Instance (AMI) ready for publisher customization. The AMI can be used to send broadcast or segmented Text Alerts or Background Download Notifications to DPS Push Enabled applications. Segmented data sets can be created via Omniture Web Services when valid credentials are provided. Also, personalized consumer information can be collected with the provided web forms when embedded within a DPS application. Additionally, segmented data containing device identifiers and personally identifiable information can be exported (CSV) for inclusion with other (e.g. email, marketing) systems.
 

 
Overview

This article describes an example implementation that is ready for customization to your specific requirements. Communication with Apple’s Push Notification Service (APNS) is provided via either of the following connectors: Urban Airship, Push.IO or a built-in open source library (JavAPNS). (Note: Usage of the Urban Airship or Push.IO connector requires a valid account at the respective provider.)
 
Figure 1 - Overview of DPS Notification Station

Figure 1 - Overview of DPS Notification Station

 

The implementation sends text alerts immediately while pacing all Newsstand/background download notifications in accordance with Adobe’s recommendations.
 
The solution works with the concept of an ‘APP’. An ‘APP’ defines an explicit relationship between a Apple Bundle ID (aka Application ID, Title ID) and the authenticated Adobe ID. Administrative users are users who have logged into the Notification Station using an Adobe ID that contains an Application Role. Administrative users can create/delete multiple ‘APPS’ that are all connected to a common Adobe ID. As such, a typical dashboard may contain a few ‘APPS’ that all pull Folio data from the same Adobe ID – but they would have to have different Bundle IDs (Application IDs).
 
Figure 2 - Possible set of APPs

Figure 2 - Possible set of APPs

 

Administrative users can optionally define a ‘Marketing’ user prior to creating an ‘APP’. This Marketing user can then log into the system to segment data and/or send text or background downloads. Only Administrative users can define/remove ‘APPS’. This is done so you need not share sensitive Adobe ID credentials.
 
Notification Station comes packaged with web forms that collect personalized information from consumers. This information (email, zipcode, first and last names) is associated with the reporting device and persisted along side the push token. This enables sending specific messages to specific users. The implementation contains forms for the Entitlement Banner, Custom Storefront (or Library), Post-subscription dialog and Digital Blow-ins.
 
Figure 3 – Data Capture within the Entitlement Banner

Figure 3 – Data Capture within the Entitlement Banner

 

Figure 4 – Data Capture within the Post-Subscription Dialog

Figure 4 – Data Capture within the Post-Subscription Dialog

 

 
Authentication

This implementation uses Java Authentication and Authorization Service (JAAS) framework as the basis for authenticating administrator, marketing and super users. There are 2 main roles – admin and marketing. For Admin users, the implementation queries Adobe’s Account Management System (AMS) to authenticate and request information about the supplied Adobe ID. Administrative users have access to all functionality – but are restricted to only the APPs they have created.
 
Marketing users are authenticated internally to the application and only have access to APPs that the Administrative user granted them. Specifically, they can not create or delete APPs.
 
A super-user is an authenticated admin user whose Adobe ID is also contained within the ‘super’ MySQL table. A super-user can view all APPs that have been created, but can not initiate activity.
 

 
Creating your instance

We have published a public AMI that has everything preloaded. You will need to log into your Amazon Web Service account.
 
  1. We have published a community contribution to the AWS AMI Catalog.  To launch this instance into your account, follow this link. 
    http://aws.amazon.com/amis/dps-notification-station
Figure 5 - Notification Station Manifest

Figure 5 - Notification Station Manifest

 

  1. Launch the AMI. You will be able to choose which region.
Figure 6 - Launching the AMI

Figure 6 - Launching the AMI

 

  1. Select Continue to accept the defaults on the next few screens.
Figure 7 – Choosing the AMI

Figure 7 – Choosing the AMI

 

  1.  
Figure 8 - Instance details

Figure 8 - Instance details

 

  1.  
Figure 8.1 – Instance details (continued)

Figure 8.1 – Instance details (continued)

 

Figure 8.2 – Instance details (continued)

Figure 8.2 – Instance details (continued)

 

  1. Choose a key pair. If you do not have any (typical), then choose “Create a new Key Pair”.
Figure 9 – Creating key pairs

Figure 9 – Creating key pairs

 

  1. Setup a new security group (unless you already have one).
Figure 10 - Configure Firewall Settings

Figure 10 - Configure Firewall Settings

 

a. Give it a name and description.
b. You will need to do the following for each of the ports you want to open up. These ports are SSH (port 22), HTTP(80), and MYSQL(3306).
  i. Select “Create a new rule”; select either SSH, HTTP or MYSQL; then press the “Add Rule” button.
c. Also add the FTP port. “Create a new rule” and select the “Custom TCP rule” and enter port 21. This is the FTP port and is not in the pre-defined list. Press the “Add Rule” button to add it.
  1. Once complete, select Continue.
Figure 10.1 – Configure Firewall Settings (continued)

Figure 10.1 – Configure Firewall Settings (continued)

 

  1. Now…Launch your new instance based upon mine.
Figure 10.2 – Configure Firewall Settings (continued)

Figure 10.2 – Configure Firewall Settings (continued)

 

  1. After it is launched, note the subdomain name of your instance. You will need this for later.
Figure 11 - Your Instances on EC2

Figure 11 - Your Instances on EC2

 

 
Configuring your AMI

At this point, the AMI is functional but requires some configuration. Using a SSH Shell (see “Connecting to your AMI” below), modify the following file as necessary:
/usr/share/tomcat7/webapps/marketpush/WEB-INF/config.properties
 
Property Description Example Required
hostname The hostname where the application is hosted. ec2-54-219-36-129.us-west-1.compute.amazonaws.com Required
app.version A modifier displayed next to the title. Beta 1, Development Only Recommended
app.title Title of Application DPS Notification Station Required
omniture.username Omniture Web API username used for accessing Omniture data.   Optional
omniture.password Omniture Web API password   Optional
Once complete, you will need to restart Tomcat. Type the following command into the terminal shell:
sudo service tomcat7 restart
At this point, you are good to go.
 

 
Connecting to your AMI

 
Connecting via FTP
I use Fetch (http://fetchsoftworks.com) on my Mac. Any FTP client should work, but I know that Fetch does. Use the following credentials to connect to the FTP server on your Instance.
 
  • Hostname: Enter the complete subdomain name of your AWS AMI.
  • (e.g. ec2-184-169-254-236.us-west-1.compute.amazonaws.com).
  • Username: ftpuser
  • Password: password
Figure 12 – Connecting via FTP

Figure 12 – Connecting via FTP

 

 
Connecting via SSH
When we created the security group prior to launching the AMI, we added SSH (Secure Shell). Using the public/private key PEM file you downloaded at the beginning of this process, log into your new Instance.
 
Open up a terminal window on a Mac (you can obviously do this this with any SSH client, but I use Terminal and Bash SSH).
 
At the command prompt, type:
ssh -i <yourpemfilename> ec2-user@<your_subdomain_name>
(eg. ssh -i sdreierkey_for_AWS.pem ec2-user@ec2-50-18-246-133.us-west-1.compute.amazonaws.com)
 
You will want to ensure that your PEM is only owned by you. The AMI instance may complain if not. To fix, type: chmod 400 <your pem file>
 
 
Once Connected
Tomcat is installed at:
/var/share/tomcat7/
 
Notification Station (aka marketpush) is installed at:
/var/share/tomcat7/webapps/marketpush
 
Logging is at:
/var/log/tomcat7/catalina.out
 

 
Usage

 
Create an APP
Choose “MANAGE APPS AND USERS” from the main menu.
 
Figure 13 - Main menu - Manage Apps and Users

Figure 13 - Main menu - Manage Apps and Users

 

If you would like to define a “Marketing” user, do so BEFORE you create any apps. Choose “Add/EDIT Users” and then Select “ADD”. Fill in the dialog and select “Create”.
 
Figure 14 - Create and Add Marketing User

Figure 14 - Create and Add Marketing User

 

Now Select “ADD/EDIT APPS” and then select ADD. Fill in all the information – taking care to choose the type of APNS provider you intend to use. The SSL (.P12) file is the SSL APNS certificate you exported from your Key Chain. It contain information about the Bundle ID (aka application ID, title ID), whether its for sandbox or production and when it expires. All of this will be read from the SSL certificate and be used to manage the application. If you defined a Marketing User, you can select it now. Once complete, select “ADD”.
 
Figure 15 - Create new JavAPNS based APP

Figure 15 - Create new JavAPNS based APP

 

Validation is done on the SSL certificate and if accepted, an entry will be provided within the “MANAGE APPS” view.
 
Figure 16 - Listing of existing apps

Figure 16 - Listing of existing apps

 

Note: If you had correctly configured the ‘hostname’ field of ‘config.properties’ earlier, the correct URL will be displayed in the Push URL box. This information is purely informational and should be used to cut+paste into the 3rd Party Push URL in DPS App Builder.
 
From here, you will need a 3rd party Push enabled DPS application. Once you have it installed on some devices, we can send notifications.
 
Figure 17 - Send an Alert Notification

Figure 17 - Send an Alert Notification

 

Or we can choose to trigger a Newsstand Notification. Choose your application and the Folio/Product ID that you wish to have background downloaded to the application.
 
Figure 18 - Send a Newsstand Notification

Figure 18 - Send a Newsstand Notification

 

If you have provided Omniture Web API credentials, then you will be able to create Segment Data Sets. This data takes approximately 30 seconds to be created. Once complete you can choose to download a CSV representation of the segment OR send a Text Alert immediately.
 
Figure 19 - Create/Export Segment Data

Figure 19 - Create/Export Segment Data

 

The exported CSV will contain a line for every device ID registered that was found to be in the Segment.
 
Figure 20 - Exported Segment Data

Figure 20 - Exported Segment Data

 

 
Adding a Custom Push Provider

The solution comes with connectors to JavaPNS (Open Source), Push.IO and Urban Airship. If you would like to add your own, the steps are fairly simple.
 
  1. Subclass ‘com.adobe.dpsenable.marketpush.provider.PushTaskBase’ and override the following methods:
    1. a. notifyNewsstand – This method will be called to send groups of tokens for background download.
    2. b. notifyText – Used for sending Alert notifications
  2. Modify ‘com.adobe.dpsenable.marketpush.provider.APNSProviderFactory’ in order to have your new class instantiated.
  3. Modify ‘WebContent\manage\CreateAppView.js’ to have your new option added to the APNS Provider Select control.
  4. Add the modifications your implementation demands to CreateAppView form, as well.

 
Security

This AMI has been provided as an example implementation. I strongly recommend getting the Java source and customizing the code as needed for your environment.
 
Since you created your own private AWS AMI from a common, publicly available AMI, I strongly recommend changing passwords and/usernames. Or to put it another way – every publisher that deploys this EC2 instance will all have the same FTP access.
 
Another good customization is to turn off the MYSQL port (3306) by removing it from the security group you created and re-booting the instance. As you may have noticed, we didn’t need to do anything to customize or setup the MYSQL instance. All database creation and management was provided with the AMI. For reference, username/password for MYSQL is ‘root’, (no password) in case you want to inspect it or customize it.
 
SSH access is only available to those in possession of the public/private key file (.PEM), so you do not need to change that.
 
Finally, when you are comfortable with this AMI, you SHOULD purchase a reserved instance from Amazon so that you can have:
 
  • Always on availability. Devices can register 24/7/265.
  • A non-changing domain name. Every time you stop/restart your AMI, you will get a different domain name which is incompatible with device registration.

 
Where to go from here

Amazon cloud services are a paid service. I strongly recommend familiarizing yourself with the different payment terms. It is likely that you will want to create a ‘Reserved Instance’. This allows you to make a single yearly (or 3 year) payment at significant cost savings.
 
See the article Best practices for driving readership with Digital Publishing Suite for an overview of the many approaches you can use, in addition to segmented push, to drive readership of your DPS titles.
 
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.