Direct entitlement starter kit

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.

• You need to deploy the server portion of the web application to a location that you control.
• You need to create a DPS viewer that can connect to it.
• You need to publish some Public+Retail folio data.

Below is a step-by-step guide.

Deploy the web application

The following is a general guide to deployment. The kit has been developed and deployed on Apache running on both OSX (Lion) and Linux.

1. Download and extract the distribution from the ZIP file you downloaded in the Requirements section.
2. Create a context root on the web server you plan to deploy on.
3. Modify the settings.php file as follows:
   1. Enter the connection information (hostname, username, and password) for your MySQL instance. If you are running the MySQL instance on the same machine as your Apache server, you may be able to connect through localhost.
4. Create a MySQL database entry
   1. Create a database named entitlements.
   2. Later on, I will explain how to create the table dynamically.
5. Deploy the web application.

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:

1. Open a browser and navigate to:

where:

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

2. Once you have run the script, the page displays a message: "Successfully created table: subscriptions".

Configure an application with Viewer Builder

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:

Configure your Folio Data

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.

OK…one more thing

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. (For more information, see the Custom Storefront article on how to find this information.)

A note about mod_rewrite

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, not 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.

Creating an 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:

http://<yourservername>[:<port>]/<contextroot>/forms/createAccount.html

(for instance, http://lighthouse.adobe.com/dps/entitlement_starter/forms/createAccount.html)

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.

Entitling content

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 SignInWithCredentials and RenewAuthToken. The DPS application viewer does nothing with the AuthToken data other than persist it and attach it to subsequent calls to verifyEntitlement and entitlements.

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:

Entitlement banner

The entitlement banner provides messaging to:

• Entitlement-based subscribers
• Apple AppStore subscribers
• Non (prospective) subscribers

As such, consider different messages for these groups. Using the JavaScript Viewer API for DPS, you can interface to information within the viewer about the user's authentication state ( getUserInfo ), subscription data ( getSubscriptionData ) and entitlements ( getEntitledProducts ).

Also, you might need to modify the entitlement banner to adjust to rotation. The provided implementation uses CSS Media Queries.

Integrator ID

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:

• Leveraging direct entitlement with Digital Publishing Suite
• Building a custom storefront with Digital Publishing Suite