Reminder: By Aug 31, 2026, all new apps and updates to existing apps must use Billing Library version 8 or later. If you need more time to update your app, you can request an extension until Nov 1, 2026. Learn about Play Billing Library version deprecation.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

应用内集成指南（适用于结算方式选择）

本指南介绍了如何将应用与 Play 结算库 API 集成，以便为用户提供结算选项。

与 PBL 集成

您可以在四种场景中将结算选择与 PBL 集成。具体方案因选择屏幕的呈现方和付款发生的位置而异。下表列出了集成方案：

		付款在哪个环节进行？
		应用内	外部网页链接
您要呈现哪个结算方式选择界面？	Google Play 的	场景 1A Google 会呈现选择界面，备选结算系统在您的应用内处理。	场景 1B 应用开发者呈现选择界面，备选结算系统在您的应用内处理。
您要呈现哪个结算方式选择界面？	您自己的（符合用户体验指南）	场景 2A Google 会呈现选择界面，用户可以通过链接前往您自己的网站进行购买。	场景 2B 应用开发者呈现选择界面，用户通过链接前往您自己的网站进行购买。

下图详细说明了每种情形下的结算方式选择流程：

结算选项流程，显示了四种集成方案的 API 调用和用户互动序列。 — **图 1.** 结算方式选择集成方案

PBL 集成方案

根据您的集成方案，按照本部分中的步骤在应用中实现结算方式选择。

处理场景 1A

Google 会呈现选择界面，备选结算系统会在您的应用内处理。请按以下步骤操作，以在此场景中启用结算选择：

在构建 BillingClient 实例时，使用 EnableBillingProgramParams 调用 enableBillingProgram，然后启动连接。例如：

Kotlin


// Build the parameters to enable the Billing Choice program and assign the listener
// to handle user selection of the developer-provided billing option.
val params = EnableBillingProgramParams.newBuilder()
    .setBillingProgram(BillingProgram.BILLING_CHOICE)
    .setDeveloperProvidedBillingListener(developerProvidedBillingListener)
    .build()

// Build the parameters to enable support for pending purchases.
val pendingPurchasesParams = PendingPurchasesParams.newBuilder()
    .enableOneTimeProducts()
    .build()

// Construct the BillingClient instance with the purchases updated listener,
// pending purchases support, and the billing choice params.
val billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases(pendingPurchasesParams)
    .enableBillingProgram(params)
    .build()

// Establish a connection to Google Play
val billingResult = suspendCancellableCoroutine { continuation ->
    billingClient.startConnection(object : BillingClientStateListener {
        // Called when the connection setup process completes.
        override fun onBillingSetupFinished(billingResult: BillingResult) {
            // Resume the coroutine and pass back the BillingResult to the caller.
            continuation.resume(billingResult)
        }

        // Called if the connection to the Play Store service is dropped.
        // This prevents the await or suspension point from hanging indefinitely.
        override fun onBillingServiceDisconnected() {
            continuation.resume(
                BillingResult.newBuilder()
                    .setResponseCode(BillingClient.BillingResponseCode.SERVICE_DISCONNECTED)
                    .setDebugMessage("Billing service disconnected during connection setup")
                    .build()
            )
        }
    })
}

Java


EnableBillingProgramParams params = EnableBillingProgramParams.newBuilder()
        .setBillingProgram(BillingProgram.BILLING_CHOICE)
        .setDeveloperProvidedBillingListener(developerProvidedBillingListener)
        .build();

BillingClient billingClient = BillingClient.newBuilder(context)
        .setListener(purchasesUpdatedListener)
        .enablePendingPurchases(
                PendingPurchasesParams.newBuilder()
                        .enableOneTimeProducts()
                        .build()
        )
        .enableBillingProgram(params)
        .build();

验证用户是否可以使用 Google 结算选项。

调用 isBillingProgramAvailableAsync 检查计划是否可用，然后调用 queryProductDetailsAsync 显示可用的商品。例如：

Kotlin


val (billingResult, billingProgramAvailabilityDetails) = billingClient.isBillingProgramAvailable(BillingProgram.BILLING_CHOICE)

if (billingResult.responseCode == BillingResponseCode.OK) {
    val billingChoiceAvailabilityDetails = billingProgramAvailabilityDetails.billingChoiceAvailabilityDetails
    if (billingChoiceAvailabilityDetails != null &&
        billingChoiceAvailabilityDetails.choiceScreenType == ChoiceScreenType.GOOGLE_RENDERED
    ) {
        // Billing choice is available. Query products and proceed.

    } else {
        // Fallback to other available programs.
    }
} else {
    // Fallback to other available programs.
}

Java


// ...
billingClient.isBillingProgramAvailableAsync(
    BillingProgram.BILLING_CHOICE,
    (billingResult, billingProgramAvailabilityDetails) -> {
        if (billingResult.getResponseCode() == BillingResponseCode.OK) {
            BillingChoiceAvailabilityDetails billingChoiceAvailabilityDetails =
                billingProgramAvailabilityDetails.getBillingChoiceAvailabilityDetails();

            if (billingChoiceAvailabilityDetails != null &&
                billingChoiceAvailabilityDetails.getChoiceScreenType() == ChoiceScreenType.GOOGLE_RENDERED) {
                // Billing choice is available. Query products and proceed.
            } else {
                // Fallback to other available programs.
            }
        } else {
            // Fallback to other available programs.
        }
    }
);

注意：billingProgramAvailabilityDetails 用于指示 Google 渲染的结算选项界面或开发者渲染的结算选项界面是否可用。

当用户点击“购买”时，调用 launchBillingFlow 以触发购买流程。如果结算选项可用，请将 DeveloperBillingOptionParams 传递给 BillingFlowParams。例如：

Kotlin


val developerBillingOptionParams = DeveloperBillingOptionParams.newBuilder()
    .setBillingProgram(BillingProgram.BILLING_CHOICE)
    .build()

val billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(productDetailsParamsList)
    .enableDeveloperBillingOption(developerBillingOptionParams)
    .build()

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

Java


DeveloperBillingOptionParams developerBillingOptionParams =
    DeveloperBillingOptionParams.newBuilder()
        .setBillingProgram(BillingProgram.BILLING_CHOICE)
        .build();
BillingFlowParams billingFlowParams =
    BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(productDetailsParamsList)
        .enableDeveloperBillingOption(developerBillingOptionParams)
        .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

注意：家长控制功能仅面向受监督的用户显示。

按如下方式处理用户对结算类型的选择：
- 如果用户选择 Play 结算服务，结算结果会返回到第 1 步中注册的 PurchasesUpdatedListener。
- 如果用户选择您的备选结算系统，结算结果会返回到第 1 步中注册的 DeveloperProvidedBillingListener。返回的 DeveloperProvidedBillingDetails 在这种情况下包含 externalTransactionToken。该令牌将用于交易报告。

处理方案 1B

开发者呈现选择界面，并在应用内处理备选结算系统。请按以下步骤操作，在此方案中启用结算选择：

在构建 BillingClient 实例时，调用 EnableBillingProgramParams 中的 enableBillingProgram（不含 DeveloperProvidedBillingListener），然后启动连接。例如：

Kotlin


// Build the parameters to enable the Billing Choice program.
val params = EnableBillingProgramParams.newBuilder()
    .setBillingProgram(BillingProgram.BILLING_CHOICE)
    .build()

// Construct the BillingClient instance with the purchases updated listener,
// pending purchases support, and the billing choice params.
val billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases()
    .enableBillingProgram(params)
    .build()

// Establish a connection to Google Play
val billingResult = suspendCancellableCoroutine<BillingResult> { continuation ->
    billingClient.startConnection(object : BillingClientStateListener {
        // Called when the connection setup process completes.
        override fun onBillingSetupFinished(billingResult: BillingResult) {
            // Resume the coroutine and pass back the BillingResult to the caller.
            continuation.resume(billingResult)
        }

        // Called if the connection to the Play Store service is dropped.
        // This prevents the await or suspension point from hanging indefinitely.
        override fun onBillingServiceDisconnected() {
            continuation.resume(
                BillingResult.newBuilder()
                    .setResponseCode(BillingClient.BillingResponseCode.SERVICE_DISCONNECTED)
                    .setDebugMessage("Billing service disconnected during connection setup")
                    .build()
            )
        }
    })
}

Java


EnableBillingProgramParams params = EnableBillingProgramParams.newBuilder()
        .setBillingProgram(BillingProgram.BILLING_CHOICE)
        .build();

BillingClient billingClient = BillingClient.newBuilder(context)
        .setListener(purchasesUpdatedListener)
        .enablePendingPurchases()
        .enableBillingProgram(params)
        .build();

验证开发者提供的结算选项是否适用于相应用户。

调用 isBillingProgramAvailableAsync 检查计划是否可用，然后调用 queryProductDetailsAsync 显示可用的商品。例如：

Kotlin


val (billingResult, billingProgramAvailabilityDetails) =
    billingClient.isBillingProgramAvailable(BillingProgram.BILLING_CHOICE)

if (billingResult.responseCode == BillingResponseCode.OK) {
    val billingChoiceAvailabilityDetails =
        billingProgramAvailabilityDetails.billingChoiceAvailabilityDetails

    if (billingChoiceAvailabilityDetails != null &&
        billingChoiceAvailabilityDetails.choiceScreenType == ChoiceScreenType.DEVELOPER_RENDERED
    ) {
        // Billing choice is available. Query products and proceed.
        // You can inspect details such as:
        // - billingChoiceAvailabilityDetails.choiceScreenType
        // - billingChoiceAvailabilityDetails.isExternalLinkAvailable
    } else {
        // Fallback to other available programs.
    }
} else {
    // Fallback to other available programs.
}

Java


// ...
billingClient.isBillingProgramAvailableAsync(
    BillingProgram.BILLING_CHOICE,
    (billingResult, billingProgramAvailabilityDetails) -> {
        if (billingResult.getResponseCode() == BillingResponseCode.OK) {
            BillingChoiceAvailabilityDetails billingChoiceAvailabilityDetails =
                billingProgramAvailabilityDetails.getBillingChoiceAvailabilityDetails();

            if (billingChoiceAvailabilityDetails != null
                    && billingChoiceAvailabilityDetails.getChoiceScreenType() == ChoiceScreenType.DEVELOPER_RENDERED) {
                // Billing choice is available. Query products and proceed.
                // You can inspect details such as:
                // - billingChoiceAvailabilityDetails.getChoiceScreenType()
                // - billingChoiceAvailabilityDetails.isExternalLinkAvailable()
            } else {
                // Fallback to other available programs.
            }
        } else {
            // Fallback to other available programs.
        }
    }
);

注意：billingProgramAvailabilityDetails 表示 Google 渲染的结算选项界面或开发者渲染的结算选项界面是否可用。

调用 getBillingChoiceInfoAsync 方法以获取 Play 结算服务横幅和会员信息。例如：

Kotlin


// 1. Create the params required for the request
val params = GetBillingChoiceInfoParams.newBuilder()
    .setBillingProgram(BillingClient.BillingProgram.BILLING_CHOICE)
    .setPlayBillingChoiceImageLayout(GetBillingChoiceInfoParams.ImageLayout.RECTANGULAR_FOUR_BY_ONE)
    .build()

// 2. Call the suspend method on your billingClient instance
val (billingResult, playBillingChoiceInfo) = billingClient.getBillingChoiceInfo(params)

if (billingResult.responseCode == BillingResponseCode.OK && playBillingChoiceInfo != null) {
    // Access the URL of the image associated with the Play Billing Choice
    val imageUrl = playBillingChoiceInfo.playBillingChoiceImageUrl

    // Access the Play Loyalty string information, if available
    val loyaltyInfo = playBillingChoiceInfo.playBillingLoyaltyInfo

    // Populate your developer-rendered UI elements
    playBillingLoyaltyTextView.text = loyaltyInfo
    loadImage(imageUrl, playBillingImageView)
} else {
    // Handle error scenarios
}

Java


// 1. Create the params required for the request
GetBillingChoiceInfoParams params = GetBillingChoiceInfoParams.newBuilder()
    .setBillingProgram(BillingClient.BillingProgram.BILLING_CHOICE)
    .setPlayBillingChoiceImageLayout(GetBillingChoiceInfoParams.ImageLayout.RECTANGULAR_FOUR_BY_ONE)
    .build();
// 2. Call the method asynchronously on your billingClient instance
billingClient.getBillingChoiceInfoAsync(params, (billingResult, playBillingChoiceInfo) -> {
    if (billingResult.getResponseCode() == BillingResponseCode.OK && playBillingChoiceInfo != null) {
      // Access the URL of the image associated with the Play Billing Choice
        String imageUrl = playBillingChoiceInfo.getPlayBillingChoiceImageUrl();
        // Access the Play Loyalty string information, if available
        String loyaltyInfo = playBillingChoiceInfo.getPlayBillingLoyaltyInfo();

        // Populate your developer-rendered UI elements
        playBillingLoyaltyTextView.setText(loyaltyInfo);
          loadImage(imageUrl, playBillingImageView);
      } else {
          // Handle error scenarios
      }
});

创建将 DeveloperBillingType 设置为 IN_APP 的外部交易令牌。例如：

Kotlin


// Build the parameters specifying the billing program and that the billing type is IN_APP.
val params = BillingProgramReportingDetailsParams.newBuilder()
    .setBillingProgram(BillingProgram.BILLING_CHOICE)
    .setDeveloperBillingType(DeveloperBillingType.IN_APP)
    .build()

// Call the suspending extension function to request the reporting details
val (billingResult, billingProgramReportingDetails) =
    billingClient.createBillingProgramReportingDetails(params)
    
if (billingResult.responseCode != BillingResponseCode.OK) {
    // Handle failures such as retrying due to network errors.
    return
}

// Extract the transaction token from the returned reporting details
val transactionToken = billingProgramReportingDetails?.externalTransactionToken

// Persist the external transaction token locally. Pass it to
// DeveloperBillingOptionParams when launchBillingFlow is called.
// It can also be used as part of your external website

Java


BillingProgramReportingDetailsParams params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.BILLING_CHOICE)
        .setDeveloperBillingType(DeveloperBillingType.IN_APP)
        .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
            // DeveloperBillingOptionParams when launchBillingFlow is called.
            // It can also be used as part of your external website
        }
    }
);

当用户点击“购买”时，调用 showBillingProgramInformationDialog 以显示信息对话框。例如，请参阅面向用户的信息对话框。必须在请求中设置第 4 步中的 BillingProgram 和 transactionToken。

注意：家长控制功能仅面向受监督的用户显示。
如果上一步的结果为 OK，则启动您的替代结算方式选择界面。
按如下方式处理用户对结算类型的选择：
- 如果用户选择 Play 结算服务，请按照标准 Play 结算服务指南调用 launchBillingFlow。结算结果会返回到第 1 步中注册的 PurchasesUpdatedListener。
- 如果用户选择您的备选结算系统，您必须自行处理交易，并使用在第 4 步中生成的令牌向 Play 报告交易。

处理场景 2A

Google 会呈现选择界面，替代结算方式会在您的应用之外处理。请按以下步骤操作，以在此场景中启用结算方式选择：

在构建 BillingClient 实例时，使用 EnableBillingProgramParams 调用 enableBillingProgram，然后启动连接。例如：

Kotlin


// Build the parameters to enable the Billing Choice program and assign the listener
// to handle user selection of the developer-provided billing option.
val params = EnableBillingProgramParams.newBuilder()
    .setBillingProgram(BillingProgram.BILLING_CHOICE)
    .setDeveloperProvidedBillingListener(developerProvidedBillingListener)
    .build()

// Build the parameters to enable support for pending purchases.
val pendingPurchasesParams = PendingPurchasesParams.newBuilder()
    .enableOneTimeProducts()
    .build()

// Construct the BillingClient instance with the purchases updated listener,
// pending purchases support, and the billing choice params.
val billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases(pendingPurchasesParams)
    .enableBillingProgram(params)
    .build()

// Establish a connection to Google Play
val billingResult = suspendCancellableCoroutine { continuation ->
    billingClient.startConnection(object : BillingClientStateListener {
        // Called when the connection setup process completes.
        override fun onBillingSetupFinished(billingResult: BillingResult) {
            // Resume the coroutine and pass back the BillingResult to the caller.
            continuation.resume(billingResult)
        }

        // Called if the connection to the Play Store service is dropped.
        // This prevents the await or suspension point from hanging indefinitely.
        override fun onBillingServiceDisconnected() {
            continuation.resume(
                BillingResult.newBuilder()
                    .setResponseCode(BillingClient.BillingResponseCode.SERVICE_DISCONNECTED)
                    .setDebugMessage("Billing service disconnected during connection setup")
                    .build()
            )
        }
    })
}

Java


EnableBillingProgramParams params = EnableBillingProgramParams.newBuilder()
        .setBillingProgram(BillingProgram.BILLING_CHOICE)
        .setDeveloperProvidedBillingListener(developerProvidedBillingListener)
        .build();

BillingClient billingClient = BillingClient.newBuilder(context)
        .setListener(purchasesUpdatedListener)
        .enablePendingPurchases(
                PendingPurchasesParams.newBuilder()
                        .enableOneTimeProducts()
                        .build()
        )
        .enableBillingProgram(params)
        .build();

验证以下各项的可用性：

Google 呈现的结算方式选择界面
外部网页链接

调用 isBillingProgramAvailableAsync 检查计划是否可用，然后调用 queryProductDetailsAsync 显示可用的商品。例如：

Kotlin


// Check the availability of the billing choice program asynchronously using coroutines
val (billingResult, billingProgramAvailabilityDetails) =
    billingClient.isBillingProgramAvailable(BillingProgram.BILLING_CHOICE)

// Ensure the billing program query succeeded
if (billingResult.responseCode == BillingResponseCode.OK) {
    // Retrieve the availability details specific to the billing choice program
    val billingChoiceAvailabilityDetails =
        billingProgramAvailabilityDetails.billingChoiceAvailabilityDetails

    // Check if billing choice is available, renders via Google Play, and external link is supported
    if (billingChoiceAvailabilityDetails != null &&
        billingChoiceAvailabilityDetails.choiceScreenType == ChoiceScreenType.GOOGLE_RENDERED &&
        billingChoiceAvailabilityDetails.isExternalLinkAvailable
    ) {
        // Billing choice is available and external transaction links are supported. Query products and proceed.
    } else {
        // Fallback to other available programs.
    }
} else {
    // Fallback to other available programs.
}

Java


// ...
billingClient.isBillingProgramAvailableAsync(
    BillingProgram.BILLING_CHOICE,
    (billingResult, billingProgramAvailabilityDetails) -> {
        if (billingResult.getResponseCode() == BillingResponseCode.OK) {
            BillingChoiceAvailabilityDetails billingChoiceAvailabilityDetails =
                billingProgramAvailabilityDetails.getBillingChoiceAvailabilityDetails();

            if (billingChoiceAvailabilityDetails != null
                    && billingChoiceAvailabilityDetails.getChoiceScreenType() == ChoiceScreenType.GOOGLE_RENDERED
                    && billingChoiceAvailabilityDetails.isExternalLinkAvailable()) {
                // Billing choice is available and external transaction links are supported.
                // Query products and proceed.
            } else {
                // Fallback to other available programs.
            }
        } else {
            // Fallback to other available programs.
        }
    }
);

当用户表示有意购买时，调用 createBillingProgramReportingDetailsAsync 以创建外部交易令牌。例如：

Kotlin


// Build the parameters for creating reporting details
val params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.BILLING_CHOICE)
        .setDeveloperBillingType(DeveloperBillingType.EXTERNAL_LINK)
        .build()

// Call the suspend function to create billing program reporting details
val (billingResult, billingProgramReportingDetails) =
    billingClient.createBillingProgramReportingDetails(params)

// Handle response failure cases
if (billingResult.responseCode != BillingResponseCode.OK) {
    // Handle failures such as retrying due to network errors.
    return
}

// Retrieve the external transaction token
val transactionToken =
    billingProgramReportingDetails?.externalTransactionToken

// Persist the external transaction token locally. Pass it to
// DeveloperBillingOptionParams when launchBillingFlow is called.
// It can also be used as part of your external website

Java


BillingProgramReportingDetailsParams params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.BILLING_CHOICE)
        .setDeveloperBillingType(DeveloperBillingType.EXTERNAL_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
            // DeveloperBillingOptionParams when launchBillingFlow is called.
            // It can also be used as part of your external website.
        }
    }
);

当用户点击“购买”时，调用 launchBillingFlow 以触发购买流程。如果用户可以选择结算方式，请执行以下操作：

将 DeveloperBillingOptionParams 传递给 BillingFlowParams。
将第 3 步中的外部交易令牌传递给 DeveloperBillingOptionParams。

例如：

Kotlin


// Build the developer billing option parameters with the external link URI,
// the transaction token, and browser/app launch mode.
val developerBillingOptionParams =
    DeveloperBillingOptionParams.newBuilder()
        .setBillingProgram(BillingProgram.BILLING_CHOICE)
        .setLinkUri(Uri.parse("https://www.example.com/external/purchase"))
        .setExternalTransactionToken(transactionToken)
        .setLaunchMode(
            DeveloperBillingOptionParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP
        )
        .build()

Java


DeveloperBillingOptionParams developerBillingOptionParams =
    DeveloperBillingOptionParams.newBuilder()
        .setBillingProgram(BillingProgram.BILLING_CHOICE)
        .setLinkUri(Uri.parse("https://www.example.com/external/purchase"))
        .setExternalTransactionToken(transactionToken)
        .setLaunchMode(
          DeveloperBillingOptionParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
        .build();

注意：家长控制功能仅面向受监督的用户显示。

按如下方式处理用户对结算类型的选择：
- 如果用户选择 Play 结算服务，请按照标准 Play 结算服务指南调用 launchBillingFlow。结算结果会返回到第 1 步中注册的 PurchasesUpdatedListener。
- 如果用户选择您的备选结算系统，结算结果会返回到步骤
  1. 返回的 DeveloperProvidedBillingDetails 包含在第 4 步中传递给 DeveloperBillingOptionParams 的 externalTransactionToken（如果它是有效令牌）。

处理场景 2B

开发者呈现选择界面，备选结算系统在应用外部处理。请按以下步骤操作，在此场景中启用结算选择：

在构建 BillingClient 实例时，调用不含 EnableBillingProgramParams 中 DeveloperProvidedBillingListener 的 enableBillingProgram，然后启动连接。例如：

Kotlin


// Build the parameters to enable the Billing Choice program.
val params = EnableBillingProgramParams.newBuilder()
    .setBillingProgram(BillingProgram.BILLING_CHOICE)
    .build()

// Construct the BillingClient instance with the purchases updated listener,
// pending purchases support, and the billing choice params.
val billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases()
    .enableBillingProgram(params)
    .build()

// Establish a connection to Google Play
val billingResult = suspendCancellableCoroutine<BillingResult> { continuation ->
    billingClient.startConnection(object : BillingClientStateListener {
        // Called when the connection setup process completes.
        override fun onBillingSetupFinished(billingResult: BillingResult) {
            // Resume the coroutine and pass back the BillingResult to the caller.
            continuation.resume(billingResult)
        }

        // Called if the connection to the Play Store service is dropped.
        // This prevents the await or suspension point from hanging indefinitely.
        override fun onBillingServiceDisconnected() {
            continuation.resume(
                BillingResult.newBuilder()
                    .setResponseCode(BillingClient.BillingResponseCode.SERVICE_DISCONNECTED)
                    .setDebugMessage("Billing service disconnected during connection setup")
                    .build()
            )
        }
    })
}

Java


EnableBillingProgramParams params = EnableBillingProgramParams.newBuilder()
        .setBillingProgram(BillingProgram.BILLING_CHOICE)
        .build();

BillingClient billingClient = BillingClient.newBuilder(context)
        .setListener(purchasesUpdatedListener)
        .enablePendingPurchases()
        .enableBillingProgram(params)
        .build();

验证以下各项的可用性：

Google 呈现的结算方式选择界面
外部网页链接

调用 isBillingProgramAvailableAsync 检查计划是否可用，然后调用 queryProductDetailsAsync 显示可用的商品。例如：

Kotlin


// Check the availability of the billing choice program asynchronously using a coroutine
val (billingResult, billingProgramAvailabilityDetails) =
    billingClient.isBillingProgramAvailable(BillingProgram.BILLING_CHOICE)

// Ensure the response code is OK
if (billingResult.responseCode == BillingResponseCode.OK) {
    // Retrieve the billing choice availability details
    val billingChoiceAvailabilityDetails =
        billingProgramAvailabilityDetails.billingChoiceAvailabilityDetails

    // Check if billing choice details are available, choice screen is developer-rendered,
    // and external transaction links are supported.
    if (billingChoiceAvailabilityDetails != null &&
        billingChoiceAvailabilityDetails.choiceScreenType == ChoiceScreenType.DEVELOPER_RENDERED &&
        billingChoiceAvailabilityDetails.isExternalLinkAvailable
    ) {
        // Billing choice is available and external transaction links are supported.
        // Query products and proceed.
    } else {
        // Fallback to other available programs.
    }
} else {
    // Fallback to other available programs.
}

Java


// ...

billingClient.isBillingProgramAvailableAsync(
    BillingProgram.BILLING_CHOICE,
    (billingResult, billingProgramAvailabilityDetails) -> {
        if (billingResult.getResponseCode() == BillingResponseCode.OK) {
            BillingChoiceAvailabilityDetails billingChoiceAvailabilityDetails =
                billingProgramAvailabilityDetails.getBillingChoiceAvailabilityDetails();
            if (billingChoiceAvailabilityDetails != null &&
                billingChoiceAvailabilityDetails.getChoiceScreenType() == ChoiceScreenType.DEVELOPER_RENDERED &&
                billingChoiceAvailabilityDetails.isExternalLinkAvailable()) {
                // Billing choice is available and external transaction links are supported. Query products and proceed.
            } else {
                // Fallback to other available programs.
            }
        } else {
            // Fallback to other available programs.
        }
    }
);

调用 getBillingChoiceInfoAsync 方法以获取 Play 结算服务横幅和会员信息。

Kotlin


// 1. Create the params required for the request
val params = GetBillingChoiceInfoParams.newBuilder()
    .setBillingProgram(BillingClient.BillingProgram.BILLING_CHOICE)
    .setPlayBillingChoiceImageLayout(GetBillingChoiceInfoParams.ImageLayout.RECTANGULAR_FOUR_BY_ONE)
    .build()

// 2. Call the suspend method on your billingClient instance
val (billingResult, playBillingChoiceInfo) = billingClient.getBillingChoiceInfo(params)

if (billingResult.responseCode == BillingResponseCode.OK && playBillingChoiceInfo != null) {
    // Access the URL of the image associated with the Play Billing Choice
    val imageUrl = playBillingChoiceInfo.playBillingChoiceImageUrl

    // Access the Play Loyalty string information, if available
    val loyaltyInfo = playBillingChoiceInfo.playBillingLoyaltyInfo

    // Populate your developer-rendered UI elements
    playBillingLoyaltyTextView.text = loyaltyInfo
    loadImage(imageUrl, playBillingImageView)
} else {
    // Handle error scenarios
}

Java


// 1. Create the params required for the request
GetBillingChoiceInfoParams params = GetBillingChoiceInfoParams.newBuilder()
    .setBillingProgram(BillingClient.BillingProgram.BILLING_CHOICE)
    .setPlayBillingChoiceImageLayout(GetBillingChoiceInfoParams.ImageLayout.RECTANGULAR_FOUR_BY_ONE)
    .build();
// 2. Call the method asynchronously on your billingClient instance
billingClient.getBillingChoiceInfoAsync(params, (billingResult, playBillingChoiceInfo) -> {
    if (billingResult.getResponseCode() == BillingResponseCode.OK && playBillingChoiceInfo != null) {
      // Access the URL of the image associated with the Play Billing Choice
        String imageUrl = playBillingChoiceInfo.getPlayBillingChoiceImageUrl();
        // Access the Play Loyalty string information, if available
        String loyaltyInfo = playBillingChoiceInfo.getPlayBillingLoyaltyInfo();

        // Populate your developer-rendered UI elements
        playBillingLoyaltyTextView.setText(loyaltyInfo);
          loadImage(imageUrl, playBillingImageView);
      } else {
          // Handle error scenarios
      }
});

当用户表示有意购买时，调用 createBillingProgramReportingDetailsAsync 以创建外部交易令牌。例如：

Kotlin


// Build the parameters for creating reporting details
val params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.BILLING_CHOICE)
        .setDeveloperBillingType(DeveloperBillingType.EXTERNAL_LINK)
        .build()

// Call the suspend function to create billing program reporting details
val (billingResult, billingProgramReportingDetails) =
    billingClient.createBillingProgramReportingDetails(params)

// Handle response failure cases
if (billingResult.responseCode != BillingResponseCode.OK) {
    // Handle failures such as retrying due to network errors.
    return
}

// Retrieve the external transaction token
val transactionToken =
    billingProgramReportingDetails?.externalTransactionToken

// Persist the external transaction token locally. Pass it to
// DeveloperBillingOptionParams when launchBillingFlow is called.
// It can also be used as part of your external website

Java


BillingProgramReportingDetailsParams params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.BILLING_CHOICE)
        .setDeveloperBillingType(DeveloperBillingType.EXTERNAL_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
            // DeveloperBillingOptionParams when launchBillingFlow is called.
            // It can also be used as part of your external website.
        }
    }
);

在用户点击“购买”时启动备选方案选择界面。

按如下方式处理用户对结算类型的选择：

如果用户选择 Play 结算服务，请按照标准 Play 结算服务指南调用 launchBillingFlow。结算结果会返回到第 1 步中注册的 PurchasesUpdatedListener。

家长控制功能会针对受监督的用户显示。

如果用户选择您的备选结算系统，请调用 launchExternalLink。例如：

Kotlin


// An activity reference from which the purchase flow will be launched.
val activity: Activity = ...

val params = LaunchExternalLinkParams.newBuilder()
    .setBillingProgram(BillingProgram.BILLING_CHOICE)
    // You can pass along the external transaction token from
    // BillingProgramReportingDetails as a URL parameter in the URI
    .setLinkUri(yourLinkUri)
    .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_DIGITAL_CONTENT_OFFER)
    .setLaunchMode(
        LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP
    )
    .build()

// Call launchExternalLink with a callback
billingClient.launchExternalLink(activity, params) { billingResult ->
    if (billingResult.responseCode == BillingResponseCode.OK) {
        // Proceed with the rest of the purchase flow. If the user
        // purchases an item, be sure to report the transaction to Google
        // Play.
    } else {
        // Handle failures such as retrying due to network errors.
    }
}

Java


// An activity reference from which the purchase flow will be launched.
Activity activity = ...;

LaunchExternalLinkParams params = LaunchExternalLinkParams.newBuilder()
    .setBillingProgram(BillingProgram.BILLING_CHOICE)
    // You can pass along the external transaction token from
    // BillingProgramReportingDetails as a URL parameter in the URI
    .setLinkUri(yourLinkUri)
    .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_DIGITAL_CONTENT_OFFER)
    .setLaunchMode(
        LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
    .setExternalTransactionToken(transactionToken)
    .build();

LaunchExternalLinkResponseListener listener =
    new LaunchExternalLinkResponseListener() {
      @Override
      public void onLaunchExternalLinkResponse(BillingResult billingResult) {
        if (billingResult.getResponseCode() == BillingResponseCode.OK) {
          // Proceed with the rest of the purchase flow. If the user
          // purchases an item, be sure to report the transaction to Google
          // Play.
        } else {
          // Handle failures such as retrying due to network errors.
        }
      }
    };

billingClient.launchExternalLink(activity, params, listener);

将第 4 步中的外部交易令牌传递给 LaunchExternalLinkParams。如果返回 OK，则继续进行交易，并向 Google Play 报告交易。

家长控制功能会向受监督的用户显示。

更换订阅时的结算方式选择

对于订阅替换，不应显示用户选择界面，因为系统会保留原始购买交易的相关用户选择以用于升级和降级。

如果原始购买交易是通过 Google Play 结算服务处理的，您应使用标准 Google Play 结算服务订阅替换信息调用 launchBillingFlow。

不过，如果原始购买交易是通过备选结算系统处理的，则订阅替换的处理方式会因具体情况而略有不同。

方案 1A 中的订阅替换

请求升级或降级的用户应通过开发者的备选结算系统继续操作，无需用户再次选择。

为此，当用户请求升级或降级时，请调用 launchBillingFlow。在参数的 SubscriptionUpdateParams 对象中使用 setOriginalExternalTransactionId 提供原始购买交易的外部交易 ID。采用这种方式不会显示用户选择界面，因为系统会保留原始购买交易的相关用户选择以用于升级和降级。在此使用场景中，调用 launchBillingFlow 会为您可以从回调中检索的交易生成新的外部交易令牌。

Kotlin


// The external transaction ID from the current
// alternative billing subscription.
val externalTransactionId = //... ;

val developerBillingOptionParams = DeveloperBillingOptionParams.newBuilder()
    .setBillingProgram(BillingProgram.BILLING_CHOICE)
    .build()

val billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(
        listOf(
            BillingFlowParams.ProductDetailsParams.newBuilder()
                // Fetched using queryProductDetailsAsync.
                .setProductDetails(productDetailsNewPlan)
                // offerIdToken can be found in
                // ProductDetails=>SubscriptionOfferDetails.
                .setOfferToken(offerTokenNewPlan)
                .build()
        )
    )
    .setSubscriptionUpdateParams(
        BillingFlowParams.SubscriptionUpdateParams.newBuilder()
            .setOriginalExternalTransactionId(externalTransactionId)
            .build()
    )
    .enableDeveloperBillingOption(developerBillingOptionParams)
    .build()

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

// When the user selects the alternative billing flow,
// the DeveloperProvidedBillingListener is triggered.

Java


// The external transaction ID from the current
// alternative billing subscription.
String externalTransactionId = //... ;

DeveloperBillingOptionParams developerBillingOptionParams =
    DeveloperBillingOptionParams.newBuilder()
        .setBillingProgram(BillingProgram.BILLING_CHOICE)
        .build();

List<ProductDetailsParams> productDetailsParamsList = new ArrayList<>();
productDetailsParamsList.add(
    ProductDetailsParams.newBuilder()
        // Fetched using queryProductDetailsAsync.
        .setProductDetails(productDetailsNewPlan)
        // offerIdToken can be found in
        // ProductDetails=>SubscriptionOfferDetails
        .setOfferToken(offerTokenNewPlan)
        .build());

BillingFlowParams billingFlowParams =
    BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(productDetailsParamsList)
        .setSubscriptionUpdateParams(
            SubscriptionUpdateParams.newBuilder()
                .setOriginalExternalTransactionId(externalTransactionId)
                .build())
        .enableDeveloperBillingOption(developerBillingOptionParams)
        .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

// When the user selects the alternative billing flow,
// the DeveloperProvidedBillingListener is triggered.

升级或降级完成后，您需要使用通过之前针对新订阅购买交易的调用所获得的外部交易令牌来报告新交易。

方案 1B 中的订阅替换

在这种情况下，必须生成新的外部交易令牌。与正常购买交易的唯一区别在于，在这种情况下，系统会保留用户选择，您无需显示升级或降级选择界面。不过，您必须显示一次性信息对话框和家长确认信息。

如需查看集成代码示例，请参阅方案 1B：开发者呈现选择界面，并在应用内处理备选结算系统中的第 4 步。

升级或降级完成后，您需要使用通过之前针对新订阅购买交易的调用所获得的外部交易令牌来报告新交易。

方案 2A 中的订阅替换

对于最初在用户选择后通过开发者的网站或付款应用购买的订阅，请求升级或降级的用户应通过开发者的网站或付款应用继续操作，无需用户再次选择。

为此，当用户请求升级或降级时，请调用 launchBillingFlow。请使用 setOriginalExternalTransactionId 提供原始购买交易的外部交易 ID，而不是在 SubscriptionUpdateParams 对象下指定其他参数。在此调用中，还必须提供 DeveloperBillingOptionParams。采用这种方式不会显示用户选择界面，因为系统会保留原始购买交易的相关用户选择以用于升级和降级。例如：

Kotlin


val externalTransactionId = //... ;

// 1. Construct DeveloperBillingOptionParams indicating the billing program
val developerBillingOptionParams = DeveloperBillingOptionParams.newBuilder()
    .setBillingProgram(BillingClient.BillingProgram.BILLING_CHOICE)
    .build()

// 2. Build BillingFlowParams combining DeveloperBillingOptionParams and SubscriptionUpdateParams
val billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(
        listOf(
            BillingFlowParams.ProductDetailsParams.newBuilder()
                // Fetched using queryProductDetailsAsync.
                .setProductDetails(productDetailsNewPlan)
                // offerIdToken can be found in ProductDetails=>SubscriptionOfferDetails.
                .setOfferToken(offerTokenNewPlan)
                .build()
        )
    )
    .setSubscriptionUpdateParams(
        SubscriptionUpdateParams.newBuilder()
            .setOriginalExternalTransactionId(externalTransactionId)
            .build()
    )
    .enableDeveloperBillingOption(developerBillingOptionParams)
    .build()

Java


String externalTransactionId = //... ;

// 1. Construct DeveloperBillingOptionParams indicating the billing program
DeveloperBillingOptionParams developerBillingOptionParams =
    DeveloperBillingOptionParams.newBuilder()
        .setBillingProgram(BillingClient.BillingProgram.BILLING_CHOICE)
        .build();

// 2. Add ProductDetailsParams
List productDetailsParamsList = new ArrayList<>();
productDetailsParamsList.add(
    ProductDetailsParams.newBuilder()
        // Fetched using queryProductDetailsAsync.
        .setProductDetails(productDetailsNewPlan)
        // offerIdToken can be found in ProductDetails=>SubscriptionOfferDetails
        .setOfferToken(offerTokenNewPlan)
        .build());

// 3. Build BillingFlowParams combining DeveloperBillingOptionParams and SubscriptionUpdateParams
BillingFlowParams billingFlowParams =
    BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(productDetailsParamsList)
        .setSubscriptionUpdateParams(
            SubscriptionUpdateParams.newBuilder()
                .setOriginalExternalTransactionId(externalTransactionId)
                .build())
        .enableDeveloperBillingOption(developerBillingOptionParams)
        .build();

您还必须生成新的外部交易令牌。例如：

Kotlin


val params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.BILLING_CHOICE)
        .setDeveloperBillingType(DeveloperBillingType.EXTERNAL_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 using DeveloperBillingOptionParams when
            // launchBillingFlow is called.
        }
    }
)

Java


BillingProgramReportingDetailsParams params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.BILLING_CHOICE)
        .setDeveloperBillingType(DeveloperBillingType.EXTERNAL_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 using DeveloperBillingOptionParams when
        // launchBillingFlow is called.
      }
    });

生成新令牌后，您必须调用 launchBillingFlow 方法来启动购买流程。

升级或降级完成后，您需要使用通过之前针对新订阅购买交易的调用所获得的外部交易令牌来报告新交易。

场景 2B 中的订阅替换

在此场景中处理订阅替换的步骤与场景 2A 中的订阅替换中所述的步骤类似。唯一的区别在于，在生成交易令牌后，您必须调用 launchExternalLink 来显示外部链接免责声明对话框，而不是调用 launchBillingFlow 方法。在这种情况下，系统会保留用户选择，您无需显示升级或降级选择界面。

如需查看集成代码示例，请参阅方案 2B：开发者呈现选择界面，并在应用内处理备选结算系统中的第 6 步。

升级或降级完成后，您需要使用通过之前针对新订阅购买交易的调用所获得的外部交易令牌来报告新交易。

应用内集成指南（适用于结算方式选择） 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

与 PBL 集成

PBL 集成方案

处理场景 1A

Kotlin

Java

Kotlin

Java

Kotlin

Java

处理方案 1B

Kotlin

Java

Kotlin

Java

Kotlin

Java

Kotlin

Java

处理场景 2A

Kotlin

Java

Kotlin

Java

Kotlin

Java

Kotlin

Java

处理场景 2B

Kotlin

Java

Kotlin

Java

Kotlin

Java

Kotlin

Java

Kotlin

Java

更换订阅时的结算方式选择

方案 1A 中的订阅替换

Kotlin

Java

方案 1B 中的订阅替换

方案 2A 中的订阅替换

Kotlin

Java

Kotlin

Java

场景 2B 中的订阅替换

应用内集成指南（适用于结算方式选择）