外部コンテンツ リンクのアプリ内統合のガイダンス

このドキュメントでは、Google Play Billing Library の API を統合して、対象となるアプリで外部コンテンツのリンクを提供する方法について説明します。これには、米国のユーザーを Google Play アプリ外に誘導して、アプリ内のデジタル コンテンツやアプリのダウンロードの特典を提供できるようにすることが含まれます。このプログラムについて詳しくは、 プログラムの要件をご覧ください。

Play Billing Library のセットアップ

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

BillingClient を初期化する

BillingClient を初期化するには、 を初期化するの手順に沿って、次の変更を加えます。BillingClient

  • PurchasesUpdatedListener を有効にしない。このリスナーは外部コンテンツのリンクには必要ありません。
  • BillingProgram.EXTERNAL_CONTENT_LINK を指定して enableBillingProgram() を呼び出し、アプリが外部コンテンツのリンクを使用していることを示します。

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

Kotlin

val billingClient = BillingClient.newBuilder(context)
    .enableBillingProgram(
        EnableBillingProgramParams.newBuilder()
            .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
            .build()
    )
    .build()

Java

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
    .build();

Google Play に接続する

BillingClient を初期化したら、Google Play に接続するの説明に沿って Google Play に接続します。

ユーザーの資格を確認する

Google Play に接続したら、 ユーザーが外部コンテンツ リンク プログラムの対象となるかどうかを isBillingProgramAvailableAsync() メソッドを呼び出して確認する必要があります。ユーザーが外部コンテンツのリンク プログラムの対象となる場合、このメソッドは BillingResponseCode.OK を返します。次のサンプルは、ユーザーが外部コンテンツのリンクの対象となるかどうかを確認する方法を示しています。

Kotlin

billingClient.isBillingProgramAvailableAsync(
    BillingProgram.EXTERNAL_CONTENT_LINK,
    object : BillingProgramAvailabilityListener {
        override fun onBillingProgramAvailabilityResponse(
            billingResult: BillingResult,
            billingProgramAvailabilityDetails: BillingProgramAvailabilityDetails
        ) {
            if (billingResult.responseCode != BillingResponseCode.OK) {
                // Handle failures such as retrying due to network errors,
                // handling external content links unavailable, etc.
                return
            }

            // External content links are available. Prepare an external
            // transaction token.
        }
    }
)

Java

billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_CONTENT_LINK,
  new BillingProgramAvailabilityListener() {
    @Override
    public void onBillingProgramAvailabilityResponse(
      int billingProgram, BillingResult billingResult) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external content links unavailable, etc.
            return;
        }

        // External content links are available. Prepare an external
        // transaction token.
      }

    });

他のレスポンス コードに対応する方法については、レスポンス処理のセクションをご覧ください。Kotlin 拡張機能を使用している場合は、Kotlin コルーチンを使用できるため、リスナーを別に定義する必要はありません。

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

次に、Google Play Billing Library から外部取引トークンを生成する必要があります。ユーザーが外部リンクの API を介して外部ウェブサイトにアクセスするたびに、新しい外部取引トークンを生成する必要があります。これは、 createBillingProgramReportingDetailsAsync API を呼び出すことで行えます。トークンは、ユーザーがアプリ外に誘導される直前に生成する必要があります。

注: 外部取引トークンはキャッシュに保存しないでください。ユーザーがアプリ外に誘導されるたびに新しいトークンを 生成する必要があります。

Kotlin

val params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
        .build()

billingClient.createBillingProgramReportingDetailsAsync(
    params,
    object : BillingProgramReportingDetailsListener {
        override fun onCreateBillingProgramReportingDetailsResponse(
            billingResult: BillingResult,
            billingProgramReportingDetails: BillingProgramReportingDetails?
        ) {
            if (billingResult.responseCode != BillingResponseCode.OK) {
                // Handle failures such as retrying due to network errors.
                return
            }
            val externalTransactionToken =
                billingProgramReportingDetails?.externalTransactionToken
            // Persist the external transaction token locally. Pass it to the
            // external website when launchExternalLink is called.
        }
    }
)

Java

BillingProgramReportingDetailsParams params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
        .build();

billingClient.createBillingProgramReportingDetailsAsync(
  params,
  new BillingProgramReportingDetailsListener() {
    @Override
    public void onCreateBillingProgramReportingDetailsResponse(
      BillingResult billingResult,
      @Nullable BillingProgramReportingDetails
        billingProgramReportingDetails) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        String transactionToken =
          billingProgramReportingDetails.getExternalTransactionToken();

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

Kotlin 拡張機能を使用している場合は、Kotlin コルーチンを使用できるため、リスナーを別に定義する必要はありません。

外部リンクを起動する

外部取引トークンが準備できたら、 ユーザーをアプリ外のデジタル コンテンツの特典やアプリのダウンロードに誘導できます。 launchExternalLink メソッドを呼び出してこの API を呼び出すと、ユーザーの設定に応じて、Google Play で追加の情報ダイアログが表示されることがあります。

launchExternalLink メソッドを呼び出す場合は、外部リンク の詳細を LaunchExternalLinkParams を介して提供する必要があります。このクラスには次のパラメータが含まれています。

  • リンク URI - デジタル コンテンツや アプリのダウンロードが提供される外部ウェブサイトへのリンク。アプリのダウンロードの場合、このリンクは Google Play Console で登録して承認される必要があります。
  • リンクタイプ - ユーザーに提供されるコンテンツのタイプ。
  • 起動モード - リンクの起動方法を指定します。アプリのダウンロードの場合は、LAUNCH_IN_EXTERNAL_BROWSER_OR_APP に設定する必要があります。

  • 課金プログラム - BillingProgram.EXTERNAL_CONTENT_LINK に設定します。

Kotlin

val params =
    LaunchExternalLinkParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
        .setLinkUri(Uri.parse("https://www.myapprovedsite.com"))
        .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_APP_DOWNLOAD)
        .setLaunchMode(
            LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP
        )
        .build()

val listener: LaunchExternalLinkResponseListener =
    object : LaunchExternalLinkResponseListener {
        override fun onLaunchExternalLinkResponse(
            billingResult: BillingResult
        ) {
            if (billingResult.responseCode != BillingResponseCode.OK) {
                // Handle failures such as retrying due to network errors.
                return
            }

            // If Launch Mode was set to LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, the
            // user was directed outside of the app by Play. This does not give
            // any information on the user's actions during the link out, such
            // as if a transaction was completed.

            // If Launch Mode was set to CALLER_WILL_LAUNCH_LINK, then your app
            // may proceed to direct the user to the external website.
        }
    }

billingClient.launchExternalLink(activity, params, listener)

Java

LaunchExternalLinkParams params =
  LaunchExternalLinkParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
    .setLinkUri(Uri.parse("https://www.myapprovedsite.com"))
    .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_APP_DOWNLOAD)
    .setLaunchMode(
      LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
    .build()

LaunchExternalLinkResponseListener listener =
  new LaunchExternalLinkResponseListener() {
    @Override
    public void onLaunchExternalLinkResponse(BillingResult billingResult) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        // If Launch Mode was set to LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, the
        // user was directed outside of the app by Play. This does not give
        // any information on the user's actions during the link out, such
        // as if a transaction was completed.

        // If Launch Mode was set to CALLER_WILL_LAUNCH_LINK, then your app
        // may proceed to direct the user to the external website.
    }
  }

billingClient.launchExternalLink(activity, params, listener);

レスポンス処理

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

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

外部コンテンツのリンクをテストする

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

次のステップ

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