Google Play 结算服务 AIDL 参考

警告：AIDL 现已弃用并将在未来的版本中移除。如需为 Google Play 实现结算功能，请使用 Google Play 结算库。

本文档提供了使用 Google Play 结算服务 AIDL 的技术参考信息。

服务器响应代码

下表列出了从 Google Play 发送到您应用的所有服务器响应代码。Google Play 将在响应 Bundle 中以映射到 RESPONSE_CODE 键的整数形式同步发送响应代码。您的应用必须处理所有这些响应代码。

按季订阅已自 2019 年 6 月 15 日起被弃用。现在，对于所有新的按季订阅购买，Google Play 会返回 BILLING_RESPONSE_RESULT_DEVELOPER_ERROR。

表 1. Google Play 结算服务 AIDL 调用的响应代码汇总。

响应代码	值	说明
`BILLING_RESPONSE_RESULT_OK`	0	成功
`BILLING_RESPONSE_RESULT_USER_CANCELED`	1	用户按上一步或取消对话框
`BILLING_RESPONSE_RESULT_SERVICE_UNAVAILABLE`	2	网络连接断开
`BILLING_RESPONSE_RESULT_BILLING_UNAVAILABLE`	3	所请求的类型不支持 Google Play 结算服务 AIDL 版本
`BILLING_RESPONSE_RESULT_ITEM_UNAVAILABLE`	4	请求的商品已不再出售。
`BILLING_RESPONSE_RESULT_DEVELOPER_ERROR`	5	提供给 API 的参数无效。此错误也可能说明应用未针对结算服务正确签名或设置，或者在其清单中缺少必要的权限。
`BILLING_RESPONSE_RESULT_ERROR`	6	API 操作期间出现严重错误
`BILLING_RESPONSE_RESULT_ITEM_ALREADY_OWNED`	7	未能购买，因为已经拥有此商品
`BILLING_RESPONSE_RESULT_ITEM_NOT_OWNED`	8	未能消费，因为尚未拥有此商品

Google Play 结算服务 AIDL 参考 - 支持

本节介绍了几种方法，可用于获取您的应用支持的结算服务类型相关信息。

isBillingSupported() 方法

该方法可指示：

您的应用是否支持给定的 AIDL 版本。
Google Play 是否支持在用户所在国家/地区进行结算。
您的应用软件包中是否已启用 Google Play 结算系统。
您的应用是否可以使用给定类型的商品进行结算。

表 2. isBillingSupported() 参数。

键	类型	说明
`apiVersion`	`int`	您的应用正在使用的 Google Play 结算服务 AIDL 的版本号。
`packageName`	`String`	调用此方法的应用的软件包名称。
`type`	`String`	对于应用内商品，该值必须为 `inapp`；对于订阅，该值必须为 `subs`。

此方法在版本 3 及更高版本的 Google Play 结算服务 AIDL 中可用。

isBillingSupportedExtraParams() 方法

此方法类似于 isBillingSupported()，不同之处在于您可以传入第四个参数 Bundle（可包含额外的参数）。

表 3. isBillingSupportedExtraParams() 参数。

键	类型	说明
`apiVersion`	`int`	您的应用正在使用的 Google Play 结算服务 AIDL 的版本号。
`packageName`	`String`	调用此方法的应用的软件包名称。
`type`	`String`	对于应用内商品，该值必须为 `inapp`；对于订阅，该值必须为 `subs`。
`extraParams`	`Bundle`	一组额外的参数，用于进一步指定应用支持的 Google Play 结算系统的类型。此 Bundle 可以包含一个名为 `vr` 的可选键，此键具有布尔值。此标记指定该应用是否支持虚拟实境 (VR) 购买流程。

此方法在版本 7 及更高版本的 Google Play 结算服务 AIDL 中可用。

Google Play 结算服务 AIDL 参考 - 详细信息

Google Play 结算服务 AIDL 在 IInAppBillingService.aidl 文件中定义，此文件包含在版本 3 应用示例中。

getSkuDetails() 方法

使用 getSkuDetails() 方法可以获取相应商品 ID 列表的商品详情。

表 4. GetSkuDetails() 参数。

键	类型	说明
`apiVersion`	`int`	您的应用正在使用的 Google Play 结算服务 AIDL 的版本号。
`packageName`	`String`	调用此方法的应用的软件包名称。
`type`	`String`	应用内商品的类型（对于一次性购买，该值为“inapp”；对于订阅，该值为“subs”）。
`skusBundle`	`Bundle`	Bundle，其中包含具有 `ITEM_ID_LIST` 键的 SKU 的 `StringArrayList`。

如果 getSkuDetails() 方法调用成功，Google Play 会发送一个响应 Bundle。查询结果存储在映射到 DETAILS_LIST 键的字符串 ArrayList 内的 Bundle 中。详情列表中的每个字符串都以 JSON 格式包含一种商品的商品详情。表 5 汇总了含有商品详情的 JSON 字符串中的字段。

表 5. JSON 字段的说明，该字段包含从 getSkuDetails() 请求返回的商品详情。

键	说明
`productId`	商品 ID。
`type`	对于应用内商品，该值必须为 `inapp`；对于订阅，该值必须为 `subs`。
`price`	商品的格式化价格，包括货币符号。该价格不含税。
`price_amount_micros`	以微单位显示的价格，其中 1000000 个微单位等于 1 单位的货币。例如，如果 `price` 为 `"€7.99"`，则 `price_amount_micros` 为 `"7990000"`。此值表示特定币种已经过四舍五入的当地价格。
`price_currency_code`	`price` 的 ISO 4217 货币代码。例如，如果用英镑指定 `price`，则 `price_currency_code` 为 `"GBP"`。
`title`	商品的标题。
`description`	商品的说明。
`subscriptionPeriod`	订阅期，采用 ISO 8601 格式指定。例如，`P1W` 相当于一周，`P1M` 相当于一个月，`P3M` 相当于三个月，`P6M` 相当于六个月，`P1Y` 相当于一年。注意：仅针对订阅返回。
`freeTrialPeriod`	Google Play 管理中心中配置的试用期，采用 ISO 8601 格式指定。例如，`P7D` 相当于七天。要详细了解免费试用资格，请参阅应用内订阅。注意：仅针对配置了试用期的订阅返回。
`introductoryPrice`	订阅的格式化初次体验价，包括货币符号，例如 `€3.99`。此价格不含税。注意：仅针对配置了初次体验期的订阅返回。
`introductoryPriceAmountMicros`	以微单位显示的初次体验价。币种与 `price_currency_code` 相同。注意：仅针对配置了初次体验期的订阅返回。
`introductoryPricePeriod`	初次体验价的结算周期，采用 ISO 8601 格式指定。注意：仅针对配置了初次体验期的订阅返回。
`introductoryPriceCycles`	用户将享受初次体验价的订阅结算周期数，例如 3。注意：仅针对配置了初次体验期的订阅返回。

getBuyIntent() 方法

此方法会返回一个映射到 RESPONSE_CODE 键的响应代码整数，以及一个 PendingIntent 来启动映射到 BUY_INTENT 键的应用内商品的购买流程，如实现 Google Play 结算服务中所述。Google Play 在收到 PendingIntent 后，会发送一个包含该采购订单的数据的响应 Intent。表 6 汇总了响应 Intent 中返回的数据。

注意：我们建议您不要使用此方法，而应使用 getBuyIntentExtraParams()，因为后者提供了额外的功能。

表 6. 来自 Google Play 购买请求的响应数据。

键	说明
`RESPONSE_CODE`	如果购买成功，则值为 `0`；否则包含错误代码。
`INAPP_PURCHASE_DATA`	JSON 格式的字符串，其中包含有关采购订单的详细信息。有关 JSON 字段的说明，请参阅表 7。
`INAPP_DATA_SIGNATURE`	包含使用开发者私钥签署的购买数据签名的字符串。该数据签名使用 RSASSA-PKCS1-v1_5 模式。

表 7 介绍了采购订单响应数据中返回的 JSON 字段。

表 7. INAPP_PURCHASE_DATA 的 JSON 字段说明。

字段	说明
`autoRenewing`	表明是否自动续订订阅。如果为 `true`，则表示订阅处于活动状态，并将在下一个结算日期自动续订。如果为 `false`，则表示用户已取消订阅。用户可以在下一个结算日期之前访问订阅内容，并且在该日期后将无法访问，除非他们重新启用自动续订（或者手动续订，如手动续订中所述）。如果您提供宽限期，只要宽限期尚未结束，对于所有订阅而言，此值都将保持为 `true`。下一次结算日期每天都会自动推延，直至宽限期结束或用户更改他们的付款方式。
`orderId`	交易的唯一订单标识符。此标识符对应于 Google 付款订单 ID。
`packageName`	发起购买的应用软件包。
`productId`	商品的产品标识符。每件商品都有一个产品 ID，您必须在 Google Play 管理中心的应用产品列表中指定产品 ID。
`purchaseTime`	购买产品的时间，以从 Epoch 纪元日（1970 年 1 月 1 日）开始计算的毫秒数表示。
`purchaseState`	订单的购买状态。始终返回 `0`（已购买）。
`developerPayload`	开发者指定的字符串，其中包含关于订单的补充信息。当您发出 `getBuyIntent` 请求时，您可以为此字段指定一个值。
`purchaseToken`	用于对给定商品和用户对的购买交易进行唯一标识的令牌。

consumePurchase() 方法

消费与给定购买令牌相对应的购买。这将导致此商品从 getPurchases() 的所有后续响应中移除，并允许重新购买相同 SKU 的商品。

表 8. consumePurchase() 参数。

键	类型	说明
`apiVersion`	`int`	您的应用正在使用的 Google Play 结算服务 AIDL 的版本号。
`packageName`	`String`	调用此方法的应用的软件包名称。
`purchaseToken`	`String`	购买信息 JSON 中的令牌，用于标识要消费的购买。

消费成功时，此方法会返回 RESULT_OK(0)；失败时，也会返回相应的响应代码。

getBuyIntentToReplaceSkus() 方法

可以使用此方法升级或降级订阅购买。此方法类似于 getBuyIntent()，不同之处在于它会获取一个列表，其中只包含一个已购买的 SKU，该 SKU 将被替换为正在购买的 SKU。当用户完成购买后，Google Play 将换掉旧的 SKU，并按比例向用户返还未使用的订阅时间所对应的余额。Google Play 会将此余额结转到新订阅中，并且在此余额用完之前不会向用户收取新订阅的费用。

注意：我们建议您不要使用此方法，而应使用 getBuyIntentExtraParams()，因为后者提供了额外的功能。

此方法在 Google Play 结算服务 AIDL 版本 5 中添加。如要验证此方法是否已报告，请发送一个 isBillingSupported AIDL 请求。

注意：您只能针对订阅购买使用此方法。如果传递的 type 参数不是 "subs"，则此方法会返回 BILLING_RESPONSE_RESULT_DEVELOPER_ERROR。此外，传递的 SKU 可能不包含季度订阅的 SKU。

此方法会返回一个映射到 RESPONSE_CODE 键的响应代码整数，以及一个 PendingIntent 以启动映射到 BUY_INTENT 键的应用内订阅的购买流程。Google Play 在收到 PendingIntent 后，会发送一个包含该采购订单的数据的响应 Intent。表 9 汇总了响应 Intent 中返回的数据。

表 9. 来自 Google Play 结算服务 AIDL 版本 5 购买请求的响应数据。

键	说明
`RESPONSE_CODE`	如果购买成功，值为 `0`。如果购买失败，则包含错误代码。
`INAPP_PURCHASE_DATA`	JSON 格式的字符串，其中包含有关采购订单的详细信息。有关 JSON 字段的说明，请参阅表 6。
`INAPP_DATA_SIGNATURE`	包含开发者使用其私钥签署的购买数据签名的字符串。该数据签名使用 RSASSA-PKCS1-v1_5 模式。

getBuyIntentExtraParams() 方法

此方法会开启一个购买请求。此方法是 getBuyIntent() 方法的变体，并采用额外的 extraParams 参数。此参数是影响该方法操作的可选键和值的 Bundle（如表 10 所示）。

表 10. getBuyIntentExtraParams() 额外参数。

键	类型	说明
`skusToReplace`	`List<String>`	仅包含用户正在升级或降级的一个 SKU 的可选列表。如果购买是对现有订阅的升级或降级，则传递此字段。指定的 SKU 将被替换为用户正在购买的 SKU。Google Play 将在下一个结算周期开始时替换指定的 SKU。
`replaceSkusProration`	`boolean`	指定用户是否应该就升级或降级的 SKU 获得任何未使用的订阅时间的余额返还。如果将此字段设置为 true，Google Play 将换掉旧的 SKU 并按比例向用户返还未使用的订阅时间所对应的余额。Google Play 会将此余额结转到新订阅中，并且在此余额用完之前不会向用户收取新订阅的费用。如果将此字段设置为 false，则用户不会因未使用的订阅时间获得余额返还，并且下个订阅周期的开始日期不会改变。默认值为 true。如果您不传递 `skusToReplace`，则忽略。
`accountId`	`String`	可选的混淆字符串，与您应用中的用户帐号唯一关联。如果您传递此值，Google Play 可以使用它来检测不正常的活动，例如大量设备在短时间内使用同一帐号进行购买。此字段类似于 `developerId`，因为它表示单个用户，但请注意，如果您有多个应用，则同一用户可以为每个应用设置不同的 `accountId`，而 `developerId` 应该在所有应用中唯一标识单个用户。请勿在此字段中使用 Google Play 管理中心开发者 ID 或用户的 Google ID。另外，此字段不应以明文形式包含用户 ID。我们建议您使用单向哈希技术来根据用户 ID 生成一个字符串，并将此哈希字符串存储在此字段中。
`developerId`	`String`	可选的混淆字符串，与用户在您的所有应用中的帐号唯一关联。此字段类似于 `accountId`，因为它表示单个用户。但是对于同一用户，此字段应该在所有应用中相同，而 `accountId` 对于每个应用都可能是唯一的，即使对于同一用户也是如此。请勿在此字段中使用 Google Play 管理中心开发者 ID 或用户的 Google ID。另外，此字段不应以明文形式包含用户 ID。我们建议您使用单向哈希技术来根据用户 ID 生成一个字符串，并将此哈希字符串存储在此字段中。
`vr`	`boolean`	指定所提供的 intent 是否代表虚拟实境 (VR) 购买流程的开始。注意：为了让此额外参数对您的应用产生影响，您必须使用 Google Play 结算服务 AIDL 版本 7 或更新的 API。

此方法在版本 6 及更高版本的 Google Play 结算服务 AIDL 中可用。

getPurchases() 方法

此方法将返回当前归用户所有但未消费的商品，包括购买的商品和通过兑换促销代码获得的商品。表 11 列出了 Bundle 中返回的响应数据。

表 11. 来自 getPurchases 请求的响应数据。

键	说明
`RESPONSE_CODE`	如果请求成功，则值为 `0`；否则包含错误代码。
`INAPP_PURCHASE_ITEM_LIST`	`StringArrayList`，包含从此应用发起的购买交易的商品 ID 列表。
`INAPP_PURCHASE_DATA_LIST`	`StringArrayList`，包含从此应用发起的购买交易的详细信息。表 13 列出了此列表中每项内容存储的详细信息。
`INAPP_DATA_SIGNATURE_LIST`	`StringArrayList`，包含从此应用发起的购买交易的签名。
`INAPP_CONTINUATION_TOKEN`	一个字符串，其中包含用于检索用户拥有的下一组应用内商品的继续令牌。如果用户拥有的商品的数量非常庞大，则此字符串只能通过 Google Play 服务设置。当响应中存在继续令牌时，您必须对 `getPurchases` 发起另一个调用，并传入您接收到的继续令牌。随后的 `getPurchases` 调用会返回更多购买并可能会返回另一个继续令牌。

getPurchaseHistory() 方法

此方法返回用户对每个 SKU 所做的最近一次购买，即使该购买已过期、取消或消费。表 12 列出了 Bundle 中返回的响应数据：

表 12. 来自 getPurchaseHistory 请求的响应数据。

键	说明
`RESPONSE_CODE`	如果请求成功，则值为 `0`；否则包含错误代码。
`INAPP_PURCHASE_ITEM_LIST`	`StringArrayList`，包含从此应用发起的购买交易的商品 ID 列表。
`INAPP_PURCHASE_DATA_LIST`	`StringArrayList`，包含最近从此应用发起的购买交易的详细信息。表 6 列出了此列表中的每个 `INAPP_PURCHASE_DATA` 项目中存储的详细信息。
`INAPP_DATA_SIGNATURE_LIST`	`StringArrayList`，包含从此应用发起的购买交易的签名。
`INAPP_CONTINUATION_TOKEN`	一个字符串，其中包含用于检索用户拥有的下一组应用内商品的继续令牌。如果用户拥有的商品的数量非常庞大，则此字符串只能通过 Google Play 服务设置。当响应中存在继续令牌时，您必须对 `getPurchases` 发起另一个调用，并传入您接收到的继续令牌。随后的 `getPurchases` 调用会返回更多购买并可能会返回另一个继续令牌。

表 13. getPurchaseHistory() 返回的交易记录 JSON 字段的说明。

字段	说明
`productId`	商品的产品标识符。每件商品都有一个产品 ID，您必须在 Google Play 管理中心的应用产品列表中指定产品 ID。
`purchaseTime`	购买产品的时间，以从 Epoch 纪元日（1970 年 1 月 1 日）开始计算的毫秒数表示。
`developerPayload`	开发者指定的字符串，其中包含关于订单的补充信息。当您发出 `getBuyIntent` 请求时，您可以为此字段指定一个值。
`purchaseToken`	用于对给定商品和用户对的购买交易进行唯一标识的令牌。

注意：getPurchaseHistory() 方法的开销比 getPurchases() 高，因为它需要调用 Google Play 服务器。如果您确实不需要用户的交易记录，则应该使用 getPurchases()。

此方法在版本 6 及更高版本的 Google Play 结算服务 AIDL 中可用。