2 April 2012
This article assumes you have access to and can deploy to a web server such as Apache that you have configured to run with PHP and MySQL. Readers should also be familiar with creating and publishing content to Adobe® Digital Publishing Suite (DPS) applications and using Viewer Builder to create custom DPS viewer applications.
Additional required other products
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.
This article introduces a kit for getting started with Adobe Digital Publishing Suite direct entitlement. The kit provides an implementation for all of the required services along with a lightweight MySQL database. The kit is based on PHP and MySQL.
The purpose of this starter kit is to showcase a concrete example implementation that illustrates the basic interface and requirements. Production usage would require you to make significant modifications to connect to distributed subscription databases and services.
There are three configurations required to enable the entitlements starter kit.
Below is a step-by-step guide.
The following is a general guide to deployment. The kit has been developed and deployed on Apache running on both OSX (Lion) and Linux.
Now that you have the application, you need to create a database. To make this easy, the starter kit provides a PHP script to create the database. Use the following steps to create the database with the PHP script:
<yourservername>is the IP or common name of the your server (for example "lighthouse.adobe.com).
<port>is optional. If you're unsure of your server port, you probably don't need this setting; delete it out of your URI.
<contextroot>is the value created in step #2 above. On Apache, it can be the directory where you extracted your files to; this assumes that the web server's documents folder is a parent. For example: http://lighthouse.adobe.com/dps/entitlement_starter/db/initdb.php.
You will need an entitlement-enabled application to use the starter kit. The starter kit comes with an entitlement "banner" that you can use. Within Viewer Builder, use the following settings:
Multi-issue with Entitlement
(For example: http://lighthouse.adobe.com/dps/entitlement_starter/api/)
Service Auth URL
Enter the same information as you used for "Service URL" above.
You will need to get this from your Adobe representative. For now, use "starter kit" as a stand-in property value. You use the
Create Account URL
Forgot Password URL
Banner Page URL
Offline Banner Assets
Use the file chooser to select the Archive.zip contained within the "banner" directory of the distribution.
When properly configured, the starter kit entitles all Public/Retail folios published after a subscriber's subscription starts. It is not necessary to publish any specific number of folios, but you will want enough to make it interesting. My suggestion is to publish at least three folios. You also need to make these available for in-app purchase. To do so, configure the in-app purchase product IDs within iTunesConnect. If you are working with a development viewer, connect to iTunesConnect through the sandbox. Within iTunesConnect, set your IAPs to the Waiting for screenshot option, in order to have them available through the sandbox. (For further information on configuring in-app purchases, see the iPad Publishing Companion Guide available from the DPS Dashboard.)
When configuring this option, select a publish time for one of your folios to be a week (or so) from today's date, so it is properly entitled.
As mentioned above, the starter kit attempt to access your DPS Fulfillment account to entitle content. Thus, it needs to know the account number. Set the variable
$fulfillment_account in the settings.php file to this value. (Use the Adobe lookup service to retrieve the fulfillment account number associated with your Adobe ID.)
I have implemented the API implementations using PHP and they have PHP file extensions. However, Adobe DPS-based viewers will invoke these endpoints without the PHP extension (for example, they will invoke
SignInWithCredentials.php). These are remapped using
mod_rewrite logic embodied in the .htaccess file.
Now that you have downloaded, configured, and deployed everything, we can attempt to exercise the system. Once you have set up everything properly, you will see all of your folios marked as "Buy" with a price associated. For the below example, I've published three folios to my DPS account.
For a subscriber to be entitled to retail content, they must be provisioned for access. For a traditional print publication, this step usually involves looking up the subscriber's account information from a preexisting database and provisioning that account for digital access. For our starter kit, we will allow anyone to sign up. By default, the
createAccount link creates a two-month subscription, which you can easily change.
You can create an account within the starter kit by creating an account from the sign-in dialog box of the viewer (see Figure 2) or by using the createAccount.html page from the starter kit deployment (see below).
To create an account using the createAccount.html page, navigate your browser (desktop or device) to:
When navigating to the createAccount HTML page, you will see the following form:
Our sample form performs minimal data validation. It only checks that the password entries match. In a production system, you should typically validate the e-mail address by sending an e-mail against a known database entry.
The starter kit queries the fulfillment account (as specified in settings.php) for a list of retail+public content and then entitles any content published from the creation of the subscription account, plus one month (specifically, 31 days from creation). So, for a user created on 27-March-2012, DPS entitles anything with a publish date after 27-March-2012 to 27-April-2012. Figure 4 shows that Folio 3 has a publication date of 28-Mar-2012, but Folio1 and Folio2 are 5-Mar and 6-Mar, respectively.
Thus, only Folio 3 is entitled for our new user after he/she signs in.
The authentication system generates
AuthToken, an opaque piece of data, in response to calls to
RenewAuthToken. The DPS application viewer does nothing with the
AuthToken data other than persist it and attach it to subsequent calls to
From a publisher's perspective, you can use the
AuthToken as a key to look up a specific user and ideally, a specific user's session on a specific device. For the purpose of the starter kit, we create
AuthTokens as a MD5 hash of the user's
emailAddress. You can find this function in settings.php.
In our example, the
AuthToken is not bound to a specific session. Instead, we have chosen to test the device ID (UUID) against a list of device IDs. We have arbitrarily chosen to allow you to use a single user account on up to five different devices. This allows someone with a few devices to use the same account across all of them.
How you choose to create
AuthTokens is up to you. The only requirement is that your systems must be able to look up entitlements for a specific user based on it.
At this point you should have a very basic entitlement system working. To take it to the next step, consider the following:
The entitlement banner provides messaging to:
getUserInfo ), subscription data (
getSubscriptionData ) and entitlements (
Also, you might need to modify the entitlement banner to adjust to rotation. The provided implementation uses CSS Media Queries.
Adobe's fulfillment server invokes the
verifyEntitlement API method. The fulfillment server uses the
integrator ID, which knows where to call your services. You must provide a publicly addressable URL to
verifyEntitlement to your Adobe representative in order to have this set up.
Note: Until Adobe sets up your
integrator ID and deploys it, you will be unable to download any entitled content within your application.
To deploy a fully functional entitlement system, you must have Adobe define and deploy an
integrator ID. It is also recommended to review these related articles:
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.
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.