仅限替代计费的应用内集成指南

本指南介绍如何集成 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 开发者 API 向 Google Play 报告，并提供一个 externalTransactionToken，该令牌是使用下面描述的 API 获取的。对于每次一次性购买、每次新订阅以及对现有订阅的任何升级/降级，都应生成一个新的 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 的连接。

测试替代计费

应使用许可证测试人员来测试您的替代计费集成。对于由许可证测试人员帐户发起的交易，您将不会被开具发票。有关配置许可证测试人员的更多信息，请参阅 使用应用许可测试应用内结算。

后续步骤

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