Getting Started with the Amazon In-App Purchasing API

Introduction

The Amazon In-App Purchasing API makes it easy for you to offer digital content and subscriptions —such as in-game currency, expansion packs, upgrades, magazine issues and more— for purchase within your apps. Within minutes you can be up and running, ready to give millions of Amazon customers the ability to purchase engaging digital content using their Amazon 1-Click settings.

The In-App Purchase API is designed to encapsulate the complexity behind the purchase process while still providing a fully featured API set. The API utilizes the following objects in completing In-App Purchasing transactions:

• Purchasing Manager - used to initiate API requests
• Purchasing Observer - handles the API response callbacks
• Response Receiver - facilitates callbacks from the Amazon Client to the Purchasing Observer
• Receipt Verification Service - optional service for validating receipts outside of your app

The following diagram outlines the steps involved in the purchase sequence:

The simplest implementation can be completed in the following 5 steps.

1. Update the Android Manifest

In order to receive callbacks from the Amazon Client, you need to add the following lines to the <application> section of your AndroidManifest.xml file.

 <application>
 .
 .
 .
     <receiver android:name = "com.amazon.inapp.purchasing.ResponseReceiver" >
         <intent-filter>
             <action android:name = "com.amazon.inapp.purchasing.NOTIFY"
                 android:permission = "com.amazon.inapp.purchasing.Permission.NOTIFY" />
         </intent-filter>
    </receiver>
.
.
.
</application>

Read more about the Response Receiver

2. Implement the Purchasing Observer

The Purchasing Observer listens for callbacks as initiated via the Purchasing Manager. The observer should extend the BasePurchasingObserver class, allowing you to override only the callback methods you need.

At a minimum, you need to handle the callbacks for retrieving item data and for initiating a purchase request. You can create the Purchasing Observer class in your app's activity.

private class MyObserver extends BasePurchasingObserver {

  public MyObserver() {
   
        super(MainActivity.this);

  }

  @Override
  public void onItemDataResponse(ItemDataResponse itemDataResponse) {

      //Check itemDataResponse.getItemDataRequestStatus();
      //Use itemDataResponse to populate catalog data

  }

  @Override
  public void onPurchaseResponse(PurchaseResponse purchaseResponse) {

      //Check purchaseResponse.getPurchaseRequestStatus();
      //If SUCCESSFUL, fulfill content;

  }
} 
 

Read more about the Purchasing Observer

3. Register the Purchasing Observer

You need to register your Purchasing Observer with the Purchasing Manager, so your observer can listen for the callbacks. This should be done in your apps onStart method.

  protected void onStart() {
  super.onStart();
  PurchasingManager.registerObserver(new MyObserver());
  };
 

Read more about registering the Purchasing Observer

4. Initiate In-App Purchase

Once you register your observer you can begin using the Purchasing Manager to initiate item data request and purchase request. The API manages the purchase flow and all customer interaction for your app.

Use the Purchasing Manager to request item data for your SKU with the initiateItemDataRequest method

PurchasingManager.initiateItemDataRequest("DeveloperSKU-1234"); 

Use the Purchasing Manager to initiate a purchase request for your SKU with the initiatePurchaseRequest method

private OnClickListener purchaseClickListener = new OnClickListener() {

  public void onClick(View v) {
      String requestId = PurchasingManager.initiatePurchaseRequest("DeveloperSKU-1234");
  }
}; 
 

Read more about the Purchasing Manager

5. Handle Response Notification

After initiating a purchase request call, the Purchasing Observer will receive a callback with the response object matching the request. Your app will need to handle the response object received in the callback and provide the content to the user. This implementation will be specific to your app. At this point your base implementation is complete and you can begin testing with the SDK Tester App.

To learn more about the Amazon In-App Purchasing API, click here. We’ve also created a plugin for Eclipse to speed up development and cut down on project setup time. For more information on the Amazon Mobile App SDK Eclipse Plugin, click here.

This article was re-printed with permission from Amazon Digital Services, Inc.