Adobe

Products

Acrobat

Creative Cloud

Creative Suite

Digital Marketing Suite

Digital Publishing Suite

Elements

Photoshop

Touch Apps

Student and Teacher Editions

More products

Solutions

Digital marketing

Digital media

Education

Financial services

Government

Web Experience Management

Leveraging direct entitlement with Digital Publishing Suite

by Scott Dreier

Content

How does direct entitlement work in Digital Publishing Suite applications?
Example publications with direct entitlement
Existing fulfillment providers

Created

28 February 2012

Requirements

Prerequisite knowledge

Familiarity with HTTP requests and responses.

Additional required other products

Access to an application server or a print fulfillment system such as CDS Global, Time Customer Service (TCS), Palm Coast Data (PCD), or Dovetail

User level

All

Required products

Digital Publishing Suite, Enterprise Edition

Sample files

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

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

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 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

        [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 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

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

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)

The New Yorker
http://itunes.apple.com/us/app/the-new-yorker-magazine/id370614765?mt=8

Wired Magazine
http://itunes.apple.com/us/app/wired-magazine/id373903654?mt=8

Reader’s Digest
http://itunes.apple.com/us/app/readers-digest/id411524298?mt=8

Newsweek
http://itunes.apple.com/us/app/newsweek-for-ipad/id370903329?mt=8

Martha Stewart Living
http://itunes.apple.com/us/app/martha-stewart-living-magazine/id399094624?mt=8

Digital Upsell for existing Print Subscribers

Dagens Nyheter (Sweden)
http://itunes.apple.com/us/app/dn+/id403485766?mt=8

Subscription activation within Entitlement Banner

EVO (UK)
http://itunes.apple.com/us/app/evo-magazine/id401980272?mt=8

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.