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

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

Play 计费库设置

将 Play 计费库依赖项 添加到您的 Android 应用中。要使用替代计费 API，您需要使用 6.1 版或更高版本。

连接到 Google Play

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

• 您需要调用一个新方法来指示您的应用仅使用替代计费系统：enableAlternativeBillingOnly。

以下示例演示了使用这些修改初始化 BillingClient

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

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

初始化 BillingClient 后，您需要 建立与 Google Play 的连接，如集成指南中所述。

检查可用性

您的应用应通过调用 isAlternativeBillingOnlyAvailableAsync 来确认仅限替代计费可用。

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

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.
        }
    });

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 通常不会再次显示对话框。在某些情况下，例如用户清除设备缓存时，可能会再次向用户显示对话框。

// 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)

// 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 后报告交易，请参阅 后端集成指南。

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.
        }
    });

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 的连接。

测试替代计费

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

后续步骤

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