アプリ内プロモーションの AIDL リファレンス

警告: AIDL はすでにサポートが終了しており、将来のリリースで完全に削除される予定です。Google Play 請求サービス機能を実装するには、Google Play 請求サービス ライブラリを使用してください。

このドキュメントでは、Google Play Billing AIDL API を使用してプロモーションを作成する際のテクニカル リファレンス情報について説明します。

プロモーション コードを使用すると、限られたユーザーに無料でコンテンツや機能を提供できます。プロモーション コードを作成したら、利用規約に基づいて配布できます。ユーザーはアプリまたは Google Play ストア アプリでプロモーション コードを入力し、アイテムを無料で受け取ります。プロモーション コードを使うことで、下記のようなさまざまなアイデアを駆使してユーザーを引き込むことができます。

  • ゲームの場合、イベントに参加したプレーヤーだけが入手できるキャラクターやデコレーションなど特別なアイテムを設けるケースが考えられます。デベロッパーはイベントでプロモーション コード付きのカードを配信し、ユーザーはそのコードを入力してアイテムをロック解除します。
  • デベロッパーは潜在的なユーザーにアプリを試用してもらえるよう、ローカル ビジネスでプロモーション コードを配信することもできます。
  • デベロッパーから従業員に友人や家族用コードを贈り、友人と共有してもらうことも可能です。

各プロモーション コードは特定のアイテム ID(別名 SKU)に関連付けられています。プロモーション コードは既存のアプリ内アイテムに対して作成できます。SKU を Play ストアで使用せずに、SKU のプロモーション コードを入力した場合に限りアイテムを入手可能にすることもできます。ユーザーは Play ストアまたはアプリ内でプロモーション コードを入力すると、アイテムの価格を全額支払った場合と同様にそのアイテムを入手できます。アプリ内購入に対応するため、すでにアプリで In-app Billing API のバージョン 3 以降を使用している場合は、簡単にプロモーション コードのサポートを追加できます。

プロモーション コードを作成、利用する

プロモーション コードは Google Play Console で作成します。各プロモーション コードは、Play Console で登録された単一のアイテムに関連付けられています。

ユーザーは、次の 2 つのうちいずれかの方法でプロモーション コードを利用することができます。

  • アプリの通常の購入フローの中でプロモーション コードを入力します。アプリ内課金を実装するをご覧ください。アプリにおいては、お金の代わりにプロモーション コードで支払いを行う点を除いては、通常の購入と変わりはありません。
  • Google Play ストア アプリでコードを利用できます。ユーザーは Google Play ストア アプリで手動でコードを入力できます。または、デベロッパーがアプリ内で URL を生成できます。ユーザーがその URL にアクセスすると、Google Play ストアで自動的にコードが提供されます。コードを自動的に提供するには、以下の構文の URL を生成し、<code> をプロモーション コードで置き換えます。
    https://play.google.com/redeem?code=<code>
    例を次に示します。
    https://play.google.com/redeem?code=bvlkfdxkjghlkgdhlkj
    Android アプリから Google Play へのリンクを生成する方法については、Google Play へのリンクをご覧ください。ユーザーがコードを入力すると、Play ストアの画面に、アプリを開く(最新バージョンがインストールされている場合)、ダウンロード、更新のいずれかの操作を行うように求めるメッセージが表示されます。

アプリでプロモーション コードをサポートする

プロモーション コードをサポートするには、アプリの起動時または再開時に getPurchases() メソッドを呼び出す必要があります。このメソッドは、ユーザーがプロモーション コードを利用して購入したものも含めて、現在の未消費の購入情報を一括して返します。最もシンプルな手法は、アクティビティの onResume() メソッド内で getPurchases() を呼び出すことです。これは、このコールバックがアクティビティの再開時に加え、アクティビティの作成時にも呼び出されるためです。起動時と再開時に getPurchases() を呼び出すことで、アプリが実行されていない間にユーザーが行ったすべての購入とコードの利用を確実に調べることができます。さらに、アプリの実行中にユーザーが行った購入を見逃すようなことがあっても、アクティビティの次の再開時に getPurchases() を呼び出して確認できます。

ユーザーがアプリ内でプロモーション コードを利用できるようにしておく必要があります。アプリ内課金リクエストを行うに記載のとおり、アプリがアプリ内購入のワークフローに対応している場合は、自動的に、アプリ内でのプロモーション コードの利用にも対応します。アプリ内購入 UI を起動した際に、ユーザーにはプロモーション コードで支払うオプションが表示されます。アクティビティの onActivityResult() メソッドは、購入が完了したかどうかをアプリに伝えるレスポンス インテントを受け取ります。ただし、購入と消費のワークフローが完了していない場合には、アプリは引き続き起動時と再開時に getPurchases() を呼び出す必要があります。たとえば、ユーザーが正常にプロモーション コードを利用した後、アイテムを消費する前にアプリがクラッシュした場合でも、次の起動時にアプリが getPurchases() を呼び出せば、購入情報を受け取ることができます。

また、ユーザーがアプリの実行中に Play ストア アプリでプロモーション コードを利用する場合もサポートする必要があります。PURCHASES_UPDATED インテントに対するリスナーを登録すると、ユーザーがコードを利用した際に、即座にアプリで検知できるようになります。Play ストアは、ユーザーがプロモーション コードを利用するたびに必ずこのインテントを発行します。

PURCHASES_UPDATED インテントをリッスンするには、BroadcastReceiver オブジェクトを動的に作成し、com.android.vending.billing.PURCHASES_UPDATED を受信するように登録します。アクティビティの onResume() メソッドに次のようなコードを追加してレシーバーを登録します。

Kotlin

val filter = IntentFilter("com.android.vending.billing.PURCHASES_UPDATED")

Java

IntentFilter filter = new IntentFilter("com.android.vending.billing.PURCHASES_UPDATED");

ユーザーが購入すると、システムがブロードキャスト レシーバーの onReceive() メソッドを呼び出します。ユーザーの購入内容を確認するには、このメソッドで getPurchases() を呼び出す必要があります。

アプリが実行中でないときのオーバーヘッドを減らすには、アクティビティの onPause() メソッドでブロードキャスト レシーバーの登録を解除する必要があります。

Kotlin

unRegisterReceiver(myPromoReceiver);

Java

unRegisterReceiver(myPromoReceiver);

注: このブロードキャスト レシーバーはアプリのマニフェストには登録しないでください。マニフェストにレシーバーを宣言すると、アプリが実行中でないときにユーザーが購入した場合、システムがインテントを処理しようとしてアプリを起動してしまいます。この動作は不要なだけでなく、ユーザーを困惑させる可能性もあります。ユーザーがアプリを実行していない間に購入を行ったかどうかを調べるには、ユーザーがアプリを起動した際に getPurchases() を呼び出します。

アプリ内プロモーションをテストする

アプリがアプリ内プロモーションをサポートしている場合、以下のユースケースをテストします。

ユーザーがアプリ内でプロモーション コードを利用する

アプリ内の購入フローに沿ってユーザーがプロモーション コードを利用した場合は、アプリ内課金リクエストを行うに記載のとおり、システムがアクティビティの onActivityResult() メソッドを呼び出して購入を処理します。ユーザーが代金を支払った場合でも、プロモーション コードを利用した場合でも、onActivityResult() が購入を正しく処理しているか検証します。

ユーザーが Google Play ストア内でプロモーション コードを利用する

ユーザーが Play ストア内でプロモーション コードを利用した場合、いくつかのワークフローが考えられます。各ワークフローをそれぞれ検証します。

アプリがインストールされていない場合

デバイスにインストールしていないアプリのプロモーション コードをユーザーが利用しようとした場合、Play ストアは、アプリをインストールするようユーザーに求めます(アプリがインストールされていても最新版ではない場合、Play ストアは、アプリをアップデートするようユーザーに求めます)。アプリがインストールされていないデバイスで、次のシーケンスをテストします。

  1. ユーザーが、Play ストア内でアプリのプロモーション コードを利用します。Play ストアが、アプリをインストールするようユーザーに求めます。
  2. ユーザーが、アプリをインストールして起動します。起動時にアプリが getPurchases() を呼び出し、ユーザーがプロモーション コードを使って行った購入を正しく検出しているか検証します。

アプリはインストールされているが、実行中ではない場合

デバイスにインストールされているアプリのプロモーション コードをユーザーが利用しようとした場合、Play ストアは、そのアプリに切り替えるようユーザーに求めます。アプリはインストール済みだが実行中ではないデバイスで、次のシーケンスをテストします。

  1. ユーザーが、Play ストア内でアプリのプロモーション コードを利用します。Play ストアが、アプリを切り替えるようユーザーに求めます。
  2. ユーザーが、対象のアプリを起動します。起動時にアプリが getPurchases() を呼び出し、ユーザーがプロモーション コードを使って行った購入を正しく検出しているか検証します。

アプリがインストールされていて、実行中の場合

デバイス上で現在実行中のアプリのプロモーション コードをユーザーが利用しようとした場合、Play ストアは、PURCHASES_UPDATED インテントを通じてアプリに通知します。次のシーケンスをテストします。

  1. ユーザーが、対象のアプリを起動します。PURCHASES_UPDATED インテントを受信できるようにアプリが正しく登録されているか検証します。
  2. ユーザーは、手動で、あるいはプロモーション コードを含む生成 URL を使用して、Play ストア アプリを起動し、対象アプリのプロモーション コードを利用します。Play ストアが PURCHASES_UPDATED インテントを発行します。アプリの onReceive() コールバックがトリガーされて、インテントを処理しているか検証します。
  3. onReceive() メソッドが、getPurchases() を呼び出して、インテントに応答する必要があります。アプリがこのメソッドを呼び出し、ユーザーがプロモーション コードを使用して行った購入を正しく検出しているか検証します。
  4. ユーザーが、対象アプリに戻ります。購入したアイテムをユーザーが所持しているか検証します。