IAP API for Web Apps
You can add In-App Purchasing (IAP) capability to your web application. The Amazon Services library presents a simple API to your app and manages the interactions with the native IAP APIs.
API Overview
In-App Purchasing for web apps comprises three major elements:
- Amazon Services Library - A JavaScript class that manages the interaction between your web app and the Amazon native IAP APIs.
- Purchase Handlers - You provide methods in your web app to respond to callbacks from the Amazon Services library.
- Receipt Verification Service - An Amazon service that you can use to validate the customer's purchase receipt.
Perform the following tasks to integrate your app with the In-App Purchasing API:
- Register the Purchase Handlers with the Amazon Services library.
- Call the IAP API methods at appropriate points in your app.
- Respond to the callback methods.
The callbacks can be triggered by your app or they could be called asynchronously, so your app must handle both cases. Structure your app to be stateless and not depend on any particular state of execution. For instance, a previous session of your app could have initiated a purchase request that was not delivered because the app shut down. When the app restarts and registers the Purchase Handler, the queued purchase is delivered to the new session.
API Flow
The following list itemizes the flow for a web application using the Amazon Services library. The list item numbers correspond to the callouts in the figure after the list:
- Implement a Purchase Handler method.
- Register your Purchase Handler with the Amazon Services library.
- The app initiates the in-app purchase.
-
Response notification is handled by your Purchase Handler method.
The above steps represent the minimum required steps. We recommend the following additional steps for a real-world implementation:
- Your app persists the receipt.
- Your app sends the receipt to you app server.
- Your app server sends the receipt to the Amazon RVS for validation, and receives a response.
- Your app server sends the response to your app.
- Your app persists the result.
The Amazon Services Library
The Amazon Services library is an integral part of the In-App Purchasing API. After you initiate a purchase using the In-App Purchasing API, the library presents an Amazon-branded user interface to complete the transaction.
To include the JS Library in your app, add the following <script> tag in the main HTML file of your web app:
<script src="https://resources.amazonwebapps.com/v1/latest/Amazon-Web-App-API.min.js">
</script>
Your code that uses Amazon In-App Purchasing API needs to wait for the amazonPlatformReady event, which is generated by the Amazon HTML5 Framework.
document.addEventListener('amazonPlatformReady', function () {
if(amzn_wa.IAP) {
//API usage code goes here
}
});
If your app calls the IAP API when the user is not authenticated with Amazon, the Amazon Services library will authenticate the user. To ensure a good user experience and confirm the user is logged into Amazon's services, check for entitlements as soon as your application launches.
The library and Amazon's services present the user interface for all aspects of the purchase workflow. They provide the logic to display the purchasable item, perform the 1-Click purchase itself, and handle any preconditions or error scenarios that arise.
In the event a purchase is unsuccessful, the client will present messaging to the customer; your app should not message the customer. For example, if the customer does not have a valid credit card on file, the library redirects the customer to a page where they can update their payment information. You do not need to provide a confirmation or other interstitial dialog to the customer regarding the purchase flow.