Web App IAP API Reference
- Amazon Services Library
- API Reference: AmazonInAppPurchasing
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 theonStart()
oronResume()
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 forgetPurchaseUpdatesResponse()
in IAP 2.0:- Add logic in your app to handle fulfillment of purchase receipts returned from the call to
getPurchaseUpdates()
. The correspondingpurchaseUpdatesResponse()
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. - Use the boolean
reset
parameter instead of theoffset
parameter. Setreset
totrue
to return all purchase receipts, or setreset
tofalse
to return the receipts for purchases made since the last call togetPurchaseUpdates()
.
- Add logic in your app to handle fulfillment of purchase receipts returned from the call to
- Entitlements:
onPurchaseUpdatesResponse()
returns receipts for canceled and active purchases of entitlements and subscriptions. Check whether the purchase was canceled withreceipt.isCanceled()
. In IAP 1.0, receipts for canceled entitlements and subscriptions were returned by callinggetRevokedSkus()
on thepurchaseUpdatesResponse
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 theonPurchaseUpdatesResponse()
callback the next time you callgetPurchaseUpdates()
. 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
- 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
Response Objects
Every call you initiate via the Amazon Services results in a response received by the corresponding response handler specified in registerObserver()
. Each of these responses makes use of a response object. These responses are detailed below:
GetUserIdResponse
- provides the app-specific UserID for the user currently logged into the Amazon ClientPurchaseUpdatesResponse
- provides a paginated list of receipts and revoked SKUs since the offset passed into the initiating request. Receipts are returned in a set and are unordered.ItemDataResponse
- 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 registerObserver method with the Amazon Services library:
onSdkAvailable(onAvailableResponse)
- This gets called when the In-App Purchasing services are ready to be called by your code.onGetUserIdResponse(userIdResponse)
- Called in response toGetUserId
.onItemDataResponse(itemDataResponse)
- Called in response toGetItemData
.data.itemData
is a hash table ofitemData
objects keyed by SKU.onPurchaseResponse(purchaseResponse)
- Called to report the status of a purchase operation.purchaseResponse.purchaseRequestStatus
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.onPurchaseUpdateResponse(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.data.revokedSkus
has a list of SKUs that the user can no longer use.
API Reference: AmazonInAppPurchasing
Members
ItemDataStatus
Response codes for getItemData()
- INVALID_INPUT
- SUCCESSFUL
- FAILED
- SUCCESSFUL_WITH_UNAVAILABLE_SKU
ItemType
Types of purchases that can be made by the Amazon In-App Purchasing API.
This enumeration contains the following values:
- CONSUMABLE
- ENTITLEMENT
- SUBSCRIPTIONS
Offset
Helper value for finding purchase updates from the beginning of time.
Properties:
- BEGINNING - default value is NULL
PurchaseStatus
The status of the receipt
- INVALID_INPUT
- SUCCESSFUL
- FAILED
- INVALID_SKU
- ALREADY_ENTITLED
PurchaseUpdatesStatus
Response codes for getPurchaseData()
- INVALID_INPUT
- SUCCESSFUL
- FAILED
UserIdStatus
Response codes for getUserId()
- SUCCESSFUL
- FAILED
Methods
getItemData(skus)
Get item data for the list of SKUs.
Parameters:
Name | Type | Description |
---|---|---|
skus | Array | List of SKUs for which to retrieve item information |
getPurchaseUpdates(reset)
Get the user's receipts. Set reset
to false
to return only the new receipts since the last time you called this method. Set reset
to true
to return all of the receipts for this user.
Parameters:
Name | Type | Description |
---|---|---|
reset |
Boolean. Pass in a key/value pair, such as {reset: true} |
Set to false to return only the new receipts since the last time you called this method. Set to true to return all of the receipts for this user. |
getUserId()
Request the user ID. This will trigger a call to onGetUserIdResponse
when the result is available.
purchaseItem(sku)
Initiates a purchase of the given SKU
Parameters:
Name | Type | Description |
---|---|---|
sku | Requested SKU |
registerObserver()
Registers the callback handlers for handling asynchronous responses from the Amazon In-App Purchasing API.
Expects a hashtable of functions that will get called.
onSdkAvailable
onGetUserIdResponse
onItemDataResponse
onPurchaseResponse
onPurchaseUpdatesResponse
Type Definitions
onGetUserIdResponse(event)
Called as a response to getUserId
The structure of the event object is:
requestId
getUserIdRequestStatus
userId
Parameters:
Name | Type | Description |
---|---|---|
event | Requested SKU |
onItemDataResponse(event)
Called as a response to getItemData
with the requested item data.
The structure of the event object is:
requestId
itemDataRequestStatus
itemData (array)
sku
price
title
itemType
description
smallIconUrl
onPurchaseResponse(event)
Called as a response to purchaseItem
with the receipts.
The structure of the event object is:
requestId
userId
purchaseRequestStatus
receipt
sku
itemType
purchaseToken
subscriptionPeriod
(null for non-subscription receipts)startDate
endDate
onPurchaseUpdatesResponse(event)
Called as a response to getPurchaseUpdates
with the receipts.
The structure of the event object is:
requestId
purchaseUpdatesRequestStatus
receipts (array)
sku
itemType
purchaseToken
subscriptionPeriod
(null for non-subscription receipts)startDate
endDate
revokedSkus
(array of strings)offset
isMore
onSdkAvailable()
Called when the API is ready for further calls. This is a callback for the registerObserver
method.
Last updated: Dec 29, 2020