Prerequisite knowledge
 
This article assumes the user has access to and can deploy to a Web Server such as Apache that is configured to run with PHP and MySQL.  The user should also be familiar with creating and publishing content to Adobe DPS applications.
 
Original publication date: 04/02/2012
 
Modified: 07/31/2013 (Change log)
 
User level: Intermediate
 
Required products
 
Additional required other products
 
Sample files
entitlement_starter_kit_v2_new.zip
By downloading software from the Adobe Web site you agree to the terms of our license agreement. Please read it before downloading.
 
 
 

 
This article introduces a kit for getting started with Adobe DPS 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 kit has been updated to work with both V1 and V2 of the Direct Entitlement APIs.
 
The purpose of the kit is to showcase a simple example implementation that illustrates the basic interface and requirements.  For production usage, it is expected that significant modifications would be required to connect to distributed subscription databases and services.
 

 
Installation and configuration

This article introduces a kit for getting started with Adobe DPS 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 kit has been updated to work with both V1 and V2 of the Direct Entitlement APIs.
The purpose of the kit is to showcase a simple example implementation that illustrates the basic interface and requirements.  For production usage, it is expected that significant modifications would be required to connect to distributed subscription databases and services.
 

 
Installation and Configuration

There are three configurations required to enable the Entitlement Starter Kit.  You need to deploy the server portion somewhere you control; you need to create a DPS viewer that can connect to it; and you need to publish some Public+Retail folio data.  Below is a step-by-step guide.
 
 
Configure the Server
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 unzip the distribution to a suitable location on your Apache server.
  2. Modify 'settings.php'.  Configure the following…
    1. $db_host – the hostname of the server running MySQL.  If on the same server as Apache, then use 'localhost'.
    2. $db_user – The MySQL user name.
    3. $db_pass – password for MySQL user name.
    4. $fulfillment_account - The GUID of your Adobe DPS Fulfillment account.  You can look this up at: https://www.dpsapps.com/dps/entitlement.  Provide the Adobe ID that contains the 'application role' for your application.  In DPS App Builder, this is the 'Title ID'.
  3. The distribution uses 'klogger' for simple logging.  You need to provide a directory that PHP/Apache will have rights to create files in.  Do one of the following:
    1. Manually create a 'dps_starter_kit' directory in /var/log using the following commands (note: you may need to preface with 'sudo')
      1. cd /var/log
      2. mkdir dps_starter_kit
      3. chmod –R 777 dps_starter_kit
    2. Provide another suitable location by modifying the path in 'settings.php'.
  4. Create a MySQL database entry
    1. Create a database named "entitlements".
    2. We'll actually create the table dynamically later on.
  5. Deploy and restart Apache (if necessary).
The application should be running now.  The next step is to create a database.  In order to ease some of the details here, a PHP script is provide to create the database.  Run it now by navigating in a browser to:
http://<yourservername>[:<port>]/<install_dir>/db/initdb.php
 
Where:
 
  • <yourservername> is IP or common name of the your server.  (eg "lighthouse.adobe.com)
  • <serverport> is optional and if you have to ask, you do not need it
  • <install_dir> is the value created in step #1 above.
e.g. http://yourserver.com/starter_kit/db/init.php
 
If successful, the above page will return:
 
"Created table: subscriptions".
 
 
Configure an application with Viewer Builder
You will need an entitlement enabled application in order to use the starter kit.  The starter kit comes with an entitlement 'banner' that you can use.  Within Viewer Builder, use these settings:
 
Property
 
Value
 
Viewer Type
 
Multi-issue with Entitlement
 
Service URL
 
http://<yourservername>[:<port>]/install_dir/api/
(e.g. http://yourserver.com/starter_kit /api/)
Service Auth URL
 
Same as above
 
Integrator ID
 

You will need to get this from your Adobe representative. For now, use "starter kit". The Integrator ID is used to call verifyEntitlement which is only invoked when attempting to download an entitled folio.
 
Create Account URL
 
http://<yourservername>[:<port>]/<install_dir>/forms/createAccount.html
 
Forgot Password URL
 
http://<yourservername>[:<port>]/<install_dir>/forms/forgotPassword.html
Banner Page URL
 
http://<yourservername>[:<port>]/<install_dir>/banner
Offline Banner Assets
 
Use the file chooser to select the Archive.zip contained within the "banner" directory of the distribution.
 
 
Configure your Application for Restricted Distribution
Restricted Distribution means that you will simply only present for download folios that are authorized for download.  It also can mean that no folios are available for purchase via iTunesConnect.  Both are typical for Enterprise/Corporate publishing examples as these applications are often not distributed via the AppStore.
 
If you would like to enable your application for 'Restricted Distribution' choose the 'Hide Buy Buttons' option within the "Navigation Toolbar" section of DPS App Builder.  This will not show any folio that is set as RETAIL UNLESS the folio has been explicitly authorized (by this starter kit) for download.
 
 
Configure your Folio Data
The starter kit, when properly configured, is designed to entitle 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, so publish at least 3.  You also need to make these available for in-app purchase, so also configure the in-app purchase product IDs within iTunesConnect. If you are working with a development viewer, it will be connecting to iTunesConnect via the sandbox.  Within iTunesConnect, your IAPs should be set to "Waiting for screenshot" in order to have them available via the sandbox. (For further information on configuring in-app purchases, see the Adobe iOS Publishing Companion Guide).
 
You should choose a publish time for one of your folios to be a week (or so) from now so it gets properly entitled
 
 
A note about mod_rewrite
The API implementations are implemented using PHP and have ".php" extensions.  However, Adobe DPS based viewers will invoke these endpoints without the ".php" extension (eg. SignInWithCredentials, not SignInWithCredentials.php).  These are remapped using mod_rewrite logic embodied in the .htaccess file.
 

 
Usage

Now that you have everything downloaded, configured and deployed, we can attempt to exercise the system. If everything is setup properly, you should see all of your folios marked as "Buy" with a price associated (or not shown at all if you chose 'Hide Buy Buttons'). For the below example, I've published 3 folios to my DPS account.
 
Custom DPS Viewer app showing three published folios.
Figure 1: Custom DPS Viewer app showing three published folios.
 
 
Create Account
For a subscriber to be entitled to retail content, they must be provisioned for access.  For a traditional print publication, this step would involve looking up the subscribers account information from a pre-existing database and then provisioning that account for digital access.  For our starter kit, we will just allow anyone to sign up.  By default, the createAccount link will create a 2 month subscription.  You can easily change this.
 
You can create an account within the starter kit by either:
1. Selecting the "Create an Account" hyperlink from the "Sign In" dialog:
 
Creating an account from the Sign In dialog box of the custom viewer
Figure 2: Creating an account from the Sign In dialog box of the custom viewer
 
 
Or
 
  1. Navigating a browser (desktop or device) to:
    http://<yourservername>[:<port>]/<install_dir>/forms/createAccount.html
    (e.g. http://yourserver.com/starter_kit/forms/createAccount.html )
Either will direct you to the following form:
 
The createAccount.html form
Figure 3: The createAccount.html form
 
 
Our sample form performs minimal data validation – it only checks that the password entries match.  In a production system, you would want to typically validate the email address by sending an email or against a known database entry.
 
 
Entitle 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 time the subscription account was created, plus 1 month (specifically, 31 days from creation).  So, for a user created on 27-March-2012, anything with a publish date after this, but before 27-April-2012 will be entitled. The below shows that Folio 3 has a publication date of 28-Mar-2012, but Folio1 and Folio2 are 5-Mar and 6-Mar, respectively. 
 
Figure 4: Folio Producer Organizer shows three folios with different publication dates
Figure 4: Folio Producer Organizer shows three folios with different publication dates
 
Thus, only Folio 3 will be entitled for our new user after signing in.
 
The custom viewer app showing Folio 3, the only folio entitled for this user
Figure 5: The custom viewer app showing Folio 3, the only folio entitled for this user

 
What about AuthTokens?

The AuthToken is an opaque piece of data that is generated by the authentication system in response to calls to SignInWithCredentials and RenewAuthToken.  The DPS application viewer does nothing with it other than persist it and attach it to subsequent calls to verifyEntitlement and entitlements.
 
From a publisher's perspective, the AuthToken should be a key to look up a specific user and ideally, a specific users session on a specific device.  For the purposes of the starter kit, we create AuthTokens as a MD5 hash of the user's emailAddress.  This function is 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 a single user account to be used on up to 10 different devices.  This allows someone with a couple 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 be able to look entitlements for a specific user based on it.
 

 
What now?

At this point you should have a very basic entitlement system working.  To make it real, you will want to consider the following:
 
 
Banner
The entitlement banner provides messaging to:
 
  • Entitlement based subscribers
  • Apple AppStore subscribers
  • Non (prospective) subscribers
As such, you should 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, the entitlement banner needs to adjust to rotation.  The provided implementation uses CSS Media Selectors.
 
 
Integrator ID
The 'verifyEntitlement' API method is invoked by Adobe's fulfillment server.  It is through the 'integrator ID' that the fulfillment server knows where to call your services. You will need to provide a publicly addressable URL to 'verifyEntitlement' to your Adobe representative in order to have this setup.
 
For information about obtaining an Integrator ID, see Direct Entitlement Service Request Form.
 
NOTE: UNTIL THE INTEGRATOR ID IS SET UP UP AND DEPLOYED BY ADOBE, YOU WILL NOT BE ABLE TO DOWNLOAD ANY ENTITLED CONTENT WITHIN YOUR APPLICATION.
 

 
Where to go from here

In order to deploy a fully functional entitlement system you will need to have an integrator ID defined and deployed by Adobe.
 
It is also recommended to review these related articles:
DPS Entitlement
Building a Custom Storefront
 

 
Change log

The kit has been updated to work with both V1 and V2 of the Direct Entitlement APIs.