Appstore SDK IAPの実装
Appstore SDKアプリ内課金(IAP)APIについての理解を深めるために、Android IAPパッケージに含まれているクラスに関する以下の説明に目を通してください。AndroidアプリにIAP APIを組み込む方法については、このページのユースケースとコード例に従ってください。ここに記載されているコード例の多くは、Appstore SDKに含まれている消費型アイテムのIAPサンプルアプリで使用されています。
開始するには、ビデオチュートリアル(日本語字幕付き)を参照してください。アプリにIAPを実装する方法について詳しくは、以降の各セクションで説明します。
Android IAPパッケージについて
com.amazon.device.iap
パッケージには、AndroidアプリにIAPを実装するためのクラスとインターフェイスが用意されています。
このパッケージには、次のインターフェイスとクラスが含まれています。
ResponseReceiver
: Amazonアプリストアからのブロードキャストインテントを受信するクラスPurchasingService
: Amazonアプリストアを通じてリクエストを開始するクラスPurchasingListener
:PurchasingService
によって開始されたリクエストに対する非同期レスポンスを受け取るインターフェイス
以下の表に、PurchasingService
のリクエストメソッドと、各メソッドに対応するPurchasingListener
のレスポンスコールバックを示します。IAP APIを実装する場合は、これらのメソッド、コールバック、レスポンスオブジェクトを頻繁に使用することになります。
PurchasingServiceのメソッド | PurchasingListenerのコールバック | レスポンスオブジェクト |
---|---|---|
getUserData() |
onUserDataResponse() |
UserDataResponse |
getPurchaseUpdates() |
onPurchaseUpdatesResponse() |
PurchaseUpdatesResponse |
getProductData() |
onProductDataResponse() |
ProductDataResponse |
purchase() |
onPurchaseResponse() |
PurchaseResponse |
notifyFulfillment() |
なし | なし |
enablePendingPurchases() |
なし | なし |
マニフェストの要件
Android APIレベル30以上を対象とするアプリでアプリ内課金(IAP)APIを使用する場合は、アプリから照会する必要のあるパッケージのリストをAndroidManifest.xmlに定義する必要があります。Amazon App TesterとAmazonアプリストアを照会できるようにするには、マニフェストファイルに次のコードを追加します。
<manifest>
...
<queries>
<package android:name="com.amazon.sdktestclient" />
<package android:name="com.amazon.venezia" />
</queries>
</manifest>
また、ResponseReceiver
クラスからインテントを受け取るようにマニフェストを更新する必要もあります。詳細については、ResponseReceiverを参照してください。
ResponseReceiver
IAP APIは、すべての処理を非同期に実行します。アプリでは、ResponseReceiver
クラスを通じてAmazonアプリストアからブロードキャストインテントを受信する必要があります。このクラスがアプリ内で直接使用されることはありませんが、アプリでインテントを受信するには、マニフェストにResponseReceiver
のエントリを追加する必要があります。次のコード例は、Appstore SDK用のAndroidManifest.xmlファイルにResponseReceiver
を追加する方法を示しています。アプリがAndroid 12以降を対象としている場合は、MainActivity
とResponseReceiver
でandroid:exported
を明示的にtrue
に設定する必要があります。
<application>
...
<activity android:name="com.amazon.sample.iap.entitlement.MainActivity"
android:label="@string/app_name" android:exported="true" >
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
<receiver android:name="com.amazon.device.iap.ResponseReceiver" android:exported="true"
android:permission="com.amazon.inapp.purchasing.Permission.NOTIFY" >
<intent-filter>
<action
android:name="com.amazon.inapp.purchasing.NOTIFY" />
</intent-filter>
</receiver>
</application>
PurchasingService
PurchasingService
クラスは、情報を取得し、購入を実行して、購入されたアイテムの付与完了をAmazonに通知します。PurchasingService
には、以下のメソッドが実装されています。コールバックを機能させるには、それぞれのメソッドを以下のように実装する必要があります。
registerListener(PurchasingListener purchasingListener)
: このメソッドは、コールバック発生のメカニズムとして使用されます。registerListener()
は、PurchasingService
クラスのほかのメソッドを呼び出す前に呼び出します。PurchasingListener
オブジェクトを使用すると、ResponseReceiver
によってトリガーされるコールバックをアプリでリッスンして処理できるようになります。registerListener()
は、アプリのメインUIスレッドのonCreate()
メソッド内で呼び出します。getUserData()
: 現在ログインしているユーザーのアプリ固有IDとマーケットプレイスを取得するには、このメソッドを呼び出します。たとえば、ユーザーがアカウントを切り替えた場合や、同じデバイスで複数のユーザーがアプリにアクセスした場合、この呼び出しにより、取得するレシートが現在のユーザーアカウントのものであることを確認できます。getUserData()
は、onResume()
メソッド内で呼び出します。getPurchaseUpdates(boolean reset)
:すべてのデバイスを対象として、すべての定期購入型アイテムおよび非消費型アイテムの購入情報を取得します。消費型アイテムの購入情報は、購入を行ったデバイスからのみ取得できます。
getPurchaseUpdates()
は、付与が未完了でキャンセルされた消費型アイテムの購入情報だけを取得します。このメソッドから返されたPurchaseUpdatesResponse
データを保持しておき、その後の呼び出しでは更新分だけをシステムに問い合わせることをお勧めします。レスポンスはページ分割されます。getPurchaseUpdates()
は、onResume()
メソッド内で呼び出します。getProductData(java.util.Set skus)
: アプリに表示するSKUセットのアイテムデータを取得するには、このメソッドを呼び出します。getProductData()
は、onResume()
メソッド内で呼び出します。purchase(java.lang.String sku)
: 特定のSKUの購入を開始するには、このメソッドを呼び出します。notifyFulfillment(java.lang.String receiptId, FulfillmentResult fulfillmentResult)
: 指定したreceiptId
のFulfillmentResult
を送信するには、このメソッドを呼び出します。FulfillmentResult
に指定できる値は、FULFILLED
またはUNAVAILABLE
です。enablePendingPurchases()
: アプリで子どもと親向けに購入保留機能を有効にするには、このメソッドを呼び出します。PurchaseResponse.RequestStatus
値がPENDING
の場合、購入はまだ承認されていません。ステータスが保留中の場合は、ユーザーに非消費型アイテムを付与しないでください。購入が承認されると、onResume()
メソッドでgetPurchaseUpdates()
を呼び出すと、通常どおりに購入が処理されます。詳細については、購入保留機能の実装を参照してください。
PurchasingListener
非同期コールバックを処理するには、PurchasingListener
インターフェイスを実装します。これらのコールバックはUIスレッドで呼び出されるため、長時間実行されるタスクをUIスレッドで処理しないようにしてください。PurchasingListener
のインスタンスには、次の必要なメソッドを実装する必要があります。
onUserDataResponse(UserDataResponse userDataResponse)
:getUserData()
の呼び出し後に呼び出されます。現在ログインしているユーザーのユーザーIDとマーケットプレイスを特定します。また、クイック定期購入に対するユーザーの同意ステータスも提供します。onPurchaseUpdatesResponse(PurchaseUpdatesResponse purchaseUpdatesResponse)
:getPurchaseUpdates()
の呼び出し後に呼び出されます。購入履歴を取得します。このメソッドから返されたPurchaseUpdatesResponse
データを保持しておき、その後の呼び出しでは更新分だけをシステムに問い合わせることをお勧めします。onProductDataResponse(ProductDataResponse productDataResponse)
:getProductDataRequest()
の呼び出し後に呼び出されます。アプリで販売するSKUに関する情報を取得します。ProductDataResponse
オブジェクトから取得された有効なSKUを使用します。onPurchaseResponse(PurchaseResponse purchaseResponse)
:purchase()
の呼び出し後に呼び出されます。購入のステータスを判断するために使用します。
レスポンスオブジェクト
PurchasingService
を通じて呼び出しを開始すると、対応するレスポンスがPurchasingListener
に送られます。これらのレスポンスでは、それぞれ1つのレスポンスオブジェクトが使用されます。
UserDataResponse
: 現在ログインしているユーザーのアプリ固有のユーザーIDとマーケットプレイスを提供します。また、クイック定期購入に対するユーザーの同意ステータスも提供します。PurchaseUpdatesResponse
: ページ分割されたレシートリストを提供します。レシートはソートされていません。ProductDataResponse
: SKUをキーとするアイテムデータを提供します。アイテムデータを入手できないSKUのリストはgetUnavailableSkus()
メソッドで取得できます。PurchaseResponse
: アプリ内で開始された購入のステータスを提供します。PurchaseResponse.RequestStatus
の示す結果がFAILED
になる理由には、単にユーザーが購入手続きをキャンセルしただけの場合もあることに注意してください。
Kotlinアプリ内のレスポンスオブジェクトの例を確認するには、次のGitHubから IAP Kotlinサンプルアプリを複製またはダウンロードしてください。
IAP APIをアプリに組み込む方法
ここまで、IAPの実装に必要なクラスについて少し詳しく説明してきました。次は、アプリにIAPのコードを記述していきます。
このセクションのコードスニペットは、SDKに付属する消費型アイテムのIAPサンプルアプリから引用したものです。
1. プレースホルダーメソッドの作成
コードの骨組みを作るために、以下の場所で以下のメソッドを呼び出すプレースホルダー(スタブコード)を作成します。
registerListener()
は、onCreate()
メソッド内で呼び出します。getUserData()
は、onResume()
メソッド内で呼び出します。getPurchaseUpdates()
は、onResume()
メソッド内で呼び出します。getProductData()
は、onResume()
メソッド内で呼び出します。
アプリケーションのメインアクティビティからこれらの API を呼び出す onCreate ()
メソッドとonResume()
メソッドを呼び出します。これら4つの呼び出しはPurchasingService
クラスの一部であり、IAPを実行するための基盤となります。以降の手順では、上記の呼び出しの実装方法について詳しく説明し、独自のコードを記述するときにモデルとして使用できるサンプルコードを紹介します。
2. PurchasingListenerの実装と登録
ResponseReceiver
によってトリガーされるコールバックをアプリでリッスンして処理できるように、onCreate()
メソッドにPurchasingListener
を実装して登録します。
以下に示すコードスニペットでは、次のタスクを実行します。
-
(必須)
PurchasingListener
を登録する。 -
(任意)購入レシートに関連するデータを格納するための新しい
SampleIapManager
インスタンスを作成する。このタスクは省略できますが、その場合はアクセス可能なほかの場所に購入レシートデータを格納する必要があります。データベースを使用するかメモリ内にデータを格納するかは開発者が決定します。 -
(任意)アプリがサンドボックスモードで実行されているかどうかを確認する。Appstore SDKを使用していて、DRM用の
LicensingListener
を実装している場合は、LicensingService
クラスのgetAppstoreSDKModeメソッドを使用します。IAP v2.0を使用している場合は、PurchasingService.IS_SANDBOX_MODE
フラグを使用してサンドボックスモードになっているかどうかを確認します。このフラグは、アプリの開発中、App Testerを使用してローカルでアプリをテストする際に役立ちます。 -
(任意)購入保留を有効にする。この機能を使用すると、Amazon Kids内で子どもがアプリ内課金をリクエストし、親にその購入を承認または却下させることができます。親のレスポンスを待つ間、購入は保留状態になります。購入保留機能をセットアップする手順については、購入保留機能の実装を参照してください。
private SampleIapManager sampleIapManager; // 購入レシートデータを格納します(任意)
protected void onCreate(final Bundle savedInstanceState) // onCreateにPurchasingListenerを実装します
{
super.onCreate(savedInstanceState);
// setupApplicationSpecificOnCreate();
// Appstore SDKにApplicationContextを登録し、LicensingListenerの実装(この場合はLicensingCallback)を使用して
// DRMのライセンスを取得するリクエストを開始します
LicensingService.verifyLicense(this.getApplicationContext(), new LicensingCallback());
setupIAPOnCreate();
}
private void setupIAPOnCreate() {
sampleIapManager = new SampleIapManager(this);
final SamplePurchasingListener purchasingListener = new SamplePurchasingListener(sampleIapManager);
Log.d(TAG, "onCreate: PurchasingListenerを登録します");
PurchasingService.registerListener(this.getApplicationContext(), purchasingListener);
PurchasingService.enablePendingPurchases(); // 購入保留を有効にします
Log.d(TAG, "Appstore SDKモード:" + LicensingService.getAppstoreSDKMode()); // アプリがテストモードになっているかどうかを確認します
}
3.ユーザー情報の取得
onResume()
でgetUserData()
を呼び出して、現在のユーザーに関する情報(ユーザーIDとマーケットプレイス)を取得します。
// ...
private String currentUserId = null ;
private String currentMarketplace = null ;
// ...
public void onUserDataResponse( final UserDataResponse response) {
final UserDataResponse.RequestStatus status = response.getRequestStatus();
switch (status) {
case SUCCESSFUL:
currentUserId = response.getUserData().getUserId();
currentMarketplace = response.getUserData().getMarketplace();
break ;
case FAILED:
case NOT_SUPPORTED:
// 失敗時の処理を適切に行います。
break ;
}
}
この例では、後で使用できるようにユーザーIDとマーケットプレイスをメモリ内に保持しています。
4.getPurchaseUpdatesメソッドの実装
getPurchaseUpdates()
メソッドは、前回の呼び出し以降にユーザーが行った購入トランザクションをすべて取得します。onResume()
メソッド内でgetPurchaseUpdates()
を呼び出して、最新の更新情報を取得していることを確認します。
onResume()
メソッド内でgetPurchaseUpdates()
を呼び出す必要があります。getPurchaseUpdates()
をonResume()
内で呼び出さないと、購入レシートを受け取れない場合があり、その結果、アプリで購入済みのアイテムをユーザーに付与できなくなる可能性があります。このメソッドは、reset
というboolean型のパラメーターを取ります。取得する情報の量に応じて、この値をtrue
またはfalse
に設定します。
-
false
- レスポンスとして、前回getPurchaseUpdates()
が呼び出されてからの購入履歴がページ分割されて返されます。ユーザーへの付与が完了していない消費型アイテム、非消費型アイテム、定期購入型アイテムの購入に関するレシートが取得されます。Amazonアプリストアでは、基本的にこのアプローチの使用を推奨しています。注: アプリで購入保留を有効化すると、notifyFulfillment()
を呼び出すまで、getPurchaseUpdates(false)
の呼び出しごとに、付与が完了していない消費型アイテムと非消費型アイテムすべてのレシートが返されます。購入保留を有効にしない場合、getPurchaseUpdates(false)
の呼び出しごとに、付与が完了していない消費型アイテムのレシートのみが返されます。 -
true
- ユーザーの購入履歴全体を取得します。データをサーバー側のデータキャッシュなどに保存するか、メモリ内にすべてを保持する必要があります。
getPurchaseUpdatesのレスポンス
ほとんどのシナリオでは、getPurchaseUpdates()
からレスポンスが返されます。レスポンスが送信されるのは以下の場合です。
- 定期購入型アイテムと非消費型アイテム: 定期購入型アイテムと非消費型アイテムの購入では、常にレシートが返されます。
- 消費型アイテム: 消費型アイテムのトランザクションが正常に完了していて、(
notifyFulfillment()
を呼び出して)Amazonにアイテムの付与完了を通知する場合、onPurchaseResponse()
ではレシートが返されますが、getPurchaseUpdates()
ではレシートは返されません。これ以外の場合はすべて、消費型アイテムのレシートが返されます。このgetPurchaseUpdates()
メソッドでは、ごくまれに、付与が完了している消費型アイテムの購入情報のみが返されることがあります(アイテムの付与後、Amazonに通知する前にアプリがクラッシュした場合や、Amazon側で問題が発生した場合など)。このような状況では、アイテムを二重に付与することを避けるために、重複しているレシートを無視する必要があります。アイテムの配信時は、何らかの方法で配信状況を記録しておき、2つ目のレシートを受け取っても二重に配信しないようにしてください。 - キャンセルされた購入: キャンセルされたすべてのタイプ(定期購入型アイテム、非消費型アイテム、消費型アイテム)の購入について、レシートが返されます。
getPurchaseUpdates()
からレスポンスが返されると、PurchasingListener.onPurchaseUpdatesResponse()
コールバックがトリガーされます。
@Override
protected void onResume() // getPurchaseUpdatesはonResume内でのみ呼び出します
{
super.onResume();
//...
PurchasingService.getUserData();
//...
PurchasingService.getPurchaseUpdates(false);
}
getPurchaseUpdatesのレスポンスの処理
次に、レスポンスを処理する必要があります。
PurchasingListener.onPurchaseUpdatesResponse()
コールバックがトリガーされたら、PurchaseUpdatesResponse.getRequestStatus()
から返されるリクエストステータスを確認します。RequestStatus
がSUCCESSFUL
の場合は、各レシートを処理します。getReceipts()
メソッドを使用して、レシートの詳細を取得できます。
ページ分割を処理するには、PurchaseUpdatesResponse.hasMore()
の値を取得します。PurchaseUpdatesResponse.hasMore()
からtrueが返された場合は、次のサンプルコードに示すように、getPurchaseUpdates()
の再帰呼び出しを行います。
public class MyPurchasingListener implements PurchasingListener {
boolean reset = false ;
//...
public void onPurchaseUpdatesResponse( final PurchaseUpdatesResponse response) {
//...
// レシートを処理します
switch (response.getRequestStatus()) {
case SUCCESSFUL:
for ( final Receipt receipt : response.getReceipts()) {
// レシートを処理します
}
if (response.hasMore()) {
PurchasingService.getPurchaseUpdates(reset);
}
break ;
case FAILED:
break ;
}
}
//...
}
レシートの処理
レシートを処理します。SampleIapManager.handleReceipt()
メソッドを呼び出して、PurchaseUpdatesResponse
の一部として返されたすべてのレシートを処理します。
public void onPurchaseUpdatesResponse(final PurchaseUpdatesResponse response) {
// ....
switch (status) {
case SUCCESSFUL:
iapManager.setAmazonUserId(response.getUserData().getUserId(), response.getUserData().getMarketplace());
for (final Receipt receipt : response.getReceipts()) {
iapManager.handleReceipt(receipt, response.getUserData());
}
if (response.hasMore()) {
PurchasingService.getPurchaseUpdates(false);
}
iapManager.refreshOranges();
break;
}
// ...
}
5. getProductDataメソッドの実装
同じくonResume()
メソッド内で、getProductData()
を呼び出します。このメソッドはSKUを検証します。これは、無効なSKUが原因でユーザーの購入が失敗することを避けるためです。
次のサンプルコードでは、アプリの消費型アイテム、非消費型アイテム、定期購入型アイテムのSKUをAmazonで検証します。
protected void onResume() // 商品のSKUの検証はonResume内でのみ行います
{
super.onResume();
// ...
final Set <string>productSkus = new HashSet<string>();
productSkus.add( "com.amazon.example.iap.consumable" );
productSkus.add( "com.amazon.example.iap.entitlement" );
productSkus.add( "com.amazon.example.iap.subscription" );
PurchasingService.getProductData(productSkus); // PurchasingListener.onProductDataResponse()をトリガーします
Log.v(TAG, "SKUをAmazonで検証します" );
}
productSkus
に親SKUとすべての子SKUを追加して、getProductData()
で検証します。子SKUを含める必要があるのは、価格情報が子SKUに関連付けられているためです。価格は定期購入期間によって異なるので、親SKUには価格がありません。詳細については、定期購入型アイテムに関する質問を参照してください。PurchasingService.getProductData()
メソッドを呼び出すと、PurchasingListener.onProductDataResponse()
コールバックが呼び出されます。ProductDataResponse.getRequestStatus()
から返されたリクエストステータスを確認し、この呼び出しによって検証されたアイテムまたはSKUのみを販売します。
成功したリクエスト
RequestStatus
がSUCCESSFUL
の場合は、アプリに表示するSKUをキーとして商品データマップを取得します。RequestStatus
がSUCCESSFUL
であっても、アイテムデータを入手できないSKUが存在する場合は、ProductDataResponse.getUnavailableSkus()
を呼び出して無効なSKUのリストを取得し、アプリのユーザーがそれらの商品を購入できないようにしてください。
アプリ内でIAPアイコンを表示する場合は、AndroidManifest.xmlファイルを編集して、android.permission.INTERNET
パーミッションを含める必要があります。
商品データマップには次の値が含まれます。
フィールド | データ型 | 説明 |
---|---|---|
sku |
文字列 | 商品のSKU(Stock-keeping unit)。 |
title |
文字列 | ローカライズされた商品タイトル。 |
description |
文字列 | ローカライズされた商品説明。 |
smallIconUrl |
文字列 | 商品の小アイコンのURL。 |
productType |
文字列 | 商品の種類。有効な値は CONSUMABLE 、ENTITLED 、SUBSCRIPTION です。 |
coinsRewardAmount |
整数 | ユーザーがこの商品の購入後に受け取れるAmazonコインの数です。 |
freeTrialPeriod |
文字列 | 定期購入期間中の無料体験期間。無料体験が設定されていて、ユーザーに利用資格がある場合にのみ返されます。 |
subscriptionPeriod |
文字列 | SKUの定期購入の期間。期間のSKUに対してのみ返されます。有効な値は Weekly 、BiWeekly 、Monthly 、BiMonthly 、Quarterly 、SemiAnnually 、Annually です。 |
promotions |
[リスト] <Promotion> | ユーザーが利用できるプロモーションの詳細です。期間のSKUに対してのみ返されます。Promotion オブジェクトの詳細については、次の表を参照してください。プロモーション価格を設定する方法については、プロモーション価格の設定を参照してください。 |
price |
文字列 | ローカライズされた商品価格(定期購入型アイテムの子SKUの場合は子SKUに関連付けられている) |
Promotion
オブジェクトには次のフィールドが含まれています。
フィールド | データ型 | 説明 |
---|---|---|
promotionType |
文字列 | プロモーションのタイプ。有効な値は Introductory です。
|
promotionPlans |
[リスト]<PromotionalPlan> | プロモーションの価格と請求サイクルの詳細。PromotionalPlan オブジェクトの詳細については、次の表を参照してください。 |
PromotionalPlan
オブジェクトには次のフィールドが含まれています。
フィールド | データ型 | 説明 |
---|---|---|
promotionPrice |
文字列 | プロモーション期間中の期間SKUの価格(ローカライズされた形式)。 |
promotionPricePeriod |
文字列 | プロモーションの各請求サイクルの期間。有効な値は Weekly 、BiWeekly 、Monthly 、BiMonthly 、Quarterly 、SemiAnnually 、Annually です。 |
promotionPriceCycles |
整数 | 請求サイクルの数。 |
定期購入のさまざまなユースケースについて、商品データマップの例を確認するには、次のボタンをクリックしてください。これらの例はJSON形式です。
失敗したリクエスト
RequestStatus
がFAILED
の場合は、次のサンプルコードに示すように、アプリのIAP機能を無効にします。
public class MyPurchasingListener implements PurchasingListener {
// ...
public void onProductDataResponse( final ProductDataResponse response) {
switch (response.getRequestStatus()) {
case SUCCESSFUL:
for ( final String s : response.getUnavailableSkus()) {
Log.v(TAG, "アイテムデータを入手できないSKU:" + s);
}
final Map <string,>products = response.getProductData();
for ( final String key : products.keySet()) {
Product product = products.get(key);
Log.v(TAG, String.format( "商品:%s\n タイプ:%s\n SKU:%s\n 価格:%s\n 説明:%s\n" , product.getTitle(), product.getProductType(), product.getSku(), product.getPrice(), product.getDescription()));
}
break ;
case FAILED:
Log.v(TAG, "ProductDataRequestStatus: FAILED" );
break ;
}
}
// ...
}
6.購入を実行するコードの実装
購入を実行するコードを記述します。ここに示す例では消費型アイテムの購入を実行しますが、定期購入型アイテムや非消費型アイテムでも同様のコードを使用できます。
次のコードは消費型アイテムのサンプルアプリのMainActivity
クラスからの抜粋で、PurchasingService.purchase()
を呼び出して購入を開始します。このサンプルアプリでは、アプリユーザーが [Buy Orange] ボタンをタップすると、このメソッドが実行されます。
public void onBuyOrangeClick(final View view) {
final RequestId requestId = PurchasingService.purchase(MySku.ORANGE.getSku());
Log.d(TAG, "onBuyOrangeClick: requestId (" + requestId + ")");
}
次に、SamplePurchasingListener.onPurchaseResponse()
コールバックを実装します。以下のコードでは、実際の購入処理はSampleIapManager.handleReceipt()
によって行われます。
public void onPurchaseResponse(final PurchaseResponse response) {
switch (status) {
// ...
case SUCCESSFUL:
final Receipt receipt = response.getReceipt();
iapManager.setAmazonUserId(response.getUserData().getUserId(), response.getUserData().getMarketplace());
Log.d(TAG, "onPurchaseResponse: receipt json:" + receipt.toJSON());
iapManager.handleReceipt(receipt, response.getUserData());
iapManager.refreshOranges();
break;
}
}
7. 購入レシートの処理と購入の完了
購入レシートを処理・検証したら、購入を完了できます。独自のアプリを設計するときは、多くの場合、これらの手順をすべて1か所で処理するアイテム付与のしくみを実装することになります。
アイテムを付与する前に、購入のレシートを検証します。これを行うには、バックエンドサーバーでAmazonのレシート検証サービス(RVS)を使用してreceiptId
を検証します。Amazonでは、RVS Sandbox環境とRVS本番環境の両方を提供しています。RVS SandboxとサーバーをセットアップしてRVSを使用できるようにする方法については、レシート検証サービス(RVS)のドキュメントを参照してください。
- 開発中は、RVS Sandbox環境を使用して、App Testerで生成されたレシートを検証します。
- 本番環境では、RVS本番環境エンドポイントを使用します。
cancelDate
を検証することを強く推奨します。キャンセル日を確認しないと、ユーザーが購入をキャンセルした後も、サービスが引き続き利用される恐れがあります。cancelDate
フィールドの確認方法について詳しくは、IAPのベストプラクティスを参照してください。以下の例では、SampleIapManager
のhandleConsumablePurchase()
メソッドで、レシートがキャンセルされているかどうかを確認します。
- キャンセルされたレシートに対して既にアイテム付与が完了している場合は、
revokeConsumablePurchase()
メソッドを呼び出して購入を取り消します。 - レシートがキャンセルされていない場合は、サーバーからRVSを使用してレシートを検証し、
grantConsumablePurchase()
を呼び出して購入アイテムを付与します。
public void handleConsumablePurchase(final Receipt receipt, final UserData userData) {
try {
if (receipt.isCanceled()) {
revokeConsumablePurchase(receipt, userData);
} else {
// レシートの検証はサーバー側で実行することを強く推奨します
if (!verifyReceiptFromYourService(receipt.getReceiptId(), userData)) {
// 購入を検証できない場合は
// 適切なエラーメッセージをユーザーに表示します。
mainActivity.showMessage("購入を検証できませんでした。後でもう一度お試しください。");
return;
}
if (receiptAlreadyFulfilled(receipt.getReceiptId(), userData)) {
// レシートのアイテムが以前に付与されている場合は、付与済みであることを
// Amazonアプリストアに改めて通知します。
PurchasingService.notifyFulfillment(receipt.getReceiptId(), FulfillmentResult.FULFILLED);
return;
}
grantConsumablePurchase(receipt, userData);
}
return;
} catch (final Throwable e) {
mainActivity.showMessage("購入を完了できませんでした。もう一度お試しください。");
}
}
定期購入型アイテムの購入のガイドライン
購入可能アイテムが定期購入型アイテムである場合は、receiptId
の値に関して次の点に注意してください。
- 定期購入が継続していて途中でキャンセルされたことがない場合、その定期購入型アイテム/ユーザーについてアプリが受け取るレシートは1つだけです。
- 定期購入が継続的でない場合、たとえば、ユーザーが自動更新を選択せず、定期購入が期限切れになり、その1か月後に再び定期購入を開始した場合、アプリは複数のレシートを受け取ります。
8. Amazonにアイテム付与の結果を送信し、ユーザーにアイテムを付与
アイテム付与の結果を送信すると、ユーザーが購入したコンテンツにアクセスできるかどうかをAmazon側で確認できるようになります。アイテム付与の結果は必ずAmazonにお知らせください。notifyFulfillment()
メソッドを使用してFulfillmentResult
を送信します。
- ユーザーがアカウントを正常に作成し、サービスのコンテンツにアクセスできる場合は、アイテムを付与し、
FulfillmentResult.FULFILLED
を指定してnotifyFulfillment()
を呼び出します。この手順が完了すると、Amazonアプリストアからアプリに購入レシートが送信されなくなります。 - ユーザーに既存のアカウントがあり、サービスの定期購入型アイテムを既に所有している場合や、ユーザーにサービスのアカウントにサインアップする資格がない場合は、
FulfillmentResult.UNAVAILABLE
を指定してnotifyFulfillment()
を呼び出します。
送信するFulfillmentResult
の概要については、notifyFulfillmentの呼び出しに関するガイドラインを参照してください。
アイテムをユーザーに付与するには、購入レコードを作成し、そのレコードを永続的な場所に保存します。次のコードは、アイテム付与の結果をAmazonに送信する方法と、ユーザーにアイテムを付与する方法を示しています。
private void grantConsumablePurchase(final Receipt receipt, final UserData userData) {
try {
// 以下のサンプルコードは簡易な実装です。独自の付与ロジックを
// 実装するときは、スレッドセーフ、トランザクション性、堅牢性に
// 注意してください。
// アプリ/サーバーで購入情報を作成し、購入アイテムを
// ユーザーに付与します。この例では、ユーザーにオレンジを1つ
// 付与します。
createPurchase(receipt.getReceiptId(), userData.getUserId());
final MySku mySku = MySku.fromSku(receipt.getSku(), userIapData.getAmazonMarketplace());
// SKUがまだ適用可能であることを確認します。
if (mySku == null) {
Log.w(TAG, "レシート内のSKU [" + receipt.getSku() + "] は無効になっています。");
// SKUが適用不可になっている場合は、ステータス「UNAVAILABLE」を指定して
// PurchasingService.notifyFulfillmentを呼び出します。
updatePurchaseStatus(receipt.getReceiptId(), null, PurchaseStatus.UNAVAILABLE);
PurchasingService.notifyFulfillment(receipt.getReceiptId(), FulfillmentResult.UNAVAILABLE);
return;
}
if (updatePurchaseStatus(receipt.getReceiptId(), PurchaseStatus.PAID, PurchaseStatus.FULFILLED)) {
// SQLiteデータベースの購入ステータスの更新に成功
userIapData.setRemainingOranges(userIapData.getRemainingOranges() + 1);
saveUserIapData();
Log.i(TAG, "購入ステータスをPAIDからFULFILLEDに正しく更新しました。レシートID:" + receipt.getReceiptId());
// Amazonアプリストアにステータスの更新を渡します。購入に対して付与完了の
// ステータスが通知されると、Amazonはその購入レシートをアプリに送信しなく
// なります。
PurchasingService.notifyFulfillment(receipt.getReceiptId(), FulfillmentResult.FULFILLED);
} else {
// SQLiteデータベースの購入ステータスの更新に失敗 - ステータスは
// 既に変更されています。
// これは通常、同じレシートが別のonPurchaseResponseまたは
// onPurchaseUpdatesResponseコールバックで更新されたことを意味します。
// このサンプルコードでは、エラーを表示せずにログのみを出力します。
Log.w(TAG, "購入ステータスをPAIDからFULFILLEDに更新できませんでした。レシートID:" + receipt.getReceiptId()
+ "。ステータスは既に変更されています。");
}
} catch (final Throwable e) {
// 何らかの理由でアプリが購入アイテムを付与できない場合のために、
// ここに独自のエラー処理コードを追加します。
// 次にPurchasingService.getPurchaseUpdates APIを呼び出すと、
// Amazonから消費型アイテムの購入レシートが再度送信されます。
Log.e(TAG, "購入された消費型アイテムを付与できませんでした。エラー:" + e.getMessage());
}
}
notifyFulfillmentの呼び出しに関するガイドライン
notifyFulfillment()
を呼び出すときに、どのFulfillmentResult
を送信するかを判断するには、以下のガイドラインを使用します。
次の条件に該当する場合は、FULFILLED
を送信します。
- ユーザーがアカウントを正常に作成し、サービスのコンテンツにアクセスできる。
次のいずれかの状況が発生した場合は、UNAVAILABLE
を送信します。
- ユーザーに既存のアカウントがあり、サービスの定期購入型アイテムを既に所有している。
- ユーザーにサービスのアカウントにサインアップする資格がない。
Last updated: 2024年9月5日