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

本指南介绍了如何在符合条件的应用中集成 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 建立连接。

测试备用结算

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

下一步

完成应用内集成后,您可以集成后端