应用内仅备用结算的集成指南

本指南介绍了如何在符合条件的应用中集成 API 以仅提供备用结算（即不含用户选择）。要了解有关这些计划的更多信息，包括资格要求和地理范围，请参阅关于备用结算。

Play 结算库设置

将Play 结算库依赖项添加到您的 Android 应用。要使用备用结算 API，您需要使用 6.1 或更高版本。

连接到 Google Play

集成过程中的第一步与Google Play 结算集成指南中描述的步骤相同，但在初始化 BillingClient 时有一些修改。

以下示例演示了通过这些修改初始化 BillingClient 的过程

Kotlin


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

Java

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

初始化 BillingClient 后，您需要按照集成指南中的说明与 Google Play 建立连接。

检查可用性

您的应用应通过调用 isAlternativeBillingOnlyAvailableAsync 来确认仅备用结算是否可用。

如果仅备用结算可用，此 API 将返回 BillingResponseCode.OK。有关您的应用应如何响应其他响应代码的详细信息，请参阅响应处理。

Kotlin


billingClient.isAlternativeBillingOnlyAvailableAsync(object:
    AlternativeBillingOnlyAvailabilityListener {
        override fun onAlternativeBillingOnlyAvailabilityResponse(
            billingResult: BillingResult) {
            if (billingResult.responseCode !=  BillingResponseCode.OK) {
                // Handle failures such as retrying due to network errors,
                // handling alternative billing only being unavailable, etc.
                return
            }

            // Alternative billing only is available. Continue with steps in
            // the guide.
        }
    });

Java


billingClient.isAlternativeBillingOnlyAvailable(
    new AlternativeBillingOnlyAvailabilityListener() {
        @Override
        public void onAlternativeBillingOnlyAvailabilityResponse(
            BillingResult billingResult) {
            if (billingResult.getResponseCode() != BillingResponseCode.OK) {
                 // Handle failures such as retrying due to network errors,
                 // handling alternative billing only being unavailable,
                 // etc.
                return;
            }

            // Alternative billing only is available. Continue with steps in
            // the guide.
        }
    });

面向用户的信息对话框

要仅与备用结算集成，您的合格应用必须显示一个信息屏幕，帮助用户了解结算将不由 Google Play 管理。每次开始备用结算流程之前，必须通过调用 showAlternativeBillingOnlyInformationDialog API 向用户显示信息屏幕。如果用户已经确认过对话框，使用此 API 通常不会导致对话框再次显示。在用户清除设备上的缓存等情况下，对话框可能会再次显示给用户。

Kotlin


// An activity reference from which the alternative billing only information
// dialog will be launched.
val activity : Activity = ...;

val listener : AlternativeBillingOnlyInformationDialogListener =
    AlternativeBillingOnlyInformationDialogListener { 
        override fun onAlternativeBillingOnlyInformationDialogResponse(
            billingResult: BillingResult) {
            // check billingResult
        }
}

val billingResult =
    billingClient.showAlternativeBillingOnlyInformationDialog(activity,
        listener)

Java


// An activity reference from which the alternative billing only information
// dialog will be launched.
Activity activity = ...;

AlternativeBillingOnlyInformationDialogListener listener =
    new AlternativeBillingOnlyInformationDialogListener() {
        @Override
        public void onAlternativeBillingOnlyInformationDialogResponse(
            BillingResult billingResult) {
                // check billingResult
            }
    };

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

如果此方法返回 BillingResponseCode.OK，则您的应用可以继续进行交易。对于 BillingResponseCode.USER_CANCELED 的情况，您的应用应再次调用 showAlternativeBillingOnlyInformationDialog 向用户显示对话框。对于其他响应代码，请参阅响应处理部分。

向 Google Play 报告交易

通过备用结算系统进行的所有交易必须在 24 小时内从您的后端调用 Google Play Developer API 报告给 Google Play，并提供通过以下 API 获得的 externalTransactionToken。对于每次一次性购买、每个新订阅以及现有订阅的任何升级/降级，都应生成一个新的 externalTransactionToken。要了解如何在获得 externalTransactionToken 后报告交易，请参阅后端集成指南。

Kotlin

billingClient.createAlternativeBillingOnlyReportingDetailsAsync(object:
    AlternativeBillingOnlyReportingDetailsListener {
        override fun onAlternativeBillingOnlyTokenResponse(
            billingResult: BillingResult,
            alternativeBillingOnlyReportingDetails:
                AlternativeBillingOnlyReportingDetails?) {
            if (billingResult.responseCode !=  BillingResponseCode.OK) {
                // Handle failures such as retrying due to network errors.
                return
            }

            val externalTransactionToken =
                alternativeBillingOnlyReportingDetails?
                    .externalTransactionToken

            // Send transaction token to backend and report to Google Play.
        }
    });

Java


billingClient.createAlternativeBillingOnlyReportingDetailsAsync(
    new AlternativeBillingOnlyReportingDetailsListener() {
        @Override
        public void onAlternativeBillingOnlyTokenResponse(
            BillingResult billingResult,
            @Nullable AlternativeBillingOnlyReportingDetails
                alternativeBillingOnlyReportingDetails) {
            if (billingResult.getResponseCode() != BillingResponseCode.OK) {
                // Handle failures such as retrying due to network errors.
                return;
            }

            String transactionToken =
                alternativeBillingOnlyReportingDetails
                .getExternalTransactionToken();

            // Send transaction token to backend and report to Google Play.
        }
    });

响应处理

上述方法 isAlternativeBillingOnlyAvailableAsync()、showAlternativeBillingOnlyInformationDialog() 和 createAlternativeBillingOnlyReportingDetailsAsync() 在发生错误时可能会返回非 BillingResponseCode.OK 的响应。建议的错误处理方式如下所述

  • ERROR：这是一个内部错误。不要继续进行交易。下次用户尝试购买时，再次调用 showAlternativeBillingOnlyInformationDialog() 显示信息对话框进行重试。
  • FEATURE_NOT_SUPPORTED：当前设备上的 Play 商店不支持备用结算 API。不要继续进行交易。
  • USER_CANCELED：不要继续进行交易。下次用户尝试购买时，再次调用 showAlternativeBillingOnlyInformationDialog() 显示信息对话框。
  • BILLING_UNAVAILABLE：该交易不符合仅备用结算的条件，因此不应在此计划下进行。这可能是因为用户不在该计划的适用国家/地区，或者您的帐号尚未成功注册该计划。如果是后一种情况，请在 Play 管理中心检查您的注册状态。
  • DEVELOPER_ERROR：请求出错。在继续之前，使用调试消息识别并纠正错误。
  • NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE：这些是应重试的临时错误。在 SERVICE_DISCONNECTED 的情况下，在重试之前重新与 Google Play 建立连接。

测试备用结算

应使用许可测试人员来测试您的备用结算集成。通过许可测试帐号发起的交易将不会向您收取费用。有关如何配置许可测试人员的更多信息，请参阅使用应用许可测试应用内结算功能。

下一步

完成应用内集成后，您可以集成后端。