Prerequisite knowledge
Familiarity with HTTP requests and responses.
 
User level: All
 
Required products Sample files
By downloading software from the Adobe Web site you agree to the terms of our license agreement. Please read it before downloading.
 

 
Introduction

Integrating direct entitlement into your Adobe ® Digital Publishing Suite application enables your existing print subscribers to access your content on any supported digital device.  With direct entitlement, the publisher “owns” the subscriber’s account and contact information. Single-service implementation supports the ability to provide content portability across multiple devices. For instance, a print subscriber to The New Yorker magazine can now have free access to the same digital content on multiple devices, such as iPad and Kindle Fire devices.
 

 
How does direct entitlement work in Digital Publishing Suite applications?

When you configure a Digital Publishing Suite viewer application for direct entitlement, the viewer calls a publisher’s pre-determined web services.  As a developer, when you specify the host and path to this web service, the viewer application will provide the method/resource name. For example:
 
HTTP GET https://yourhostname.com/path_to_your_service/SignInWithCredentals?emailAdress=joe@doe.com&password=foo&uuid=12345&appId=com.adobe.dpsapp&appVersion=1.1.1
 
The direct entitlement API method/resource names are as follows:
 
SignInWithCredentials This API method authenticates a user based upon username (emailAddress) and a password, and persists the authToken value across application instances.
RenewAuthToken This API method periodically and occasionally attempts to renew a user’s authentication state using the persisted authToken value. It is called whenever the viewer is activated, the library is refreshed, or prior to a Newsstand background download.
entitlements This API method retrieves an XML list of folio product IDs entitled for download by a specific user. It is called after (re)authentication during the library update. Any folio productIds detailed within the response are entitled to the user for download.
verifyEntitlement Adobe’s Fulfillment server calls this API method to perform final validation on a specific folio product ID. If the API method returns a positive response, the folio begins downloading.
 
The following diagram shows the three-way relationship between the entitlement server, Adobe DPS Fulfillment Service, and your entitlement-enabled DPS application.  Note that, usually, the Authentication Server is the same as the Entitlement Server.
 
Figure 1a: Entitlement topography
Figure 1a: Entitlement topography
 
 
Read more about the Entitlements API Specification and how you can use these API methods/resources in your Digital Publishing Suite applications.
 
 
Timeline
The following timelines show the sequence of events and methods called during an entitlement process.
 
Figure 1: Entitlement process (first time)
Figure 1: Entitlement process (first time)
 
 
Figure 2: Entitlement process (renewing the authToken value)
Figure 2: Entitlement process (renewing the authToken value)
 
 
 
Library entitlement banner
As part of a direct entitlement enabled viewer application, you can optionally define an HTML banner to display at the top of the Library view. The banner is a communication channel between you, the publisher, and the user. You might use the banner for the following purposes:
 
  • A call to action for print subscribers to get immediate access to the content.
  • A call to action to non-print subscribers to purchase a digital subscription.
  • A customized authentication workflow.
  • New product messaging.
  • Advertising.
The banner is always 100% width (minus 30 pixels margin left and right) on a web page and usually adjusts after orientation. By default, it is 180 pixels high but you can change it when you create the viewer.
 
The library entitlement banner is implemented in HTML5/CSS3/Javascript and the publisher’s website hosts it.  Provide the URL to this implementation when you create the viewer within Viewer Builder.
 
The banner also has complete access to the Javascript Viewer API for DPS for communicating with the Viewer Application’s internals. These operations allow a banner to authenticate users, display user and/or subscription state, purchase folios/subscriptions, and present a personalized call to actions.
 
Figure 3: Banner with custom authentication
Figure 3: Banner with custom authentication
 
 
[styles.css] body { margin: 0; padding: 0; height: 180px; } /* portrait */ @media all and (min-width: 768px){ body { background-image:url(portait_bg.jpg); background-repeat: no-repeat; } } /* landscape */ @media all and (min-width: 964px){ body { background-image:url("landscape_bg.jpg"); background-repeat: no-repeat; } }
 
Offline banner
The application can detect when it is offline and unable to fetch the library banner from the publisher’s website. For this case, you can provide an alternative “offline” banner implementation. Since purchase, download, and entitlement are not possible when offline, this banner simply directs the user to connect the application by getting online. Within ViewerBuilder, you can provide a ZIP archive of the banner implementation. At a minimum, the archive must contain the file “index.html.” You can download this entitlement banner example from the Requirements section at the beginning of this article. Download and extract this example, open index.html in your browser, and resize the browser window to see how the media queries change the image (or view the page on iPad and rotate orientation to see how the banner changes).
 
 
Account creation
Optionally, you can specify a URL to a webpage within ViewerBuilder (“Create Account URL”) to direct people to when they want to create an entitlement account. There is no default implementation of this page nor does this webpage have access to the Javascript Viewer API for DPS. By providing this URL, the viewer presents a “Create an Account” hyperlink in the authentication dialog box. As a publisher, this is your mechanism for creating a new digital account.
 
Selecting the "Create an Account" link in the above authentication dialog will direct the user to a web page of your choosing.  You should use this web page to look up a user's exising account.  For instance, the below image allows you to look up a subscribers account using either "Name & Address" or "Subscription account number".
 
 
 
Figure 4: Authentication dialog box
Figure 4: Authentication dialog box
 
 
Figure 5: Create an Account process
Figure 5: Create an Account process
 
 
 
Forgotten passwords
Similar to the previous Account creation section, publishers should provide a URL to a web page for users to retrieve forgotten or lost passwords. The publisher’s website hosts this web page.
 
Figure 6: Forgot password dialog box
Figure 6: Forgot password dialog box
 
 
 
Existing print subscriptions
Within Viewer Builder, you can optionally define an “Optional Existing Subscription URL.” This displays with the following text, “I Have a Print Subscription” within the App Store subscription dialog box. The implementing web page can be the same as the “Create an Account” page, but the call to action within the viewer application only displays within the Apple subscriptions dialog box.
 
Figure 7: Subscription dialog box
Figure 7: Subscription dialog box
 
 

 
Example publications with direct entitlement

The following publications are available with direct entitlement within the Apple App Store.
 
Free Digital access to Print Subscribers (most common)
 
Digital Upsell for existing Print Subscribers
 
Subscription activation within Entitlement Banner
 

 
Existing fulfillment providers

Adobe has been working with existing print fulfillment services to extend their traditional subscription support into the digital realm of Adobe Digital Publishing Suite applications.  The following list provides implementation overviews for the publicly supported vendors in North America and United Kingdom.  All of these vendors require direct relationships with the publisher.  Contact your representative for pricing and for detailed information.
 
You must set the following required properties when creating an application with Viewer Builder.
 
CDS Global
 
ViewerBuilder property Value
Integrator ID cdsglobal
Service URL https://service.mycdsglobal.com/ws/adobe/
Service Auth URL https://service.mycdsglobal.com/ws/adobe/
Time Customer Service (TCS)
 
ViewerBuilder property Value
Integrator ID timecustomerservice
Service URL https://cgi.timeinc.com/webservices/adobews/
Service Auth URL https://cgi.timeinc.com/webservices/adobews/
Palm Coast Data (PCD)
 
ViewerBuilder property Value
Integrator ID palmcoastdata
Service URL https://www.neodata.com/
Service Auth URL https://www.neodata.com/
Dovetail
 
ViewerBuilder property Value
Integrator ID dovetail
Service URL https://adobe-fulfillmentserver.subscribeonline.co.uk/
Service Auth URL Application specific…see Note below
Note: Dovetail requires that you provide HTTP variable names and values for services with the Service Auth URL property value of SignInWithCredentials and RenewAuthToken. To use Dovetail fulfillment, you must create a service to capture these API calls, add the application-specific fields to a new HTTP request, invoke the service at Dovetail, and return the results to the application.
 
The extra fields are as follows:
 
HTTP variable name HTTP variable value
sourceSystem “MASS”
clientRef Contact Dovetail for value
brandRef Contact Dovetail for value

 
Where to go from here

To learn more about using direct entitlement in your Digital Publishing Suite applications, read the white paper, Managing customer entitlement with Adobe® Digital Publishing Suite  (PDF, 1.4MB). And watch Adobe Digital Publishing Evangelist Colin Fleming give a technical overview of how you can use direct entitlement in Adobe Digital Publishing Suite.
 
To learn more about how to extend Adobe DPS to meet your business needs, watch the video of Klaasjan Tukker's MAX 2013 session, Extending and Integrating Digital Publishing Suite.