仅适用于备选结算系统的应用内集成指南

注意： 我们即将停用仅限备选结算系统的结算方式的手动报告功能。如需了解有关迁移截止日期的更多详细信息，请点击此处。如需详细了解需要迁移哪些交易以及如何迁移，请参阅从手动报告迁移。

本指南介绍了如何集成相关 API，以便在符合条件的应用中提供仅限备选结算系统（即无需用户自选）的结算方式。如需详细了解相关计划（包括资格要求和地理范围），请参阅备选结算系统简介。

Play 结算库设置

向您的 Android 应用添加 Play 结算库依赖项。如需使用备选结算系统 API，您需要使用 6.1 或更高版本。

连接到 Google Play

注意：如果使用仅限备选结算系统的结算方式，您的应用无需提供 PurchasesUpdatedListener，该监听器用于监听通过 Google Play 结算系统进行的交易。

集成流程的最初步骤与 Google Play 结算服务集成指南中所述的一些步骤相同，在初始化您的 BillingClient 时需进行一些调整：

• 您需要调用新的方法，以表明您的应用仅使用备选结算系统：enableAlternativeBillingOnly。

以下示例演示了如何通过这些调整来初始化 BillingClient：

Kotlin

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

Java

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

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

检查可用性

注意：如需了解如何处理此 API 中的错误，请参阅“响应处理”部分中的说明。

您的应用应通过调用 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.
        }
    });

面向用户的信息对话框

注意：如需了解如何处理此 API 中的错误，请参阅“响应处理”部分中的说明。

注意：如果您仅通过备选结算系统 API 提供备选结算系统，则可以通过集成并使用客户端 API 来满足用户体验要求。您无需另行遵循临时用户体验指南。

如需集成仅限备选结算系统的结算方式，符合条件的应用必须显示一个信息界面，以帮助用户了解结算将不受 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 报告交易

注意：如需了解如何处理此 API 中的错误，请参阅“响应处理”部分中的说明。

通过备选结算系统进行的所有交易都必须在 24 小时内从后端调用 Google Play Developer API 并提供 externalTransactionToken（使用下文介绍的 API 获取），向 Google Play 报告相应交易。每笔一次性购买交易、每项新订阅以及对现有订阅的任何升级/降级都应生成新的 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：这是内部错误。继续通过备选结算系统处理交易。您无需向 Google 报告交易，包括受影响订阅的任何续订交易。
• FEATURE_NOT_SUPPORTED：当前设备上的 Play 商店不支持备选结算系统 API。继续通过备选结算系统处理交易。您无需向 Google 报告交易和受影响订阅的任何续订交易。
• USER_CANCELED：下次用户尝试进行购买时，您需要再次调用 showAlternativeBillingOnlyInformationDialog() 以向用户显示该信息对话框。
• BILLING_UNAVAILABLE：交易无法使用仅限备选结算系统的结算方式，因此不应按照此计划继续进行。这是因为用户不在符合此计划条件的国家/地区，或者您的账号未成功注册此计划。如果是后一种情况，请在 Play 管理中心内检查您的注册状态。
• DEVELOPER_ERROR：请求中存在错误。使用调试消息找出并更正错误，然后再继续交易。
• NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE：这些是暂时性错误，应该重试。如果发生 SERVICE_DISCONNECTED 错误，请重新与 Google Play 建立连接，然后再重试。

测试备选结算系统

应使用许可测试人员来测试您的备选结算系统集成。我们不会为许可测试人员帐号发起的交易开具账单。如需详细了解如何配置许可测试人员，请参阅使用应用许可来测试应用内购结算功能。

后续步骤

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