このページは Cloud Translation API によって翻訳されました。

外部特典プログラムのアプリ内統合のガイダンス

このガイドでは、API を統合して、対象となるアプリとリージョンで外部オファーをサポートする方法について説明します。資格要件や地理的範囲など、外部オファープログラムの詳細については、プログラムの要件をご覧ください。

Play Billing Library のセットアップ

外部オファーの API を使用するには、Android アプリに Play Billing Library の依存関係のバージョン 6.2.1 以降を追加します。以前のバージョンから移行する必要がある場合は、外部オファーを実装する前に移行ガイドの手順に沿って対応してください。

Google Play に接続する

統合プロセスの最初のステップは、課金の統合ガイドで説明されている手順と同じですが、BillingClient の初期化時にいくつかの違いがあります。

外部クーポンを使用することを示す新しいメソッド enableExternalOffer を呼び出す必要があります。

次の例は、これらの変更を行った BillingClient の初期化方法を示しています。

Kotlin

var billingClient = BillingClient.newBuilder(context)
  .enableExternalOffer()
  .build()

Java

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableExternalOffer()
    .build();

BillingClient を初期化したら、統合ガイドの説明のとおりに Google Play への接続を確立する必要があります。

使用できるか確認する

アプリは isExternalOfferAvailableAsync を呼び出して、外部特典が利用可能であることを確認する必要があります。

外部オファーが利用可能な場合、この API は BillingResponseCode.OK を返します。アプリが他のレスポンスコードに応答する方法については、レスポンス処理をご覧ください。

Kotlin


billingClient.isExternalOfferAvailableAsync(
  object : ExternalOfferAvailabilityListener {
    override fun onExternalOfferAvailabilityResponse(
      billingResult: BillingResult) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external offers unavailable, etc.
            return
        }

        // External offers are available. Continue with steps in the
        // guide.
})

Java


billingClient.isExternalOfferAvailableAsync(
  new ExternalOfferAvailabilityListener() {
    @Override
    public void onExternalOfferAvailabilityResponse(
      BillingResult billingResult) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external offers being unavailable, etc.
            return;
        }
        // External offers are available. Continue with steps in the
        // guide.
      }

});

外部取引トークンを準備する

外部取引を Google Play に報告するには、Play Billing Library から生成された外部取引トークンが必要です。ユーザーが外部オファー API を介して外部ウェブサイトにアクセスするたびに、新しい外部取引トークンを生成する必要があります。これを行うには、createExternalOfferReportingDetailsAsync API を呼び出します。このトークンは、ユーザーがアプリの外に誘導される直前に生成する必要があります。このトークンはキャッシュに保存しないでください。ユーザーがアプリの外に誘導されるたびに新しいトークンを生成する必要があります。

Kotlin


billingClient.createExternalOfferReportingDetailsAsync(
  object : ExternalOfferReportingDetailsListener {
    override fun onExternalOfferReportingDetailsResponse(
      billingResult: BillingResult,
      externalOfferReportingDetails: ExternalOfferReportingDetails?) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return
        }
        val externalTransactionToken =
            externalOfferReportingDetails?.externalTransactionToken
        // Persist the transaction token locally. Pass it to the external
        // website when showExternalOfferInformationDialog is called.
    }
})

Java


billingClient.createExternalOfferReportingDetailsAsync(
  new ExternalOfferReportingDetailsListener() {
    @Override
    public void onExternalOfferReportingDetailsResponse(
      BillingResult billingResult,
      @Nullable ExternalOfferReportingDetails
        externalOfferReportingDetails) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        String transactionToken =
          externalOfferReportingDetails.getExternalTransactionToken();

        // Persist the external transaction token locally. Pass it to the
        // external website when showExternalOfferInformationDialog is
        // called.
      }
});

ユーザー向け情報ダイアログ

外部オファーと統合するには、対象アプリで情報画面を表示して、アプリから外部ウェブサイトに誘導されることをユーザーが把握できるようにする必要があります。情報画面は、外部オファーにリンクする前に、毎回 showExternalOfferInformationDialog API を呼び出してユーザーに表示する必要があります。

Kotlin


// An activity reference from which the external offers information dialog
// will be launched.
val activity : Activity = ...;

val listener : ExternalOfferInformationDialogListener =
  ExternalOfferInformationDialogListener {
      override fun onExternalOfferInformationDialogResponse(
        billingResult: BillingResult){
        // Check billingResult
    }
}

val billingResult = billingClient.showExternalOfferInformationDialog(
  activity, listener)

Java


// An activity reference from which the external offers information dialog
// will be launched.
Activity activity = ...;

ExternalOfferInformationDialogListener listener =
  new ExternalOfferInformationDialogListener() {
    @Override
    public void onExternalOfferInformationDialogResponse(
      BillingResult billingResult) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
          // Handle failures such as retrying due to network errors.
        }
        // Open the external website, passing along the external transaction
        // token as a URL parameter. If the user purchases an item, be sure
        // to report the transaction to Google Play.
      }
}

BillingResult billingResult =
  billingClient.showExternalOfferInformationDialog(activity, listener);

このメソッドが BillingResponseCode.OK を返した場合、アプリはユーザーを外部ウェブサイトに誘導できます。このメソッドが BillingResponseCode.USER_CANCELED を返した場合、アプリはウェブサイトを続けて開けません。

Google Play に取引を報告する

外部取引はすべて、バックエンドから Google Play Developer API を呼び出して Google Play に報告する必要があります。createExternalOfferReportingDetailsAsync API を使用して取得した externalTransactionToken を提供しながら、外部トランザクションを報告する必要があります。ユーザーが複数の購入を行った場合は、同じ externalTransactionToken を使用して購入ごとに報告できます。取引を報告する方法については、バックエンド統合ガイドをご覧ください。

レスポンス処理

エラーが発生した場合、メソッド isExternalOfferAvailableAsync、createExternalOfferReportingDetailsAsync、showExternalOfferInformationDialog は BillingResponseCode.OK 以外のレスポンスを返すことがあります。これらのレスポンスコードは、次のように処理することを検討してください。

ERROR: これは内部エラーです。取引を進めたり外部ウェブサイトを開いたりしないでください。次回ユーザーをアプリ外に誘導しようとしたときに、showExternalOfferInformationDialog() を呼び出して情報ダイアログを表示して再試行します。
FEATURE_NOT_SUPPORTED: 外部オファーの API が、現在のデバイスの Google Play ストアでサポートされていません。取引を進めたり外部ウェブサイトを開いたりしないでください。
USER_CANCELED: 外部ウェブサイトを開きません。次回ユーザーをアプリ外に誘導しようとしたときに、showExternalOfferInformationDialog() を再度呼び出して情報ダイアログを表示します。
BILLING_UNAVAILABLE: 取引が外部オファーの対象ではないため、このプログラムでは続行できません。これは、ユーザーがこのプログラムの対象国に居住していないか、アカウントがプログラムに正常に登録されていないことが原因です。後者の場合は、Google Play Console で登録ステータスを確認してください。
DEVELOPER_ERROR: リクエストでエラーが発生しています。先に進む前に、デバッグメッセージを使用してエラーを特定および修正してください。
NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE: 適切な再試行ポリシーで処理する必要がある一時的なエラーです。SERVICE_DISCONNECTED の場合は、Google Play との接続を再確立してから再試行してください。

外部特典をテストする

外部オファーの統合をテストするには、ライセンステスターを使用する必要があります。ライセンステスターアカウントによって開始された取引については、請求は発生しません。ライセンステスターの設定について詳しくは、アプリライセンスを使用してアプリ内課金をテストするをご覧ください。

次のステップ

アプリ内統合が完了すると、バックエンドを統合する準備が整います。