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

このガイドでは、API を統合して外部提案をサポートする方法について説明します 対象となるアプリと地域でご利用いただけます。外部提案プログラムの詳細 （資格要件や地域範囲など）については、 プログラムの要件をご覧ください。

Play Billing Library のセットアップ

外部提案用 API を使用するには バージョン 6.2.1 以降の Play Billing Library 依存関係を追加する 追加できます以前のバージョンから移行する必要がある場合は、 移行ガイドの手順に沿って実装してください。 外部提案などです

Google Play に接続する

統合プロセスの最初のステップは、 課金統合ガイドをご覧ください。 BillingClient の初期化:

  • 外部 IP アドレスを使用することを示す新しいメソッドを呼び出す必要があります。 特典: 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。このトークンは、 ユーザーがアプリ外に誘導される直前に生成されます。本来は キャッシュされることはありません。また、ユーザーがリダイレクトされるたびに、新しい ID が生成されます。 使用できます。

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 に報告する必要があります バックエンドから Google Play Developer API を呼び出します。外部取引 レポートが不要な場合は externalTransactionToken は、 createExternalOfferReportingDetailsAsync API。ユーザーが複数の 同じものを使用できます。 externalTransactionToken: 購入ごとに報告します。Google Chat のメッセージ履歴を報告する バックエンド統合ガイドをご覧ください。

レスポンス処理

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

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

外部提案をテストする

ライセンス テスターは、外部提案の統合をテストするために使用する必要があります。マイページ ライセンス テスターが開始した取引については請求されません できます。詳しくは、アプリ ライセンスを使用したアプリ内課金のテストをご覧ください。 ライセンス テスターの設定についてご覧ください。

次のステップ

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