Prerequisite knowledge
 
  • Access to and ability to deploy to a web server such as Apache, configured to run with PHP and MySQL.
  • Familiarity with creating and publishing content to Digital Publishing Suite applications.
  • Ability to use Viewer Builder to create custom DPS viewer applications.
Original publication date: 03/06/2013
 
Modified: 07/30/2013 (Change log)
 
User level: Intermediate
 
Required products
Other required products
 
Sample files
YourEntitlementService.zip
By downloading software from the Adobe Web site you agree to the terms of our license agreement. Please read it before downloading.
 
 
The original Direct Entitlement Starter Kit introduced a framework for getting started with Adobe DPS Direct Entitlement. It’s primary goal was to showcase a concrete example implementation that illustrated the basic interfaces and requirements.
 
This article introduces a Direct Entitlement Service for all your applications. It extends the basic implementation with a fully functional and extensible infrastructure that can be used for lightweight production purposes. The implementation manages multiple applications through a single integrator ID. Also, basic UI has been added for the creation of applications and for the addition of users to them.
 
The distribution has been updated to support V1 or V2 of the Direct Entitlement API. The implementation manages multiple DPS applications and their users.  Basic UI and Web Forms have been added to enable the creation of applications and for the addition of users to them.
 
Additionally, the framework offers a method of connecting to existing integrators such that custom processing can pre-applied to the entitlement workflow.
 

 
Organization

The following describes the basic organization of the distribution. There is no top level UI or default file.  Rather, use the default files in /admin and /users to create applications and users respectively.
 
 
settings.php
Contains your database settings and Urban Airship account information as well as globally used helper functions.
 
 
/admin
Contains index.php (and search.php) for creating (and searching for) applications. Use these web forms for creating multiple applications.
 
 
/users
Contains index.php (and search.php) for creating (and searching for) users for specific applications.
 
 
/api
Contains endpoint implementations for the 4 Direct Entitlement APIs. Also contains .htaccess files for Apache URL mapping.
 
 
/assets
Contains shared images used in UI forms and web pages.
 
 
/banner
Example implementation of an entitlement banner.
 
 
/classes
Contains internal helper classes.
 
 
/db
Contains ‘initdb.php’ for creating the required database and tables. This can and should only be called once when setting up the application.
 
 
settings.php
Contains your database settings and Urban Airship account information as well as globally used helper functions.
 

 
Installation and Configuration

The following is a general guide to deployment.
 
  1. Download and unzip the distribution to a working area.
  2. Create a directory for your application on your web server (Apache).
  3. Modify settings.php
    1. Enter the connection information (hostname, username and password) for your MySQL instance. If it is running on the same machine as apache, you may be able to connect via ‘localhost’.
  4. 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_entitlement’ 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_entitlement
    2. Provide another suitable location by modifying the path in ‘settings.php’.Create a MySQL database entry
  5. Create a database named “entitlements”.
    1. We’ll create the tables dynamically later on.
  6. Deploy to your Apache web server (or equivalent).
Configuration is almost complete. You only need to create the required database tables. 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[s]://<yourservername>[:<port>]/<application_directory>/db/initdb.php, where:
 
  • <yourservername> is IP or common name of the your server (for example: “lighthouse.adobe.com")
  • <serverport> is optional and if you have to ask, you do not need it
  • <application_directory> is the value created in step #2 above
If successful, the above page will display:
 
 “successfully created databases and tables”.
 

 
Creating Applications

Once your distribution has been deployed, navigate a browser (Chrome works best) to /admin/index.php. Fill in the fields and press ‘Create’ in order to create a new application. Repeat for as many applications as you require.
 
Figure 1: DPS Entitlement Admininstration form

Figure 1: DPS Entitlement Admininstration form

 

 
Application ID
This must match the App ID you created for your application within the Apple Provisioning Portal OR the Application ID defined within DPS App Builder for your Android application.
 
 
Description (optional)
Plain-text, human readable description of your application. Only used within the UI.
 
 
Adobe ID
This must match the Title ID provided when you created your DPS Application within DPS App Builder. Specifically, this is the Adobe ID with the application role that you have published folios to.
 
 
password
The password for the Adobe ID provided above.
 

 
Creating Users

Once you have created one or more applications, you can create and attach users to them. User records are unique to each application and are not shared. This UI is useful for creating test users, but in production one would want to import user data from LDAP or some other subscription database.
 
Figure 2: DPS Entitlement User Creation

Figure 2: DPS Entitlement User Creation

 

 
Application
Select an application that you have previously defined by selecting the drop down combo box.
 
 
First name
Used only for storage in database.
 
 
Last name
Used only for storage in database.
 
 
emailAddress
This is the unique identifier for this user within the chosen application.  Does not have to be in an email format. Equivalent to username.
 
 
password
The password associated with the above emailAddress/username.
 
 
Start Date
All new users will have a subscription created starting now and continuing for 5 years. Since you will likely want to entitled previously published folios, it is recommended to choose a date in the past (e.g. a year ago).  With HTML5 enabled browsers (Safari/iOS, Chrome), you will be presented with a Date picker. With others, simply edit the date using the YYYY-MM-DD format.
 

 
DPS App Builder Settings

You will need a DPS Application configured for direct entitlement in order to use your Entitlement Service.  Every DPS Application that uses your Entitlement Service will have the same values for the following DPS Application Entitlement settings:
 
Property
Value
 
Service URL
 
For example: http://lighthouse.adobe.com/dps/es/api/
 
Service Auth URL
 
Same as above.
 
Integrator ID
 
You will need to get this from your Adobe representative. For information about obtaining an Integrator ID, see Direct Entitlement Service Request Form.
 
Send App ID and Version
 
Always enable this.
 

 
Usage with restricted distribution

The easiest usage method is to use a ‘restricted distribution’ approach. This way you do not need to create any In App Purchase product Ids within iTunes Connect. Simply create your DPS Application with the “Hide Buy Buttons” checked. That’s it.
 
When the application is in an un-authenticated state, none of the Retail folios will be displayed within the native library. Once authenticated, any entitled Retail folios will be displayed and available for “Download”.
 

 
Extending to other Integrators

You can extend the basic functionality offered by any integrator using this distribution.  For instance, you could check whether someone exists within an private database first – before checking whether they have an active subscription at an external integrator (e.g. CDS Global, TCS, Palm Coast Data, etc.).
 
By default, the UI to add an integrator has been commented out.  If you wish to add it, uncomment line 136 in /admin/index.php.
 
<label for="integrator">Integrator Extention (optional)</label><input class="input" name="integrator"  type="text" value="<?php echo $integrator;?>"  />
 
Of course, if you wish to add functionality, you will need to create it.
 
The SignInWithCredentials method will mark the subscriber’s record as having been authenticated via the integrator when true.
 

 
Where to go from here

There are a couple of things to consider that are specific to your deployment.
 
  1. Change the logo! It’s your entitlement service.
  2. Secure it. Once configured, only the /api directory needs to be open. You can put simple authentication on /admin and /users.
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.
 
Change log
 
The distribution has been updated to support V1 or V2 of the Direct Entitlement API.