警告:AIDL 现已弃用并将在未来的版本中移除。如需为 Google Play 实现结算功能,请使用 Google Play 结算库。
本文档提供了使用 Google Play 结算服务 AIDL 的技术参考信息。
服务器响应代码
下表列出了从 Google Play 发送到您应用的所有服务器响应代码。Google Play 将在响应 Bundle
中以映射到 RESPONSE_CODE
键的整数形式同步发送响应代码。您的应用必须处理所有这些响应代码。
表 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 可以包含一个名为 |
此方法在版本 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。如果您不传递 |
accountId
|
String
|
可选的混淆字符串,与您应用中的用户帐号唯一关联。如果您传递此值,Google Play 可以使用它来检测不正常的活动,例如大量设备在短时间内使用同一帐号进行购买。 此字段类似于 请勿在此字段中使用 Google Play 管理中心开发者 ID 或用户的 Google ID。 另外,此字段不应以明文形式包含用户 ID。 我们建议您使用单向哈希技术来根据用户 ID 生成一个字符串,并将此哈希字符串存储在此字段中。 |
developerId
|
String
|
可选的混淆字符串,与用户在您的所有应用中的帐号唯一关联。此字段类似于 请勿在此字段中使用 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 中可用。