Cordova用アプリ内課金(IAP)プラグイン


Cordova用アプリ内課金(IAP)プラグイン

はじめに

このドキュメントでは、Cordova用アプリ内課金(IAP)v2.0プラグインの使用方法を示すサンプルコードを紹介します。

Apache License, Version 2.0(以下「本ライセンス」)に基づいてライセンスが付与されています。本ライセンスに従わない場合、このファイルを使用することはできません。本ライセンスのコピーは次の場所で参照できます。

http://aws.amazon.com/apache2.0/(英語のみ)

また、プラグインファイルに付属するlicenseファイルにも含まれています。このファイルは、明示または暗示を問わず、いかなる保証も条件もなしに、「現状のまま」で配布されます。本ライセンスの下での権限および制限事項を規定する具体的な文言については、本ライセンスを参照してください。

メソッドとイベント

アプリでは、メソッド呼び出しを開始してイベントをリッスンすることができます。メソッド呼び出しでリクエストが開始され、その一部はレスポンスを返します。メソッド呼び出しのレスポンスとして送信されるのがイベントです。イベントは、システムで生成される非同期メッセージであり、リクエストされたデータを呼び出し元に返します。

NotifyFulfillmentを除き、すべてのメソッド呼び出しはシステムにデータをリクエストします。データのリクエストを開始すると、requestId文字列(一意のリクエスト識別文字列)を格納したオブジェクトがシステムから直ちに返されます。リクエストしたデータは、イベントを通じて非同期的に返されます。ただし、NotifyFulfillmentメソッド呼び出しについては、アプリからユーザーに購入アイテムが配信されたことをAmazonに通知する目的で使用するものなので、レスポンスは返されません。

イベントに格納されているデータを取得するには、ハンドラー関数を定義して、特定のイベントタイプのイベントリスナーにバインドする必要があります。返されたデータにはイベントハンドラー内からアクセスでき、また、リクエストメソッド呼び出しで返されたrequestIdに一致する一意のrequestIdが含まれています。必要に応じて、requestIdを使用して、特定のリクエストに対応するレスポンスを見つけることができます。

次のコードスニペットでは、メソッド呼び出しで返されたrequestIdを保存して、イベントハンドラーで照合する方法を示します。

// プラグインとのやり取りに使用するオブジェクトを取得します
var iapPlugin = window.AmazonIapV2;

// 保存用のrequestIdを格納する変数を作成します
var theSavedRequestId = "";

// メソッドに入力として渡すオブジェクトを作成します
var requestOptions = {
    "sku": "theSku"
};

// purchaseResponseイベントのリスナーを追加します
iapPlugin.addListener("purchaseResponse", function(event) {
    if (event.requestId == theSavedRequestId) {
        // 必要な処理を実行します
    }
});

// 入力を指定してメソッドを呼び出します
iapPlugin.purchase(
    function (operationResponse) {
        // 返されたrequestIdを保存します
        theSavedRequestId = operationResponse.requestId;

    }, function (errorResponse) {
        // エラーレスポンスを処理します
    },
    [requestOptions]
);

それぞれのメソッドとイベントについては、入力や戻り値を含めて、アプリ内課金(IAP)プラグインのメソッドとイベントのリファレンスで説明しています。

Cordovaでメソッド呼び出しを開始する方法

メソッド呼び出しを開始するには、一般に次の手順に従います。

  1. プラグインとのやり取りに使用するオブジェクトを取得します。
  2. 必要に応じて、入力をメソッドに渡すためのオブジェクトを作成します。
  3. 必要な入力やコールバック関数定義を引数に渡して、メソッドを呼び出します。

GetUserData

GetUserDataは、現在ログインしているユーザーのユーザーIDおよびマーケットプレイスを取得するリクエストを開始します。

// プラグインとのやり取りに使用するオブジェクトを取得します
var iapPlugin = window.AmazonIapV2;

// 入力なしでメソッドを呼び出します
iapPlugin.getUserData(
    function (operationResponse) {
        // オペレーションレスポンスを処理します
        var requestId = operationResponse.requestId;
    }, function (errorResponse) {
        // エラーレスポンスを処理します
    },
    []
);

Purchase

Purchaseは、商品の購入フローを開始します。

// プラグインとのやり取りに使用するオブジェクトを取得します
var iapPlugin = window.AmazonIapV2;

// メソッドに入力として渡すオブジェクトを作成します
var requestOptions = {
    "sku": "theSku"
};

// 入力を指定してメソッドを呼び出します
iapPlugin.purchase(
    function (operationResponse) {
        // オペレーションレスポンスを処理します
        var requestId = operationResponse.requestId;
    }, function (errorResponse) {
        // エラーレスポンスを処理します
    },
    [requestOptions]
);

GetProductData

GetProductDataは、最大100個のSKUのアイテムデータを取得するリクエストを開始します。

// プラグインとのやり取りに使用するオブジェクトを取得します
var iapPlugin = window.AmazonIapV2;

// メソッドに入力として渡すオブジェクトを作成します
var requestOptions = {
    "skus": ["sku1", "sku2", "sku3"]
};

// 入力を指定してメソッドを呼び出します
iapPlugin.getProductData(
    function (operationResponse) {
        // オペレーションレスポンスを処理します
        var requestId = operationResponse.requestId;
    }, function (errorResponse) {
        // エラーレスポンスを処理します
    },
    [requestOptions]
);

GetPurchaseUpdates

GetPurchaseUpdatesは、購入またはキャンセルされたアイテムに関するアップデートを取得するリクエストを開始します。

// プラグインとのやり取りに使用するオブジェクトを取得します
var iapPlugin = window.AmazonIapV2;

// メソッドに入力として渡すオブジェクトを作成します
var requestOptions = {
    "reset": true
};

// 入力を指定してメソッドを呼び出します
iapPlugin.getPurchaseUpdates(
    function (operationResponse) {
        // オペレーションレスポンスを処理します
        var requestId = operationResponse.requestId;
    }, function (errorResponse) {
        // エラーレスポンスを処理します
    },
    [requestOptions]
);

NotifyFulfillment

NotifyFulfillmentは、購入アイテムの付与完了についてAmazonに通知します。

// プラグインとのやり取りに使用するオブジェクトを取得します
var iapPlugin = window.AmazonIapV2;

// メソッドに入力として渡すオブジェクトを作成します
var requestOptions = {
    "receiptId": "receiptId",
    "fulfillmentResult": "FULFILLED"
};

// 入力を指定してメソッドを呼び出します
iapPlugin.notifyFulfillment(
    function (operationResponse) {
        // オペレーションレスポンスを処理します
    }, function (errorResponse) {
        // エラーレスポンスを処理します
    },
    [requestOptions]
);

Cordovaでイベントを処理する方法

イベントを処理するには、一般に次の手順に従います。

  1. プラグインとのやり取りに使用するオブジェクトを取得します。
  2. イベントハンドラーを定義します。
  3. イベントハンドラーをイベントリスナーに登録します。

GetUserDataResponse

GetUserDataResponseは、GetUserData呼び出しのレスポンスを返します。

// プラグインとのやり取りに使用するオブジェクトを取得します
var iapPlugin = window.AmazonIapV2;

// イベントハンドラーを定義します
var eventHandler = function(event) {
    var requestId = event.requestId; // 文字列
    var userId = event.amazonUserData.userId; // 文字列
    var marketplace = event.amazonUserData.marketplace; // 文字列
    var status = event.status; // 文字列
};

// イベントハンドラーを登録します
iapPlugin.addListener("getUserDataResponse", eventHandler);

PurchaseResponse

PurchaseResponseは、Purchase呼び出しのレスポンスを返します。

// プラグインとのやり取りに使用するオブジェクトを取得します
var iapPlugin = window.AmazonIapV2;

// イベントハンドラーを定義します
var eventHandler = function(event) {
    var requestId = event.requestId; // 文字列
    var userId = event.amazonUserData.userId; // 文字列
    var marketplace = event.amazonUserData.marketplace; // 文字列
    var receiptId = event.purchaseReceipt.receiptId; // 文字列
    var cancelDate = event.purchaseReceipt.cancelDate; // long
    var purchaseDate = event.purchaseReceipt.purchaseDate; // long
    var sku = event.purchaseReceipt.sku; // 文字列
    var productType = event.purchaseReceipt.productType; // 文字列
    var status = event.status; // 文字列
};

// イベントハンドラーを登録します
iapPlugin.addListener("purchaseResponse", eventHandler);

GetProductDataResponse

GetProductDataResponseは、GetProductData呼び出しのレスポンスを返します。

// プラグインとのやり取りに使用するオブジェクトを取得します
var iapPlugin = window.AmazonIapV2;

// イベントハンドラーを定義します
var eventHandler = function(event) {
    var requestId = event.requestId; // 文字列
    var productDataMap = event.productDataMap; // キーと値のペアを格納するオブジェクト
                                               // (キーはSKU、値はProductDataオブジェクト)
    var unavailableSkus = event.unavailableSkus; // 文字列の配列
    var status = event.status; // 文字列

    // productDataMap内のアイテムごとに、SKUに対応する以下の値を取得できます
    // ("sku"は実際のSKUに置き換えてください)
    var sku = productDataMap["sku"].sku; // 文字列
    var productType = productDataMap["sku"].productType; // 文字列
    var price = productDataMap["sku"].price; // 文字列
    var title = productDataMap["sku"].title; // 文字列
    var description = productDataMap["sku"].description; // 文字列
    var smallIconUrl = productDataMap["sku"].smallIconUrl; // 文字列
};

// イベントハンドラーを登録します
iapPlugin.addListener("getProductDataResponse", eventHandler);

GetPurchaseUpdatesResponse

GetPurchaseUpdatesResponseは、GetProductData呼び出しのレスポンスを返します。

// プラグインとのやり取りに使用するオブジェクトを取得します
var iapPlugin = window.AmazonIapV2;

// イベントハンドラーを定義します
var eventHandler = function(event) {
    var requestId = event.requestId; // 文字列
    var userId = event.amazonUserData.userId; // 文字列
    var marketplace = event.amazonUserData.marketplace; // 文字列
    var receipts = event.receipts; // PurchaseReceiptオブジェクトの配列
    var status = event.status; // 文字列
    var hasMore = event.hasMore; // boolean

    // レシート内のアイテムごとに、以下の値を取得できます
    var receiptId = receipts[0].receiptId; // 文字列
    var cancelDate = receipts[0].cancelDate; // long
    var purchaseDate = receipts[0].purchaseDate; // long
    var sku = receipts[0].sku; // 文字列
    var productType = receipts[0].productType; // 文字列
};

// イベントハンドラーを登録します
iapPlugin.addListener("getPurchaseUpdatesResponse", eventHandler);