IAP Plugin for Cordova

Introduction

This document provides sample code showing how to use the In-App Purchasing (IAP) v2.0 plugin for Cordova.

Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance with the License. A copy of the License is located at

http://aws.amazon.com/apache2.0/

or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Methods and Events

You can initiate method calls and listen for events. Method calls initiate requests, some of which return a response. Events are asynchronous system-generated messages that are sent in response to method calls to return the requested data to you.

All of the method calls, except for NotifyFulfillment, request data from the system. When you initiate a request for data, the system immediately returns an object containing a requestId string, which is a unique request identification string. The requested data is returned asynchronously via an event. The NotifyFulfillment method call does not return a response because its purpose is to notify Amazon that your app has delivered the purchased item to the user.

To get the data contained in an event, you must define a handler function and bind it to an event listener for the specific type of event. The returned data, accessible from within your event handler, includes a unique requestId that matches the requestId that was returned in the request method call. You can use the requestIds to match a specific request to a specific response, if necessary.

The following code snippet shows one way to save the requestId returned by the method call and match it in the event handler:

// Obtain object used to interact with plugin
var iapPlugin = window.AmazonIapV2;

// Create a variable to store the saved requestId
var theSavedRequestId = "";

// Construct object passed to method as input
var requestOptions = {
    "sku": "theSku"
};

// Add a listener for the purchaseResponse event
iapPlugin.addListener("purchaseResponse", function(event) {
    if (event.requestId == theSavedRequestId) {
        // do something
    }
});

// Call method with input
iapPlugin.purchase(
    function (operationResponse) {
        // Save returned requestId
        theSavedRequestId = operationResponse.requestId;

    }, function (errorResponse) {
        // Handle error response
    },
    [requestOptions]
);

IAP Plugin Methods and Events Reference describes each method and event, including any inputs and return values.

Initiating Method Calls in Cordova

To initiate a method call, you must perform the following general steps:

  1. Obtain the object used to interact with the plugin.
  2. If needed, construct the object used to pass input to the method.
  3. Call the method, passing in any required input and callback function definitions as arguments.

GetUserData

GetUserData initiates a request to retrieve the user ID and marketplace of the currently logged-in user.

// Obtain object used to interact with plugin
var iapPlugin = window.AmazonIapV2;

// Call method with no input
iapPlugin.getUserData(
    function (operationResponse) {
        // Handle operation response
        var requestId = operationResponse.requestId;
    }, function (errorResponse) {
        // Handle error response
    },
    []
);

Purchase

Purchase initiates a purchase flow for a product.

// Obtain object used to interact with plugin
var iapPlugin = window.AmazonIapV2;

// Construct object passed to method as input
var requestOptions = {
    "sku": "theSku"
};

// Call method with input
iapPlugin.purchase(
    function (operationResponse) {
        // Handle operation response
        var requestId = operationResponse.requestId;
    }, function (errorResponse) {
        // Handle error response
    },
    [requestOptions]
);

GetProductData

GetProductData initiates a request to retrieve item data for up to 100 SKUs.

// Obtain object used to interact with plugin
var iapPlugin = window.AmazonIapV2;

// Construct object passed to method as input
var requestOptions = {
    "skus": ["sku1", "sku2", "sku3"]
};

// Call method with input
iapPlugin.getProductData(
    function (operationResponse) {
        // Handle operation response
        var requestId = operationResponse.requestId;
    }, function (errorResponse) {
        // Handle error response
    },
    [requestOptions]
);

GetPurchaseUpdates

GetPurchaseUpdates initiates a request to retrieve updates about items the customer has purchased and/or cancelled.

// Obtain object used to interact with plugin
var iapPlugin = window.AmazonIapV2;

// Construct object passed to method as input
var requestOptions = {
    "reset": true
};

// Call method with input
iapPlugin.getPurchaseUpdates(
    function (operationResponse) {
        // Handle operation response
        var requestId = operationResponse.requestId;
    }, function (errorResponse) {
        // Handle error response
    },
    [requestOptions]
);

NotifyFulfillment

NotifyFulfillment notifies Amazon about the purchase fulfillment.

// Obtain object used to interact with plugin
var iapPlugin = window.AmazonIapV2;

// Construct object passed to method as input
var requestOptions = {
    "receiptId": "receiptId",
    "fulfillmentResult": "FULFILLED"
};

// Call method with input
iapPlugin.notifyFulfillment(
    function (operationResponse) {
        // Handle operation response
    }, function (errorResponse) {
        // Handle error response
    },
    [requestOptions]
);

Handling Events in Cordova

To handle an event, you must perform the following general steps:

  1. Obtain the object used to interact with the plugin.
  2. Define an event handler.
  3. Register your event handler with an event listener.

GetUserDataResponse

GetUserDataResponse returns the response from the GetUserData call.

// Obtain object used to interact with plugin
var iapPlugin = window.AmazonIapV2;

// Define event handler
var eventHandler = function(event) {
    var requestId = event.requestId; // string
    var userId = event.amazonUserData.userId; // string
    var marketplace = event.amazonUserData.marketplace; // string
    var status = event.status; // string
};

// Register for an event
iapPlugin.addListener("getUserDataResponse", eventHandler);

PurchaseResponse

PurchaseResponse returns the response from the Purchase call.

// Obtain object used to interact with plugin
var iapPlugin = window.AmazonIapV2;

// Define event handler
var eventHandler = function(event) {
    var requestId = event.requestId; // string
    var userId = event.amazonUserData.userId; // string
    var marketplace = event.amazonUserData.marketplace; // string
    var receiptId = event.purchaseReceipt.receiptId; // string
    var cancelDate = event.purchaseReceipt.cancelDate; // long
    var purchaseDate = event.purchaseReceipt.purchaseDate; // long
    var sku = event.purchaseReceipt.sku; // string
    var productType = event.purchaseReceipt.productType; // string
    var status = event.status; // string
};

// Register for an event
iapPlugin.addListener("purchaseResponse", eventHandler);

GetProductDataResponse

GetProductDataResponse returns the response from the GetProductData call.

// Obtain object used to interact with plugin
var iapPlugin = window.AmazonIapV2;

// Define event handler
var eventHandler = function(event) {
    var requestId = event.requestId; // string
    var productDataMap = event.productDataMap; // object containing key-value pairs where the key
                                               // is a SKU and the value is a ProductData object
    var unavailableSkus = event.unavailableSkus; // array of strings
    var status = event.status; // string

    // for each item in the productDataMap you can get the following values for a given SKU
    // (replace "sku" with the actual SKU)
    var sku = productDataMap["sku"].sku; // string
    var productType = productDataMap["sku"].productType; // string
    var price = productDataMap["sku"].price; // string
    var title = productDataMap["sku"].title; // string
    var description = productDataMap["sku"].description; // string
    var smallIconUrl = productDataMap["sku"].smallIconUrl; // string
};

// Register for an event
iapPlugin.addListener("getProductDataResponse", eventHandler);

GetPurchaseUpdatesResponse

GetPurchaseUpdatesResponse returns the response from the GetProductData call.

// Obtain object used to interact with plugin
var iapPlugin = window.AmazonIapV2;

// Define event handler
var eventHandler = function(event) {
    var requestId = event.requestId; // string
    var userId = event.amazonUserData.userId; // string
    var marketplace = event.amazonUserData.marketplace; // string
    var receipts = event.receipts; // array of PurchaseReceipt objects
    var status = event.status; // string
    var hasMore = event.hasMore; // boolean

    // for each item in receipts you can get the following values
    var receiptId = receipts[0].receiptId; // string
    var cancelDate = receipts[0].cancelDate; // long
    var purchaseDate = receipts[0].purchaseDate; // long
    var sku = receipts[0].sku; // string
    var productType = receipts[0].productType; // string
};

// Register for an event
iapPlugin.addListener("getPurchaseUpdatesResponse", eventHandler);