Using Amazon Web Services to enable 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.

1. A user purchases a subscription (see Figure 1).
2. Control transfers to Amazon where the Amazon website asks the user to sign in and confirm the purchase. (Note the co-branding in upper left corner of the menu as shown in Figure 2).

3. The Amazon Payment Authorization page directs the user to your website and displays your desired message.

4. In this example, the previous step auto-generates an e-mail to the user using the e-mail associated with the Amazon consumer account.
5. The consumer receives the e-mail. The e-mail instructs the user to create an account on the entitlement system.

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.

6. At this point, the user is entitled to the most recent retail folio within the fulfillment account; the user continues to have entitlement to newly published retail folios.
7. An optional, but recommended step is as follows: After confirmation, redirect the user to the application on the iPad using the URLScheme defined 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:

1. Configure Amazon Simple Pay Subscriptions: You must set up the business account at Amazon to receive and process payments.
2. Create a purchase page: Create a web page to access the business account and make a subscription purchase.
3. Create a website that handles the transactions: Create a website that receives notifications from Amazon and the business account that handles the transactions.

The following steps guide you through setting up a developer/sandbox application on Amazon.

Configure Amazon Simple Pay Subscriptions

1. Sign up for an Amazon Flexible Payments Service (FPS) Sandbox account using your "buyer" e-mail account. Use this account to collect and manage payment/subscriptions.
2. Create an Amazon Payments Business Account on Sandbox. Again, use your "buyer" e-mail account as you did in the previous step.
3. You're done. You will see the following page display (see Figure 4).

Create a purchase page

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.

Create your website for handling transactions

1. Unzip and deploy the amazon-web-services-simplepay.zip, which contains the sample files you downloaded in the Requirements section. Download these files to a publicly addressable web server instance.
2. Modify $ baseurl in the settings.php file to map to where you deployed the application, for instance, http://lighthouse.adobe.com/dps/simplepay.
3. Modify $ fulfillment_account in 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.
4. Create a MySQL database and table using the script in the createDB.sql file. This file creates a simplepay database and a users table.

Other configurations and options

1. Within the subscriptions.php file, the function 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 notify response from Amazon contains the subscription identifier, as well.
2. Create a welcome e-mail. You can use the WelcomeEmail.php as a starting point.
3. Create a new confirmation page. The example asks the user to create an entitlement password. You can customize this confirmation page.
4. Modify the createPassword.php page to redirect the user through a URLScheme to 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 .

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.

1. Create a few folios (I recommend a minimum of three folios) within your fulfillment account. These need to be retail, public folios with corresponding iTunesConnect productIDs .
2. Create and install a multi-issue viewer with entitlement configured as described previously.
3. Create another sandbox account for simulating the buyer. This requires setting up another e-mail address. Once you have an e-mail address to use, configure it at

• https://payments.amazon.com/sdui/sdui/business?sn=devfps/o

4. Browse your application. The index.php file displays as shown in Figure 6.

5. Choose any of the options above (as shown in Figure 6). You will be transferred to Amazon. Within Amazon, sign in with your new sandbox account.
6. Confirm the purchase and Amazon takes you to the "return" page on your site.
7. At this point, you will receive an e-mail confirmation. If you don't see it, check your spam folder.
8. Create an entitlement password.
9. On the device, choose "Sign In" and provide the entitlement username (your buyer sandbox e-mail address) and (entitlement) password.
10. The most recent retail folio in your Adobe Fulfillment account is now ready for download.

For more information and resources on using Amazon Flexible Payment Services, see the following:

• Amazon FPS Developer Forums
• Amazon FPS Resource Center
• Amazon Simple Pay Getting Started Guide
• Amazon Simple Pay Advanced Users API Guide

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.