Google Play 结算库版本说明

本主题包含 Google Play 结算库的版本说明。

Google Play 结算库 2.2.0 版和 Unity 支持 (2020-03-23)

Google Play 结算服务 2.2.0 版提供的功能可帮助开发者确保将购买交易归因于正确的用户。这些更改消除了基于开发者载荷构建自定义解决方案的需求。在此次更新中，开发者载荷功能已弃用并将在未来的版本中移除。如需了解包括推荐的替代方法在内的详情，请参阅开发者载荷。

适用于 Unity 的 Google Play 结算库 2

除了当前的 Java 和 Kotlin 版 Google Play 结算库 2 之外，我们还发布了一个适用于 Unity 的库版本。使用 Unity 应用内购买 API 的游戏开发者现在可以通过升级充分利用 Google Play 结算库 2 的所有功能，并在以后更轻松地升级到 Google Play 结算库的未来版本。

适用于 Unity 的结算库 2 作为 Google Game Package Registry for Unity 的一部分提供。如需了解详情，请参阅通过 Unity 使用 Google Play 结算服务。

变更摘要

• Java Google Play 结算库
  • 在 AcknowledgePurchaseParams 中，我们弃用了 setDeveloperPayload() 和 getDeveloperPayload() 方法。
  • 在 ConsumeParams 中，我们弃用了 setDeveloperPayload() 和 getDeveloperPayload() 方法。
  • 在 BillingFlowParams 中，我们将 setAccountId() 重命名为 setObfuscatedAccountId()，并记录了长度限制（64 个字符）以及禁止在此字段中使用个人身份信息 (PII) 的限制。setAccountId() 已标记为已弃用，并将在未来的库版本中移除。
  • 在 BillingFlowParams 中，我们添加了 setObfuscatedProfileId()，它的工作方式与 setObfuscatedAccountId() 类似。如需了解详情，请参阅开发者载荷更新和替代方法。
  • 在 Purchase 中，我们添加了 getAccountIdentifiers() 方法，以返回在 BillingFlowParams 中设置的经过混淆处理的帐号标识符。
  • 在 BillingClient 中，loadRewardedSku() 方法已在弃用奖励 SKU 的过程中被标记为已弃用。您可以访问 Play 管理中心帮助中心，详细了解弃用情况。

Google Play 结算库 2.1.0 版和 Kotlin 扩展程序 2.1.0 版 (2019-12-10)

Google Play 结算库 2.1.0 版和新版 Kotlin 扩展程序现已推出。Play 结算库 Kotlin 扩展程序提供惯用的 API 替代选项供 Kotlin 使用，具有更好的 null 安全和协程。如需查看代码示例，请参阅使用 Google Play 结算库。

此版本包含以下变更。

变更摘要

• 在 BillingFlowParams 中，我们弃用了 setOldSku(String oldSku) 并将其替换成 setOldSku(String oldSku, String purchaseToken)，这样在设备上的多个帐号拥有相同的 SKU 时，就可以消除歧义。

Google Play 结算库 2.0.3 版 (2019-08-05)

Google Play 结算库 2.0.3 版现已推出。

问题修复

• 修复了 querySkuDetailsAsync() 有时会发生代号为 DEVELOPER_ERROR 的错误而无法返回成功结果的问题。

Google Play 结算库 2.0.2 版 (2019-07-08)

Google Play 结算库 2.0.2 版现已推出。此版本包含对参考文档的更新，没有更改库功能。

Google Play 结算库 2.0.1 版 (2019-06-06)

Google Play 结算库 2.0.1 版现已推出。此版本包含以下变更。

问题修复

• 修复了在某些情况下系统将调试消息作为 null 返回的错误。
• 修复了潜在的内存泄漏问题。

Google Play 结算库 2.0 版 (2019-05-07)

Google Play 结算库 2.0 版现已推出。此版本包含以下变更。

必须在三天内确认购买交易

注意：本部分介绍了一项新要求，即必须确认所有购买交易。如果您已经通过 consumeAsync() 消耗所购商品，则如果您在三天内消耗所购商品，便无需做出任何进一步的更改，因为 consumeAsync() 会自动确认购买交易。未能正确确认购买交易将导致相应购买交易被退款。

注意：此要求仅适用于使用 Google Play 结算库 2.0 版及更高版本的应用。如果您使用的是旧版 Google Play 结算库或 AIDL API，则此要求不适用。

Google Play 支持从您的应用内部（应用内）或您的应用外部（应用外）购买商品。为了确保无论用户在哪里购买您的商品，Google Play 都能提供一致的购买体验，您必须在授予用户权利后尽快确认通过 Google Play 结算库收到的所有购买交易。如果您在三天内未确认购买交易，则用户会自动收到退款，并且 Google Play 会撤消该购买交易。对于待处理的交易（2.0 版中的新功能），三天期限从购买交易变为 SUCCESS 状态时起算，而购买交易处于 PENDING 状态的时间将不算在内。

对于订阅，您必须确认包含新购买令牌的任何购买交易。这意味着，需要确认所有初始购买、计划变更和重新注册，但无需确认后续续订。要确定购买交易是否需要确认，您可以检查购买交易中的确认字段。

Purchase 对象现在包含 isAcknowledged() 方法，该方法可以指示购买交易是否已得到确认。此外，Google Play Developer API 也包含 Purchases.products 和 Purchases.subscriptions 的确认布尔值。在确认购买交易之前，请务必使用这些方法确定购买交易是否已得到确认。

您可以使用以下某种方法确认购买交易：

• 对于消耗型商品，请使用客户端 API 中的 consumeAsync()。
• 对于非消耗型商品，请使用客户端 API 中的 acknowledgePurchase()。
• 还可以使用服务器 API 中新增的 acknowledge() 方法。

已移除 BillingFlowParams.setSku()

此版本已移除之前弃用的 BillingFlowParams#setSku() 方法。现在，在购买流程中渲染商品之前，您必须先调用 BillingClient.querySkuDetailsAsync()，将生成的 SkuDetails 对象传递给 BillingFlowParams.Builder.setSkuDetails()。

注意：建议不要缓存用户会话之间的 SkuDetails，因为 SkuDetails 对象仅在一段有限的时间内有效，限定的时间过后，您就必须调用 querySkuDetailsAsync() 再次刷新这些对象。

如需查看代码示例，请参阅使用 Google Play 结算库。

支持开发者有效负载

Google Play 结算库 2.0 版添加了对开发者有效负载（即，可附加到购买交易的任意字符串）的支持。您可以将开发者有效负载参数附加到购买交易，但只有在已确认购买交易或已消耗所购商品时才能附加。这与 AIDL 中的开发者有效负载不同，在 AIDL 中，可以在启动购买流程时指定有效负载。因为现在可以从您的应用外部发起购买交易，所以此变更可确保您始终有机会将有效负载添加到购买交易。

Purchase 对象现在包含一个 getDeveloperPayload() 方法，用于访问新库中的有效负载。

注意：有效负载分配后，便无法再进行修改。

一致的报价

注意：此功能目前正在测试中，不能保证其可以广泛使用。

当您提供折扣 SKU 时，Google Play 现在会返回 SKU 的原价，以便您向用户显示他们正在享受折扣。

SkuDetails 包含两种检索 SKU 原价的新方法：

• getOriginalPriceAmountMicros() - 返回折扣前未设置格式的 SKU 原价。
• getOriginalPrice() - 返回采用其他货币格式的原价。

待处理的交易

在 Google Play 结算库 2.0 版中，您必须支持在授予权利之前需要执行其他操作的购买交易。例如，用户可能会选择使用现金在实体店购买您的应用内商品。这意味着，交易在您的应用外部完成。在这种情况下，只有在用户完成交易后，您才能授予权利。

要启用“待处理的购买交易”功能，请在初始化应用期间调用 enablePendingPurchases()。

使用 Purchase.getPurchaseState() 方法确定购买交易的状态是 PURCHASED 还是 PENDING。请注意，只有在状态为 PURCHASED 时，您才能授予权利。您应通过执行以下操作来检查 Purchase 的状态更新：

1. 在启动应用时，调用 BillingClient.queryPurchases() 来检索与用户关联的非消耗型商品的列表。
2. 对每个返回的 Purchase 对象调用 Purchase.getPurchaseState()。
3. 实现 onPurchasesUpdated() 方法来响应对 Purchase 对象进行的更改。

此外，Google Play Developer API 还包含 Purchases.products 的 PENDING 状态。订阅不支持待处理的交易。

此版本还引入了一个新的实时开发者通知类型，即 OneTimeProductNotification。此通知类型包含一个消息，其值为 ONE_TIME_PRODUCT_PURCHASED 或 ONE_TIME_PRODUCT_CANCELED。仅针对与延迟付款方式（例如现金）相关的购买交易发送此类通知。

在确认待处理的购买交易时，请确保只有在购买状态是 SUCCESS（而不是 PENDING）时才确认。

注意：待处理的交易可由许可测试人员进行测试。除了两张测试信用卡之外，许可测试人员还可以使用两种新的测试付款方式，以测试在几分钟后自动完成或取消的延迟付款方式。在测试您的应用时，您应验证您的应用是否不会在用户使用这两种新付款方式中的任意一种购买后立即授予权利或确认购买交易。使用自动完成的新测试付款方式购买时，您应验证您的应用是否会在购买完成后授予权利并确认购买交易。

API 变更

Google Play 结算库 2.0 版包含多项 API 变更，以支持新特性并澄清现有功能。

consumeAsync

consumeAsync() 现在采用 ConsumeParams 对象，而非 purchaseToken。ConsumeParams 包含 purchaseToken 以及可选的开发者有效负载。

先前版本的 consumeAsync() 已从此版本中移除。

queryPurchaseHistoryAsync

为了尽量避免混淆，queryPurchaseHistoryAsync() 现在会返回 PurchaseHistoryRecord 对象，而不是 Purchase 对象。PurchaseHistoryRecord 对象与 Purchase 对象相同，只不过它仅反映由 queryPurchaseHistoryAsync() 返回的值，并且不包含 autoRenewing、orderId 和 packageName 字段。请注意，返回的数据没有任何变化 - queryPurchaseHistoryAsync() 返回的数据与以前相同。

BillingResult 返回值

先前返回一个 BillingResponse 整数值的 API 现在会返回一个 BillingResult 对象。BillingResult 包含 BillingResponse 整数以及可用于诊断错误的调试字符串。该调试字符串使用 en-US 语言环境，不会向最终用户显示。

问题修复

• SkuDetails.getIntroductoryPriceAmountMicros() 现在返回的是 long，而不是 String。

Google Play 结算库 1.2.2 版 (2019-03-07)

Google Play 结算库 1.2.2 版现已推出。此版本包含以下变更。

问题修复

• 修复了 v1.2.1 中引入的线程问题。后台调用不再阻止主线程。

其他变更

• 虽然仍建议使用主线程，但您现在可以从后台线程实例化 Google Play 结算库。
• 实例化已完全迁移到后台线程，以降低导致 ANR 的几率。

Play 结算库 1.2.1 版 (2019-03-04)

Google Play 结算库 1.2.1 版现已推出。此版本包含以下变更。

主要变更

• 添加了对奖励产品的支持。 如需详细了解获利途径，请参阅添加奖励产品专用功能。

其他变更

• 为 PurchasesResult 和 SkuDetailsResult 添加了公共构造函数，以使测试变得更容易。
• SkuDetails 对象可以使用新方法 getOriginalJson()。
• 所有 AIDL 服务调用现在都由后台线程处理。

问题修复

• Null 回调监听器不再传递到公共 API 中。

Google Play 结算库 1.2 版 (2018-10-18)

Google Play 结算库 1.2 版现已推出。此版本包含以下变更。

变更摘要

• Google Play 结算库现在依据 Android 软件开发工具包许可协议授权。
• 添加了 launchPriceChangeConfirmationFlow API，用于提示用户检查对订阅价格的待定更改。
• 在升级或降级用户的订阅时，添加了对新的按比例计费模式 DEFERRED 的支持。
• 在 BillingFlowParams 类中，将 setSku() 替换成了 setSkuDetails()。
• 修复了一些小问题并优化了代码。

价格变动确认

您现在可以在 Google Play 管理中心内更改订阅的价格，并在用户进入您的应用时提示他们查看并接受新价格。

要使用此 API，请使用订阅产品的 skuDetails 创建 PriceChangeFlowParams 对象，然后调用 launchPriceChangeConfirmationFlow()。当价格变动确认流程完成时，实现 PriceChangeConfirmationListener 来处理结果，如以下代码段所示：

Kotlin

val priceChangeFlowParams = PriceChangeFlowParams.newBuilder()
    .setSkuDetails(skuDetailsOfThePriceChangedSubscription)
    .build()

billingClient.launchPriceChangeConfirmationFlow(activity,
        priceChangeFlowParams,
        object : PriceChangeConfirmationListener() {
            override fun onPriceChangeConfirmationResult(responseCode: Int) {
                // Handle the result.
            }
        })

Java

PriceChangeFlowParams priceChangeFlowParams =
        PriceChangeFlowParams.newBuilder()
    .setSkuDetails(skuDetailsOfThePriceChangedSubscription)
    .build();

billingClient.launchPriceChangeConfirmationFlow(activity,
        priceChangeFlowParams,
        new PriceChangeConfirmationListener() {
            @Override
            public void onPriceChangeConfirmationResult(int responseCode) {
                // Handle the result.
            }
        });

价格变动确认流程会显示一个包含新定价信息的对话框，要求用户接受新价格。此流程会返回 BillingClient.BillingResponse 类型的响应代码。

新的按比例计费模式

当升级或降级用户的订阅时，您可以使用新的按比例计费模式 DEFERRED。此模式会在下次续订时更新用户的订阅。要详细了解如何设置此按比例计费模式，请参阅设置按比例计费模式。

用于设置 SKU 详情的新方法

在 BillingFlowParams 类中，setSku() 方法已被弃用。 此变更有助于优化 Google Play 结算服务流程。

在您的应用内购买结算客户端中构造新的 BillingFlowParams 实例时，我们建议您直接使用 setSkuDetails() 来处理 JSON 对象，如以下代码段所示。

在 BillingFlowParams Builder 类中，已弃用 setSku() 方法。请改用 setSkuDetails() 方法，如以下代码段所示。传入 setSkuDetails() 对象的对象来自 querySkuDetailsAsync() 方法。

Kotlin

private lateinit var mBillingClient: BillingClient
private val mSkuDetailsMap = HashMap<String, SkuDetails>()

private fun querySkuDetails() {
    val skuDetailsParamsBuilder = SkuDetailsParams.newBuilder()
    mBillingClient.querySkuDetailsAsync(skuDetailsParamsBuilder.build()
    ) { responseCode, skuDetailsList ->
        if (responseCode == 0) {
            for (skuDetails in skuDetailsList) {
                mSkuDetailsMap[skuDetails.sku] = skuDetails
            }
        }
    }
}

private fun startPurchase(skuId: String) {
    val billingFlowParams = BillingFlowParams.newBuilder()
    .setSkuDetails(mSkuDetailsMap[skuId])
    .build()
}

Java

private BillingClient mBillingClient;
private Map<String, SkuDetails> mSkuDetailsMap = new HashMap<>();

private void querySkuDetails() {
    SkuDetailsParams.Builder skuDetailsParamsBuilder
            = SkuDetailsParams.newBuilder();
    mBillingClient.querySkuDetailsAsync(skuDetailsParamsBuilder.build(),
            new SkuDetailsResponseListener() {
                @Override
                public void onSkuDetailsResponse(int responseCode,
                        List<SkuDetails> skuDetailsList) {
                    if (responseCode == 0) {
                        for (SkuDetails skuDetails : skuDetailsList) {
                            mSkuDetailsMap.put(skuDetails.getSku(), skuDetails);
                        }
                    }
                }
            });
}

private void startPurchase(String skuId) {
    BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder()
            .setSkuDetails(mSkuDetailsMap.get(skuId))
            .build();
}

Play 结算库 1.1 版 (2018-05-07)

Google Play 结算库 1.1 版现已推出。此版本包含以下变更。

变更摘要

• 现在，在升级或降级现有订阅时，可以在 BillingFlowParams 中指定按比例计费模式。
• BillingFlowParams 不再支持 replaceSkusProration 布尔标记，请改用 replaceSkusProrationMode。
• launchBillingFlow() 现在会对失败响应触发回调。

行为变更

Google Play 结算库 1.1 版包含以下行为变更。

开发者可以在 BillingFlowParams 类中设置 replaceSkusProrationMode

在升级或降级用户的订阅时，ProrationMode 会提供有关按比例计费类型的更多详情。

Kotlin

BillingFlowParams.newBuilder()
    .setSku(skuId)
    .setType(billingType)
    .setOldSku(oldSku)
    .setReplaceSkusProrationMode(replaceSkusProrationMode)
    .build()

Java

BillingFlowParams.newBuilder()
    .setSku(skuId)
    .setType(billingType)
    .setOldSku(oldSku)
    .setReplaceSkusProrationMode(replaceSkusProrationMode)
    .build();

目前，Google Play 支持以下按比例计费模式：

IMMEDIATE_WITH_TIME_PRORATION	替换会立即生效，并且系统会按比例计算新的有效期，同时向用户返还余额或收取相关费用。这是当前的默认行为。
IMMEDIATE_AND_CHARGE_PRORATED_PRICE	替换会立即生效，结算周期保持不变。用户需要补足剩余订阅期的差价。 注意：此选项仅适用于订阅升级。
IMMEDIATE_WITHOUT_PRORATION	替换会立即生效，并且会在下个续订时间点按新价格收费。结算周期保持不变。

BillingFlowParams 类不再支持 replaceSkusProration

开发者过去可以设置一个布尔标记来针对订阅升级请求收取按比例计算的金额。鉴于我们现已支持 ProrationMode，它包含更详细的按比例计费说明，因此不再支持此布尔标记。

launchBillingFlow() 现在会对失败的响应触发回调

结算库一律会触发 PurhcasesUpdatedListener 回调并异步返回 BillingResponse，并且 BillingResponse 的同步返回值也会被保留。

问题修复

• 当服务断开时，采用异步方法尽早正确退出。
• Builder 参数对象不会再改变已编译的对象。
• 问题 68087141：launchBillingFlow() 现在会对失败的响应触发回调。

Google Play 结算库 1.0 版（2017-09-19，公告）

Google Play 结算库 1.0 版现已推出。此版本包含以下变更。

重要变更

• 在库的清单内嵌入了结算权限，因此不再需要在 Android 清单内添加 com.android.vending.BILLING 权限。
• 向 BillingClient.Builder 类中添加了新的编译程序。
• 为 SkuDetailsParams 类（用于 SKU 查询方法）引入了编译程序模式。
• 为了保持一致（相同的返回参数名称和顺序），更新了几个 API 方法。

行为变更

Google Play 结算库 1.0 版包含以下行为变更。

BillingClient.Builder 类

BillingClient.Builder 现在通过 newBuilder 模式初始化：

Kotlin

billingClient = BillingClient.newBuilder(context).setListener(this).build()

Java

billingClient = BillingClient.newBuilder(context).setListener(this).build();

现在使用 BillingFlowParams 类调用 launchBillingFlow 方法

为购买交易或订阅启动结算流程时，launchBillingFlow() 方法会收到使用请求专用参数初始化的 BillingFlowParams 实例：

Kotlin

BillingFlowParams.newBuilder().setSku(skuId)
        .setType(billingType)
        .setOldSku(oldSku)
        .build()

// Then, use the BillingFlowParams to start the purchase flow
val responseCode = billingClient.launchBillingFlow(builder.build())

Java

BillingFlowParams.newBuilder().setSku(skuId)
                              .setType(billingType)
                              .setOldSku(oldSku)
                              .build();

// Then, use the BillingFlowParams to start the purchase flow
int responseCode = billingClient.launchBillingFlow(builder.build());

查询上架商品的新方式

queryPurchaseHistoryAsync() 和 querySkuDetailsAsync() 方法的参数已封装到编译程序模式中：

Kotlin

val params = SkuDetailsParams.newBuilder()
params.setSkusList(skuList)
        .setType(itemType)
billingClient.querySkuDetailsAsync(params.build(), object : SkuDetailsResponseListener() {
    ...
})

Java

SkuDetailsParams.Builder params = SkuDetailsParams.newBuilder();
params.setSkusList(skuList)
        .setType(itemType);
billingClient.querySkuDetailsAsync(params.build(), new SkuDetailsResponseListener() {...})

现在，为了方便您查看和在我们的 API 之间保持一致，结果会以结果代码和 SkuDetails 对象列表（而不是先前的封装容器类）的形式返回：

Kotlin

fun onSkuDetailsResponse(@BillingResponse responseCode: Int, skuDetailsList: List<SkuDetails>)

Java

public void onSkuDetailsResponse(@BillingResponse int responseCode, List<SkuDetails> skuDetailsList)

已更改 onConsumeResponse() 方法的参数顺序

为了在我们的 API 之间保持一致，已更改 ConsumeResponseListener 接口中的 onConsumeResponse 的参数顺序：

Kotlin

fun onConsumeResponse(@BillingResponse responseCode: Int, outToken: String)

Java

public void onConsumeResponse(@BillingResponse int responseCode, String outToken)

PurchaseResult 对象已解除封装

为了在我们的 API 之间保持一致，PurchaseResult 已解除封装：

Kotlin

fun onPurchaseHistoryResponse(@BillingResponse responseCode: Int, purchasesList: List<Purchase>)

Java

void onPurchaseHistoryResponse(@BillingResponse int responseCode, List<Purchase> purchasesList)

问题修复

• PURCHASES_UPDATED 软件包中没有响应代码
• 修复了设备旋转期间出现的 ProxyBillingActivity 和 PurchasesUpdatedListener 问题

开发者预览版 1（2017-06-12，公告）

发布了开发者预览版，旨在简化结算方面的开发过程，让开发者能够集中精力实现 Android 应用专用逻辑，如应用架构和导航结构。

该库包含一些方便使用的类和功能，供您在将 Android 应用与 Google Play Billing API 集成时使用。此外，该库还在 Android 接口定义语言 (AIDL) 服务之上提供了一个抽象层，让开发者可以更轻松地定义应用与 Google Play Billing API 之间的接口。