6 月 3 日の「#Android11: The Beta Launch Show」にぜひご参加ください。

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

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

このドキュメントでは、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 ストアに表示されます(アプリがインストールされているが、最新バージョンではない場合は、アプリの更新を求めるメッセージが表示されます)。アプリがインストールされていないデバイスで、次のシーケンスをテストします。

  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. ユーザーがアプリに戻ります。購入したアイテムをユーザーが所持していることを確認します。