Reminder - Digital Publishing Suite (DPS) will End of Life on August 31st, 2019. 
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 Digital Publishing System applications and using Viewer Builder to create custom DPS viewer apps.
The reader should also be familiar with DPS Direct Entitlement and the Direct Entitlement Starter Kit.
User level: Intermediate
Required products
Additional required other products
Sample files
By downloading software from the Adobe Web site you agree to the terms of our license agreement. Please read it before downloading.


Note: If you have questions about this article, use the DPS forum. Please don’t contact technical support with questions about Adobe Developer Connection articles.


Publisher's tablet viewers tend to be free applications, but the content (folios) within them usually require subscription or purchase. To allow a new (potential) customer to sample a folio of their choice for free, publishers can use a technique called Promotional Entitlement. This can be achieved by leveraging the direct entitlement capabilities of Digital Publishing Suite, Enterprise Edition. Using direct entitlement, this system will make available a single retail folio in return for the successful registration of a confirmed email address.
This example is built using the Direct Entitlement Starter Kit.

Promotional offer

As a means to promote a magazine's content, this system will enable a nonsubscriber to register an email address and, in return, receive the right to download any current or back issue. The example uses a simple direct entitlement system without any interaction with traditional fulfillment providers.
Upon installation of the application, the user is presented with an offer. The offer can be anything, but this example offers a single download in exchange for a confirmed email address. Once confirmed, the user is presented with a set of folios to choose from. In this example, this is the entire library of public and retail content. After the user chooses a single issue for download, the selection is noted in a database and then becomes the only folio to which the user has complimentary entitlement. All others revert to their previous "Buy" state.
While users will always be able to download their chosen folio, they will be prevented from choosing any other folio for download using the complimentary entitlement system. Only one per user is allowed.
The system uses a banner to present the offer and collect an email address from the user (see Figure 1).
Figure 1. Using a dynamic banner to collect an email address. Note: folios only have the "buy" option.

Figure 1. Using a dynamic banner to collect an email address. Note: folios only have the "buy" option.


Verify email address
The user's email address is sent to the entitlement system, which formats and sends an email to that address. This email contains a link that will first confirm the email and then direct the user back to the application (see Figure 2).
Figure 2. Confirmation email

Figure 2. Confirmation email


Users can confirm the email on an iPad or desktop. If they do so on an iPad, the link will be opened in Safari (see Figure 3):
Figure 3. Confirmation

Figure 3. Confirmation


Entitle promotional content
After confirmation of the email, the user is directed back to the application where all public retail content has been enabled for download (see Figure 4).
Figure 4. Viewer app after email confirmation. Note: The folio is now available for download.

Figure 4. Viewer app after email confirmation. Note: The folio is now available for download.


Download folio
Once the user chooses to download a folio, that folio is granted as the promotional folio and all other folios revert to Buy. In Figure 5, the user has chosen to download Folio 2.
Figure 5. Chosen folio downloaded and available to view; other folios set back to "buy"

Figure 5. Chosen folio downloaded and available to view; other folios set back to "buy"



Upon registering, the email address is associated with the device's UUID. This association is stored in a server-side database. The record then waits confirmation by email. Once confirmed, the record is updated and entitlements are provided to all the public retail content that is found in the publication's DPS fulfillment account (see Figure 6).
Figure 6. Registration, confirmation, and entitlement sequence

Figure 6. Registration, confirmation, and entitlement sequence


The download action invokes the verifyEntitlement method call which will update the record with the productId being requested. This becomes the promotional item and cannot be changed.
Email, the browser and the app
The email message contains a hyperlink that will confirm the email address when selected. The authToken is added as a HTTP GET parameter on this hyperlink and will be used to look up the account.
After confirmation, a hyperlink is provided that contains a URL scheme back to the application. It is of the form: urlscheme:ignored.html

Installation and configuration

The promotional entitlement example will work with your existing DPS fulfillment account, provided that you can deploy the server portion somewhere you control. You will also need to create a new DPS viewer that can connect to it.
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 unzip the distribution.
  2. Create a context root on the web server on which you plan to deploy.
  3. Modify settings.php as follows:
    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.
    2. Modify the value "confirmURL" to map to your deployment. It should be a URL to confirm.php in the root directory of the distribution.
    3. Create an "emailSender" address. This should be a real email account.
    4. Modify the value "fulfillment_account" to point to an account you own. (See the Custom Storefront article on how to find this information.)
  4. Create a MySQL database entry named getonefree. You'll actually create the database table dynamically later on.
  5. Deploy.
  6. Request an integrator ID from your Adobe representative. You will need this to actually download entitled retail content. Otherwise, everything else can be implemented, but the final download step will not work.
The application should be running now. The next step is to create a database. To ease some of the details here, a PHP script to create the database is provided in the code sample. Run it now by navigating in a browser to:
  • yourservername is the IP address or DNS name of your server; for example,
  • port is optional, and if you have to ask, you do not need it.
  • contextroot is the value created in step 2 above. On Apache it can be the directory to which you unzipped your files—assuming the web server's documents folder is a parent. For example,
If successful, the page will return the message:
"Successfully created table: getonefree"
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 these settings:
Property Value
Viewer Type
Multi-issue with Entitlement (and Apple subscriptions)
Technically, the Apple subscriptions are not required, but the whole point is to drive conversions and you want to convert them to Apple subscriptions.
Service URL
Service Auth URL
Same as above
Integrator ID
You will need to get this from your Adobe representative. For now, use "promotion". The Integrator ID is used to call the verifyEntitlement() method, which is only invoked when attempting to download an entitled folio.
Create Account URL
Leave blank
Forgot Password URL
Banner Page URL
Offline Banner Assets Use the file chooser to select the contained within the banner directory of the distribution.
Adobe DPS fulfillment account
As mentioned above, the starter kit will attempt to access your DPS fulfillment account to entitle content, so it needs to know the account number. Set the variable "$fulfillment_account" in settings.php to this value. (see the Custom Storefront article on how to find this information).

Where to go from here

Our example makes ALL public retail content available as a selection in return for an email address. Other possibilities:
Back issues only
Rather than offer the current issue, or even the first few issues, the system can be adapted to offer only back issues exclusive of the most recent n issues. For instance, you could allow complimentary entitlement only to 2011 or older content.
Collect other personal information
While the example collects only an email address, you could require the user to formally register a name, address and phone number.
Deferred payment
You could sell a subscription with a deferred payment option. This would collect credit card information up front and provide free access for a predetermined time, after which the credit card is automatically charged.
By leveraging an existing database of users, you could provide limited access to customers of another property or service.
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.