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

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

Play Billing Library のセットアップ

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

課金クライアントを初期化する

請求クライアントを初期化するには、BillingClient を初期化するで説明されている手順と同じ手順に沿って、次の変更を加えます。

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

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

Kotlin

val billingClient = BillingClient.newBuilder(context)
  .enableBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
  .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(
      billingProgram: Int, billingResult: BillingResult) {
        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 コルーチンを使用できるため、リスナーを別に定義する必要はありません。

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

次に、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 に設定する必要があります。

  • Billing Program - 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.OK 以外の BillingResponseCode を返すことがあります。これらのレスポンス コードは次のように処理することを検討してください。

  • 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 との接続を再確立してから再試行してください。

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

ライセンス テスターは、外部提案の統合をテストするために使用する必要があります。ライセンス テスター アカウントによって開始されたトランザクションに対しては請求されません。ライセンス テスターの構成について詳しくは、アプリ ライセンスを使用したアプリ内課金のテストをご覧ください。

次のステップ

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