8 August 2012
Before proceeding with this article, read the Adobe Developer Center article: Direct Entitlement Starter Kit, which introduces a kit for getting started with Adobe Digital Publishing Suite Direct Entitlement.
This article describes how to use Amazon's Web Services for the selling and periodic collection of payments associated with a digital-only or premium Adobe Digital Publishing Suite (DPS) folio content. It requires no interaction with a device manufacture's application storefront. This solution works with any application on any type of device (such as iOS, Kindle Fire, and Android) that has been enabled for direct entitlement. Typically, a user on a website initiates Digital subscription purchases, which are outside of the DPS application. Once purchased outside of the application, the subscription is available through direct entitlement inside the application or within the Adobe web viewer (otherwise known as a social sharing viewer).
In this article you will learn how to integrate Amazon Simple Pay Subscriptions with Digital Publishing Suite through a Direct Entitlement implementation.
This section explains the user experience that you will build in this example application. Figure 1 shows the first page in the subscription interface.
Note: Gmail or other e-mail clients may treat this notification e-mail as spam if your server is not a valid sender of the e-mail.
URLSchemedefined for the application.
The solution uses Amazon Simple Pay Subscriptions. According to Amazon, this service offers an "easy-to-use and secure way for those who offer digital content subscriptions, collect membership dues on a periodic basis, or provide premium services on their websites to enable subscriptions or recurring payments."
Users with existing Amazon IDs can purchase subscriptions with a single click after authentication. The publisher receives information and status updates as subscribers begin, complete, renew, cancel, or otherwise modify their subscriptions.
Before you get started with this tutorial, set up a new e-mail account (for instance, on mail.google.com) that you can use for the business side of the transactions, in other words, "the seller." Doing this separates this web application from any other transactions you may perform on the Amazon website. You will also need a separate/new e-mail account to create a sandbox user that can consume this service, in other words, "the buyer."
There are three components for implementing this solution:
The following steps guide you through setting up a developer/sandbox application on Amazon.
There are a number of ways to create a purchase page using C#, Ruby, Perl or PHP. Amazon's Sample Code and Libraries are an excellent place to start. For our example, we are going to use the stand-alone Library in PHP for Simple Pay Subscriptions. After you download the library, I recommend that you review the README.html file within the ButtonGeneratorWithSignature directory.
I've chosen to place the 'src' PHP files (SignatureUtils.php, ButtonGenerator.php) within my 'aws_utils' directory for convenient access.
You must provide your own values of $accessKey (Access Key ID) and $secretKey (Secret Access Key), which you can find at: https://portal.aws.amazon.com/gp/aws/securityCredentials, which should contain information similar to Figure 5.
Now that you have your access key and secret keys, you can modify the index.php file contained within the example ZIP you downloaded from the Requirements section in the beginning of this article. The only remaining basic item is to set the value of
$baseUrl in the settings.php file to the hostname and context root of your application.
baseurlin the settings.php file to map to where you deployed the application, for instance, http://lighthouse.adobe.com/dps/simplepay.
fulfillment_accountin the settings.php file to point to your Adobe Fulfillment account. See the "Connecting to fulfillment" section of the article, Build a Custom Storefront for details.
simplepaydatabase and a
getSubscriptions()returns an array of objects that contain application-specific subscriptions that are already defined. You might define your own. You can use data from these subscriptions to configure the buttons. Additionally, the
notifyresponse from Amazon contains the subscription identifier, as well.
URLSchemeto the application [optional].
Amazon will contact your website whenever it has information about the subscription or payment. It will also redirect users to your website whenever they complete or abandon a subscription purchase. You must define entry points for Amazon in the subscription button definitions or provide global defaults at: Manage Co-branding of Amazon Sandboxes.
The following table is a very brief overview of the Amazon Simple Pay: Getting Started Guide API Version 09-17-2008 .
Receives IPN notification objects during the purchase and asynchronously afterwards whenever some action happens on the user's account (i.e. renewal, cancelation, payment canceled or declined)
Status items used within the example are: SubscriptionSuccessful, PaymentSuccess and SubscriptionCanceled.
Additionally, the buyer's name and e-mail are provided along with an identifier for the type of subscription purchased.
After completing the subscription purchase, the user is redirected to this page.
The user quits the purchase experience and Amazon redirects them to this page.
Next you will learn how to build a multi-issue DPS viewer with entitlement. For both the Service URL and Service Auth URL, use the
$baseurl value from the settings.php file, with the extension of
/api/ . For instance, if your
$baseurl is http://foobar.com/dps/simplepay, set the Service URL to http://foobar.com/dps/simplepay/api/.
Note: For DPS v21+ iOS and all Android viewers, you have to define an integrator ID with these values. These devices ignore the values entered in Viewer Builder.
Once you have built and downloaded the viewer, you need to extract the account
GUID for the viewer and use that value for the
fulfillment_account within the settings.php file. See the "Connecting to fulfillment" section of the Build a Custom Storefront article for more details.
Use the following steps to test your setup.
For more information and resources on using Amazon Flexible Payment Services, see the following:
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.