Prerequisite knowledge
 
  • PHP scripting
  • MySQL or other database
  • Javascript, HTML, CSS
User level: Intermediate
 
Required products
 
Additional required other products
 
  • JQuery
Sample files
 
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

We don't need to tell you that collecting Personally Identifiable Information (PII) from consumers, like email, name, zip code, etc. is an incredibly important and valuable aspect of consumer marketing.  If you sell print based publications, you are probably well versed in doing this.  However, with your digital publications, did you know you can do this and more?

Adobe DPS enables you to choose when you collect consumer data; maybe before a customer can download content, after a customer buys a subscription, as a digital blow in, etc.  Once you have collected this information it is very easy to then send targeted push and/or email notifications to specific groups of people, and even to individuals.  

This article will cover the first phase of this, collecting the data.  The second phase, sending the targeted push / emails is covered here.
 

 
Overview

The first step to collecting data, is identifying the device that the user is using, then it becomes easy to associate the collected data with the device.  All devices are assigned unique device identifiers.  This paper will show how to leverage the Library and Store V2 SDK as well as the Reading SDK to collect data that is associated with unique device identifiers.  First, a little background on device identifiers is required.
 
Adobe DPS applications use Universally Unique Identifiers (UUIDs) to identify applications.  This 128bit value is often represented as an ASCII string punctuated by hyphens (eg. 483AE204-2E69-4608-87E6-6E31000321FA). This is not to be confused with the hardware specific UDID which Apple deprecated in iOS5 and which Adobe DPS subsequently discontinued.  The UUID is generated by calling the CFUUIDCreate function of the iOS Core Foundation.  Each UUID is unique to each application on the device.  Therefore, 2 applications on the same device would each have different UUID values.  Similarly, the same application on 2 different devices would also have different UUID values.
 
This UUID value is reported in the "uuid" field of the Direct Entitlement API, the "devId" field of the push notification registration message, the 'deviceId' of the Library/Store/Reading SDK, the 'vid' parameter (Visitor ID) of every Omniture Data Analytics report, and eVar42 of the same Omniture Data Analytics report.  Visitor ID (vid) has always been used to correlate all analytics; however, it was obfuscated at the SiteCatalyst reporting stage because of its sensitive nature.  As of v27 (July 2013), Adobe DPS bypasses this by also reporting the UUID value as a data parameter (eVar42).
 

Property
DataService/API
 
Reference/Documentation
 
uuid
 
Direct Entitlement API
 
http://download.macromedia.com/pub/developer/dps/entitlement/direct-entitlement-api.pdf
 
devId
 
Push Registration API
 
http://www.adobe.com/devnet/digitalpublishingsuite/push-notifications.html
 
vid
 
Omniture Analytics API
 
http://download.macromedia.com/pub/developer/dps/analytics-report/dps-analytics-report-guide.pdf
 
eVar42
 
Omniture Analytics API
 
http://download.macromedia.com/pub/developer/dps/analytics-report/dps-analytics-report-guide.pdf
 
deviceId
 
Library and Store V2 SDK
 
http://www.adobe.com/go/dps-library-store-api
 
deviceId
 
Reading SDK
 
http://www.adobe.com/go/dps-reading-api
 
 
The only difference, in some cases, is that the UUID may have had the hyphens "-" stripped, but numerically otherwise it is the same.
 
With this information, we can now collect whatever we can entice a user to provide, use the JavaScript APIs to access the UUID and report this via AJAX for persistence in a database of our choosing.  The remainder of this article will demonstrate this.
 
Data Flow
Figure 1 - Data Flow

 
Using the Examples

The examples provided with this article have been packaged for usage in a stand-alone LAMP (Linux, Apache, MySQL, PHP) environment. It is expected that all of the visual elements for these examples would be customized for your specific requirements, so we have kept them small and simple.
 
You will need to deploy the samples to a web server (Apache) that supports MySQL and PHP.  For MySQL, you will need to create a database and provide its name, username and password within the ‘settings.php’ file in the root of the examples.  The PHP file (database.php) will create the necessary tables if they do not already exist.
 
Listing of examples
Figure 2 – Listing of examples

 
Collection within the Entitlement Banner

The Entitlement Banner is displayed at the top of the library within direct entitlement enabled applications.  It has full access to the Library and Store V2 API and is a convenient location for active code since it is small and simple and doesn’t require the full development of a customized library or storefront.
 
Our example asks the user to register, validates their input, and posts it to a server database via AJAX.  Once registered, an acknowledgement view is displayed.  The state of the entitlement banner is tracked within localStorage.
 
Entitlement Banner
Figure 3 - Entitlement Banner
 
Entitlment Banner after registration
Figure 4 - Entitlment Banner after registration
 
 
Configuring the Application to use the Entitlement Banner
In order to add a banner to your application, you must use DPS App Builder to create an entitlement enabled application (eg: App Type either “Multi Folio with Entitlement” or “Multi Folio with Entitlement and iTunes Subscriptions”). Then provide a URL to where you deployed “banner/index.html”.
 
DPS App Builder Configuration
Figure 5 - DPS App Builder Configuration
 

 
Collection within an HTML Web View

Typical examples of HTML Web Views are full screen implementations of a custom library and/or storefront.  These areas are created using the Library and Store V2 SDK.  Registration of personal information is via a Web Form post to a server via AJAX.   Our implementation shows this being done within a dialog control.  This is not necessary.  Simply show/hide of a <div> would suffice.  You have complete design control.
 
HTML Web View Dialog
Figure 6 - HTML Web View Dialog
 
 
Adding Registration to a HTML Web View
This example (‘dialog.html’) has been created as a <div> that is shown or hidden.  For testing purposes only, a click handler has been added to allow a developer to hide|show the dialog.
 

 
The Post Subscription Dialog

A underutilized feature of Adobe DPS Applications is the ability to display a transparent and full screen transparent webview immediately following the successful purchase of an Apple subscription.  The intent is allow publishers to present an enticement to consumers to provide personalized information.  To implement this, simply provide an absolute URL within DPS App Builder.
 
An example is provided within the distribution at ‘post_sub_dialog/index.html’.
 
DPS App Builder
Figure 7 - DPS App Builder
 

 
Digital Blow-in

Do you remember those pesky (errr…I mean brilliant) 3”x5” cards that used to be inserted in print magazines that contained print subscription offers?  It is possible to create a digital equivalent with Adobe DPS.  So far, all of our examples have been additions to the application itself.  A digital blow-in is added to the folio content.
 
Again, we are going to present a web form to collect user information that posts the data to a server via an AJAX call.  We can put this digital blow-in on as many articles within a folio as we desire.  We track whether someone has registered (or not) via HTML localStorage. The effect is that if someone hasn’t registered, we can keep prompting them to do so as they navigate the folio.  If they have, we can either present nothing OR present a different message.
 
Digital Blow-in
Figure 8 - Digital Blow-in
 
The digital blow-in implementation is nearly identical, but you must use the Reading SDK for accessing viewer internals from a folio.
 
To add a digital blow-in to your article, do the following…
 
  1. Create the blow-in using the examples (we have provided one at ‘article_blowin/index.html’) and the Reading SDK.
  2. Host it on a server OR embed within the application via the HTMLResources.zip.
  3. Add a web overlay to your article and configure it.
  4. You will want to enable ‘auto-play’ and ‘Allow access to entitlement information’.  The latter actually means: “Enable Reading SDK” even if that is not exactly what is described.
Adding a digital blow-in
Figure 9 - Adding a digital blow-in
 

 
Database

Our examples all use MySQL and Personal Home Pages (PHP).  They also all use an identical 'register_user.php' script.  PHP is not required.  You could create your own server side implementation with Java Servlet Pages (JSP) or Common Gateway Interface(CGI) scripts.  The database must be created by you and its name, username and password provided withint the 'settings.php' file that is included with the distribution.  However, every access to the database by the PHP scripts will create the necessary tables, if not already present.
 
This requires CREATE table privileges and isn't the most efficient – so you may want to modify the scripts and/or user permissions after the tables are created.
 
The Database device table contains the following columns:
 
  1. Index – database index
  2. appId – The application ID this device was registered from.
  3. token – A hex/ascii representation of the device token used for push notifications.
  4. device – The UUID of the device for the reporting application.
  5. alert – Boolean indicating whether text notifications have been opted into.
  6. sound – Boolean indicating whether sound notifications have been opted into.
  7. badge – Boolean indicating whether icon update notifications have been opted into.
  8. timestamp – The last time the device registered for push notifications
  9. tag – Indicating whether the device was an iPad, iPhone or iPad3/4.
  10. email – User provided email address
  11. firstName – User provided first name
  12. lastName – User provided last name
  13. zipCode – User provided zip code.
 
 
And can be created by executing the following MySQL code.
 
CREATE TABLE `device` ( `index` int(11) NOT NULL AUTO_INCREMENT, `appId` varchar(50) DEFAULT NULL, `device` varchar(40) DEFAULT NULL, `token` varchar(65) DEFAULT NULL, `alert` tinyint(1) DEFAULT '0', `sound` tinyint(1) DEFAULT '0', `badge` tinyint(1) DEFAULT '0', `timestamp` int(11) DEFAULT '0', `newsstand` tinyint(1) DEFAULT '0', `tag` varchar(40) DEFAULT NULL, `email` varchar(100) DEFAULT NULL, `firstName` varchar(100) DEFAULT NULL, `lastName` varchar(100) DEFAULT NULL, `zipCode` varchar(15) DEFAULT NULL, PRIMARY KEY (`index`), UNIQUE KEY `device_per_app` (`device`,`appId`) ) ENGINE=InnoDB AUTO_INCREMENT=284933 DEFAULT CHARSET=utf8;

 
A Consumer Marketing Solution

All of the above collects personalized information and associates it with a device identifier.  To be truly useful, you need to associate this information with a marketing channel – push, email or otherwise.
 
The deviceID collected will be the same value as reported during push registrations (see this devnet article: http://www.adobe.com/devnet/digitalpublishingsuite/articles/dps-push-notification.html).
 
You have plenty of options here:
 
  1. Write some code to correlate the data yourself (level of effort: hard)
  2. Extend your push server to support the database and forms discussed in this article (level of effort: a bit easier)
  3. Leverage a pre-built JSP example implementation of "Notification Station" that has been posted here  as an Amazon Managed Instance (AMI). (level of effort: almost turn-key)
  4. Create a script to export a CSV (comma separated values) of email and/or deviceID and feed this into another system (level of effort: medium)

 
Where to go from here

  1. Deploy your own solution leveraging a pre-built DPS/JSP example implementation posted as an Amazon Managed Instance (AMI).
    1. http://aws.amazon.com/amis/dps-notification-station
  2. Upload your devices to a Commercial Push Provider (Urban Airship or Push.IO). For more info on how to do this, see:
    1. http://docs.urbanairship.com/reference/index.html
    2. http://docs.push.io/PushIO_API/
  3. Use Omniture Web API or Data Warehouse to create segments, cross reference with your collected data and then send highly personalized push/email messages via the provider of your choice.
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 data collection, 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.