In-app Billing API

In-app Billing Version 3 API を利用すると、アプリにアプリ内課金の仕組みを簡単に取り入れることができます。 このバージョンでは、同期購入フローが改善され、消費可能な商品の所有状況を API で簡単にトラックできるようになっており、アプリ内購入データのローカル キャッシングなどの機能が追加されています。

商品タイプ

Google Play Developer Console を使い、商品タイプ、SKU、価格、説明などで商品を定義します。 詳細については、アプリ内課金の管理をご覧ください。 Version 3 API は管理対象のアプリ内アイテムと定期購入をサポートします。

管理対象のアプリ内アイテム

管理対象のアプリ内アイテムとは、Google Play が所有情報をトラックし、管理しているアイテムのことです。 ユーザーが管理対象のアプリ内アイテムを購入すると、Google Play にユーザーごとの各アイテムの購入情報が保管されます。 これにより、特定のユーザーが購入したアイテムの状態を復元するために、いつでも Google Play に照会できるようになります。 この情報は、ユーザーがアプリをアンインストールしても、端末を替えても、Google Play サーバー上に保持されます。

Version 3 API を使うと、アプリ内で管理対象のアイテムを消費することもできます。 一般的には、複数回購入可能なアイテム（ゲーム内通貨、食糧、呪文など）を対象に消費の仕組みを実装します。 管理対象のアイテムは、一旦購入すると、Google Play に消費リクエストを送ってアイテムを消費しない限り再購入できません。 アプリ内アイテムの消費に関する詳細は、アイテムを消費するをご覧ください。

定期購入

定期購入は、アプリ内課金の商品タイプのうち、ユーザー向けコンテンツ、サービス、機能をアプリ内で月単位または毎単位で課金できるものです。 アプリからゲームまで、ほぼすべてのタイプのデジタル コンテンツに対して定期購入販売が可能です。 定期購入に関する詳細は、アプリ内課金での定期購入をご覧ください。

Version 3 API を使うと、アプリ内アイテムと同様の購入フローで定期購入を登録し、定期購入情報を取得することができます。 サンプルコードは、定期購入を実施するでご確認ください。

重要: アプリ内アイテムとは異なり、定期購入は消費できません。

アイテムを購入する

図 1. 購入リクエストの基本的なシーケンス

Version 3 API を使った購入フローは、次のとおりです。

  1. アプリから Google Play に isBillingSupported リクエストを送信して、使用している In-app Billing API のバージョンがサポートされていることを確認します。
  2. アプリの起動時、またはユーザーのログイン時に、ユーザーの所有アイテムを Google Play に確認することをお勧めします。 ユーザーのアプリ内購入情報を照会するには、getPurchases リクエストを送信します。 リクエストが成功すると、購入アイテムの商品 ID リスト、個別の購入詳細のリスト、購入に対する署名リストを含む Bundle が Google Play から返されます。
  3. 通常は、ユーザーに購入可能な商品を知らせます。 自身が Google Play で定義したアプリ内アイテムの詳細情報を照会するには、アプリから getSkuDetails リクエストを送信します。 クエリ リクエストでは商品 ID のリストを指定してください。リクエストが成功すると、商品価格、タイトル、説明、購入タイプなどの詳細情報を含む Bundle が Google Play から返されます。
  4. ユーザーがアプリ内アイテムを所有していなければ、購入を開始できます。 購入リクエストを開始するには、アプリから getBuyIntent リクエストを送信します。その際、購入するアイテムの商品 ID やその他のパラメータを指定してください。 Developer Console で新たなアプリ内アイテムを作成した際は、商品 ID を記録しておく必要があります。
    1. Google Play は 購入の精算 UI を立ち上げるためにアプリが使用する PendingIntent を含む Bundle を返します。
    2. アプリは startIntentSenderForResult メソッドを呼び出して、保留していたインテントを発行します。
    3. 精算フローが終了すると（つまり、ユーザーがアイテムを購入または購入をキャンセルすると）、Google Play は Intent レスポンスを onActivityResult メソッドに送信します。 onActivityResult の結果コードには、購入が成功したかキャンセルされたかを示す結果コードが含まれます。 Intent レスポンスには、Google Play が購入トランザクションを一意に識別するために生成した purchaseToken 文字列などの購入アイテム情報が含まれています。 Intent には、プライベート デベロッパー キーで署名した購入署名も含まれます。

Version 3 API の呼び出しやサーバー レスポンスに関する詳細は、アプリ内課金リファレンスをご覧ください。

アプリ内アイテムを消費する

消費の仕組みを利用して、アプリ内アイテムのユーザー所有権をトラックすることができます。

Version 3 では、すべてのアプリ内アイテムが管理されています。つまり、すべてのアプリ内アイテム購入のユーザー所有情報は Google Play で管理されているため、ユーザーの購入情報が必要な時にはいつでもアプリから照会できます。 ユーザーが正常にアプリ内アイテムを購入すると、Google Play に購入記録が残ります。 アプリ内アイテムが購入されると、「所有された」と認識されます。 「所有された」状態のアプリ内アイテムは、Google Play から購入できません。 Google Play で再び購入可能な状態にするには、「所有された」アプリ内アイテムに対する消費リクエストを送る必要があります。 アプリ内アイテムを消費すると、「所有されていない」状態に戻り、以前の購入データは破棄されます。

図 2. 消費リクエストの基本的なシーケンス

ユーザーが所有している商品リストを呼び出すには、アプリから Google Play に getPurchases を送信します。 アプリは consumePurchase を呼び出すことで消費リクエストを送ります。 リクエストの引数には、購入時に Google Play から取得した、アプリ内アイテムに固有の purchaseToken 文字列を指定する必要があります。 Google Play から正常に消費が記録されたことを示すステータス コードが返されます。

消費可能および消費不可なアプリ内アイテム

アプリ内アイテムの消費可否はデベロッパー側で決めることができます。

消費不可アイテム
アプリ内で一度だけ購入され、その効力がずっと続くアプリ内アイテムは、通常消費可能にはしません。 こうしたアイテムは一旦購入されると、永続的にユーザーの Google アカウントに関連付けられます。 消費不可のアプリ内アイテムの例としては、プレミアム アップグレードやレベルパックなどが挙げられます。
消費可能アイテム
逆に、何度も購入可能なアイテムは消費の対象にすることができます。 一般的には、一時的な効力があるアイテムがこれに該当します。 たとえば、ゲーム内キャラクターがライフポイントを増やしたり、追加のゴールドコインを獲得したりするような場合です。 アプリ内で購入したアイテムに効力や効果を付与することを、アプリ内アイテムを 「プロビジョニング」すると言います。 ユーザーにアプリ内アイテムをプロビジョニングする方法を管理し、トラックするのはデベロッパーの責務になります。

重要: 消費可能なアプリ内アイテムをプロビジョニングする前に、Google Play に消費リクエストを送り、消費が正しく記録されたというレスポンスを受け取る必要があります。

消費可能な購入をアプリ内で管理する

消費可能なアプリ内アイテムを購入する基本フローは次のとおりです。

  1. getBuyIntent で、購入フローを開始します。
  2. 購入が正常に完了したことを示す Bundle レスポンスを Google Play から受け取ります。
  3. 購入が成功したら、consumePurchase を呼び出して購入を消費します。
  4. 正常に消費が完了したことを示すレスポンスコードを Google Play から受け取ります。
  5. 消費が完了したら、アプリ内で商品をプロビジョニングします。

その後、アプリの起動時またはログイン時に、ユーザーが未決済の消費可能なアプリ内アイテムを所有しているかどうかを確認します。所有している場合はそのアイテムの消費とプロビジョニングを行ってください。 アプリ内で消費可能なアプリ内アイテムを実装する場合、次のようなアプリの開始フローが推奨されます。

  1. getPurchases リクエストを送信して、ユーザーが所有するアプリ内アイテムを照会します。
  2. 消費可能なアプリ内アイテムがある場合には、consumePurchase を呼び出してアイテムを消費します。 アプリで消費アイテムの購入注文を完了したあと、消費リクエストを送信するタイミングが来る前に、停止または接続が切断されるケースも考えられるため、このステップが必要になります。
  3. 正常に消費が完了したことを示すレスポンスコードを Google Play から受け取ります。
  4. 消費が完了したら、アプリ内で商品をプロビジョニングします。

ローカル キャッシュ

現在 Google Play クライアントではアプリ内課金情報を端末上にローカルでキャッシュできるため、Version 3 API を使って（getPurchases 呼び出しなどによって）、これらの情報をより頻繁に照会することができます。 旧バージョンの API とは違い、Version 3 API の呼び出しの多くは Google Play へのネットワーク接続経由ではなく、キャッシュのルックアップによって行われています。このため、API のレスポンス タイムは飛躍的に短縮されています。