Web App IAP API Methods

To implement in-app purchasing, your web app provides a set of response handlers to the Amazon Services library.

• The Amazon Services Library
  • ProductData
  • PurchaseReceipt
  • Reset
  • Response Objects
  • Purchasing Handlers
  • Processing receipts

The In-App Purchasing API comprises of two main components - the Amazon Services library (a javascript library), and Response Handlers that you implement and pass as an argument to the Amazon Services library upon initialization.

To include the library, add the following <script> tag to your web app:

<script src="https://resources.amazonwebapps.com/v1/latest/Amazon-Web-App-API.min.js">
</script>

The Amazon Services Library

The Amazon Services library includes the following methods:

• AmazonIapV2.addListener(listener)
  • You must register your observer prior to using this class
  • This method needs to be called within your onLoad() lifecycle method
• AmazonIapV2.purchase(sku)
  • This method is used to initiate a purchase of a particular SKU
  • This method works with all types of Purchasable Items
  • The user interface surfaced uses the information configured for the SKU to determine the purchase flow presented to the customer
  • This method can be called from your app anytime
• AmazonIapV2.getProductData(skus)
  • This method is used to retrieve Item data about a set of SKUs
  • This method works with all types of Purchasable Items
  • This method can be called from your app anytime
  • The parameter SKUs is an array of SKU strings
• AmazonIapV2.getPurchaseUpdates(reset)
  • This method is used to sync previous purchases and revoked entitlements across devices.
  • Implement getPurchaseUpdates() in the onStart() or onResume() method of the activity. Also, to prevent over-fulfillment of an order, de-duplicate the receipts with receiptId. See below for implementation details concerning the differences between consumables, entitlements, and subscriptions.
  • Consumables: The getPurchaseUpdates() method returns unfulfilled and canceled purchase receipts for consumables. Note the following for getPurchaseUpdatesResponse()in IAP 2.0:
    • Add logic in your app to handle fulfillment of purchase receipts returned from the call to getPurchaseUpdates(). The corresponding PurchaseUpdatesResponse() callback may run when your app opens, or any other time, so use caution when referencing user interface (UI) elements or objects that may not be available.
    • Set reset to true to return all purchase receipts, or set reset to false to return the receipts for purchases made since the last call to getPurchaseUpdates().
  • Entitlements: onPurchaseUpdatesResponse() returns receipts for canceled and active purchases of entitlements and subscriptions. Check whether the purchase was canceled with receipt.isCanceled(). In IAP 1.0, receipts for canceled entitlements and subscriptions were returned by calling getRevokedSkus() on the PurchaseUpdatesResponse object.
  • Subscriptions: Same as Entitlements.
• AmazonIapV2.getUserData()
  • This method is used to retrieve the app-specific ID of the currently logged-in user
  • This method needs to be called within your onLoad() method
• AmazonIapV2.notifyFulfillment(receiptId, fulfillmentResult)
  • IAP 2.0 provides a new API that you can use to track the fulfillment status of a purchase. To track the fulfillment status of a purchase, implement the notifyFulfillment() API. Implement this call after the item is fulfilled to send the status of the purchase to Amazon.
  • If you do not call notifyFulfillment() with the FULFILLED status after the item is fulfilled, the delivery remains pending. In this case, the delivery attempts will continue to be made through the onPurchaseUpdatesResponse() callback the next time you call getPurchaseUpdates(). Eventually, the order may be canceled if Amazon does not receive explicit acknowledgement of fulfillment with this API.
  • If you can never fulfill the item, use the UNAVAILABLE status. You can call notifyFulfillment() with the UNAVAILABLE status from your app anytime.
  • This call is immutable. If an order is marked as FULFILLED or UNAVAILABLE via notifyFulfillment(), the status cannot be changed again

ProductData

A product data represents a purchasable item, and provides information for your storefront. It is a best practice to retrieve the price of the purchasable item and display it prior to having the customer initiate a purchase. The ProductData class can be used to access the localized price, title, and description strings. The price string will include the currency symbol and be formatted appropriately based on the locale.

PurchaseReceipt

A PurchaseReceipt is provided for every purchase made. Every receipt will contain a recieptId that can be used to validate a purchase via the Receipt Verification Service. The receipt is deemed secure, and you can safely rely solely on it to authorize access to content or functionality within your app. As a developer, you have access to the userData, receiptId, and SKU for a particular purchase. The recieptId is dynamically generated each time Receipt data is returned and they are unique values for verifying the Receipt data returned in a response object. Each recieptId will successfully validate against the Receipt Verification Service at any given time.

Reset

Use the boolean reset parameter instead of the offset parameter of 1.0. Set reset to true to return all purchase receipts, or set reset to false to return the receipts for purchases made since the last call to getPurchaseUpdates()

Response Objects

Every call you initiate via the Amazon Services library results in a response received by the corresponding response handler specified in each addListener() methods. Each of these responses makes use of a response object. These responses are detailed below:

• GetUserDataResponse - provides the app-specific UserData for the user currently logged into the Amazon Client
• PurchaseUpdatesResponse - provides a paginated list of receipts and unavailable SKUs since the offset passed into the initiating request. Receipts are returned in a set and are unordered.
• ProductDataResponse - provides item data, keyed by SKU.
• PurchaseResponse - provides a status on purchases initiated within your app. Any error for a purchase is opaque to the developer, you do not need to implement any error handling scenarios in your app; this is managed by In-App Purchasing API.

Purchasing Handlers

You must implement the following response handlers and register them in the addListener method with the Amazon Services library:

• getUserDataResponse(userDataResponse) - Called in response to GetUserData.
• getProductDataResponse(productDataResponse) - Called in response to getProductData. data.productDataMap is a hash table of productData objects keyed by SKU.
• purchaseResponse(purchaseResponse) - Called to report the status of a purchase operation. purchaseResponse.status contains the status of the response. If a prior session of the application shut down before a purchase response could be delivered, this function will be called when a new session of the application registers a purchase hander.
• getPurchaseUpdateResponse(data) - Called with the list of entitlements that the user has been granted. data.receipts contains a hash table, keyed on SKU, that contains the receipts for the IAPs that have been granted to the user.

Processing receipts

Implement fulfilled acknowledgements for each receipt. When processing receipts, first check whether the receipt is cancelled. Depending on the cancellation status, do one of the following:

• If the receipt is canceled, and the item has not been revoked already, then revoke the item.
• If the receipt is not canceled:
  • Check if the fulfillment has already occurred for this receiptId. If so, call notifyFulfillment() for the receiptId with the FULFILLED status.
  • If the fulfillment has yet to occur, then fulfill the receipt. Store the receiptId to keep track of the already fulfilled items, then call notifyFulfillment() for the receiptId with the FULFILLED status.
  • If the fulfillment can not occur because the item was for a previous game state or the game does not support that item, then call notifyFulfillment() for the receiptId with the status UNAVAILABLE. Do not send this status if you encounter an interim error during receipt processing