15 October 2013
User level: Intermediate
Additional required other products
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 comments feature at the bottom of the article. Please don’t contact technical support with questions about Adobe Developer Connection articles.
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.
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.)
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).
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.
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.
We have published a public AMI that has everything preloaded. You will need to log into your Amazon Web Service account.
|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.|
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:
|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.
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.
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 firstname.lastname@example.org)
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>
Tomcat is installed at:
Notification Station (aka marketpush) is installed at:
Logging is at:
Choose “MANAGE APPS AND USERS” from the main menu.
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”.
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”.
Validation is done on the SSL certificate and if accepted, an entry will be provided within the “MANAGE APPS” view.
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.
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.
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.
The exported CSV will contain a line for every device ID registered that was found to be in the Segment.
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.
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:
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.
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.