Android应用程序的内部付费机制（转）

转自：http://wiki.eoe.cn/page/In-app_Billing_Reference

:原文地址:http://docs.eoeandroid.com/guide/google/play/billing/billing_reference.html
:译者:十旋转45度
:更新时间：2012年9月13日

TOC
:Overview of In-app Billing | 内部付费机制概述 - Overview of In-app Billing
:Implementing In-app Billing | 内部付费机制的实现 - Implementing In-app Billing
:Security and Design | 设计与安全 - Security and Design
:Administering In-app Billing | 应用程序付费机制管理 - Administering In-app Billing
:Testing In-app Billing | 程序内付费机制测试 - In-app Billing Reference
下载应用样例

* 应用程序内部付费的服务器响应码*

下表列出了所有从Google Play发送到你的应用程序的服务器响应码。Google Play将这些响应码作为* response_code* 附加信息[extras] 异步发送。你的应用程序必须处理这些这些所有响应码。

• 表1* .Google Play返回的响应码汇总{| border="1"
  |- style="background:grey; color:white; width:75%"| 响应码| style"center"| 值| 描述|-
  | * RESULT_OK* | align="center"| 0| 表示该请求成功发送至服务器。若* CHECK_BILLING_SUPPORTED* 请求返回此响应代码，那么支持付费行为。|-| * RESULT_USER_CANCELED* | align="center"| 1| 表示用户在付款页面选中的是返回按钮而非购买物品。|-| * RESULT_SERVICE_UNAVAILABLE* | align="center"| 2| 表示网络连接中断。|-| * RESULT_BILLING_UNAVAILABLE* | align="center"| 3| 表示应用程序内部付费不可用，原因是指定的* API_VERSION* 不为Google Play应用识别，或用户是没有结算在应用程序内部付费的权限（如，用户所处地区禁止在应用程序内部付费行为）|-| * RESULT_ITEM_UNAVAILABLE* | align="center"| 4| 表示Google Play在应用程序的商品列表上找不到请求的物品。产生这种情况的原因可能是你的* REQUEST_PURCHASE* 请求种商品ID拼写错误，或者这个物品并未在应用程序的商品列表中发布。|-| * RESULT_DEVELOPER_ERROR * | align="center"|5| 表示应用程序试图创建一条应用程序内部付费请求，但应用程序没有在manifest中声明com.android.vending.BILLING的许可；也可表示应用程序签名不正确，或者你发送的请求不正确，如Bundle key丢失，或使用了无法识别的请求类型。|-| * RESULT_ERROR* | align="center"|6
  | 表示产生了意外的服务器错误。如，你尝试购买自己的物品而触发的错误，这不为Google Wallet允许。|}

* 应用程序内部付费服务的接口*

以下部分介绍Google Play的应用程序内部付费服务的接口。接口是在* IMarketBillingService.aidl* 文件中定义的，该文件可在应用程序内部付费示例中找到。

接口由一个请求方法* sendBillingRequest()* 构成。该方法只需一个Bundle参数。Bundle参数包括几个键-值对，在表2中列出：

• 表2_' 传给'_sendBillingRequest()* 请求的Bundle键的描述{| style1|- style="background:grey; color:white"| 键| style="width:40px" | 类型| style"center"| 可能的值| style"center"| 是否必需？| 描述|- | * BILLING_REQUEST* | * String*
  | '''CHECK_BILLING_SUPPORTED，
• REQUEST_PURCHASE* ，
• GET_PURCHASE_INFORMATION* ，
• CONFIRM_NOTIFICATIONS* ，或 * RESTORE_TRANSACTIONS* | align="center"|是| 使用* sendBillingRequest()* 创建的付费请求的类型。可能的值在本表后续部分会详细讨论。|-| * API_VERSION*
  | int| * “2”* [ 详细信息 ]* “1”* [ 详细信息 ]
  | align="center"|是| 您要使用的Google Play应用内部付费服务的版本，当前版本为2。|- | * PACKAGE_NAME*
  | * String* | 有效的包名称。 | align="center"|是
  | 发出请求的应用程序名称。|-| * ITEM_ID*
  | * String* | 任何有效的商品标识。
  | 对* REQUEST_PURCHASE* 请求来说是必需的。| 创建内部付费请求所涉及商品ID。使用Google Play的应用程序内部付费服务所贩卖的物品在Google Play发布网站必需具有独一无二商品ID。|- | * NONCE*
  | * long*
  | 任何有效的* long* 值。| 对* GET_PURCHASE_INFORMATION* 和* RESTORE_TRANSACTIONS* 请求来说是必需的。| 只使用一次的数字。你的应用程序必须用* RESTORE_TRANSACTIONS_'请求生成并发送一个随机数。该随机数用'_PURCHASE_STATE_CHANGED* 广播intent返回，这样你就可以用这个值来验证Google Play发回的交易响应是否完整。|-| * NOTIFY_IDS*
  | * long* 值的数组| 任何有效的* long* 值数组
  | 对* GET_PURCHASE_INFORMATION* 和* CONFIRM_NOTIFICATIONS* 请求来说是必须的。 | 通知标识符的一个数组。每次购买状态发生改变时，通知ID就会通过广播intent* IN_APP_NOTIFY* 发送到你的应用程序。你可以使用该通知来检索的详细信息的购买状态变化。|-| * DEVELOPER_PAYLOAD*
  | * String*
  | 任何有效的字符串，长度不超过256字符| align="center"|否| 开发者指定的字符串，通过* REQUEST_PURCHASE* 请求指定。本字段在包含订单交易信息的JSON字符串中返回。用此键可发送订单的附加信息，例如，可以使用此键发送订单的索引键，使用数据库来存储购买信息情况，这是非常有用的。建议不要使用此键来发送数据或内容。|}

* BILLING_REQUEST* 键可以有以下值：

• * CHECK_BILLING_SUPPORTED*
  :本请求用于验证 Google Play应用程序是否支持内部付费。通常在应用启动的时候发送此请求，用以判断启用还是禁用某些与内部付费相关的UI功能。

• * REQUEST_PURCHASE*
  :此请求用于给Google Play应用发送购买消息，是进行内部付费的基石。当用户表明其想要购买你应用程序中的某商品时，你就需要发送此请求。接着，Google Play通过用户介绍界面来处理交易。

• * GET_PURCHASE_INFORMATION*
  :此请求用于检索购买状态变化的详细信息。当购买请求支付成功或者结账时取消交易，或是先前交易退款的情况下，购买状态就会改变。购买状态发生改变的时候， Google Play会通知你的应用，这种情况下你只需要发送此请求就可检索交易信息。

• * CONFIRM_NOTIFICATIONS*
  :该请求用于确认你的应用程序接收到购买状态变化的详细信息。也就是说，此消息表明你发送了给定通知的* GET_PURCHASE_INFORMATION* 请求，并且接收到该通知的购买信息。

• * RESTORE_TRANSACTIONS*
  :此请求用于检索用户的交易状态以管理购买（更多信息，请参阅选择购买类型）。只有当你需要获取用户交易状态时才需要发送此消息，通常为应用程序在设备上首次安装或重装的情况。

应用程序的每条内部付费请求会生成同步响应。响应是一个* Bundle*，可以包括以下一个或多个键：

• * RESPONSE_CODE* :此键提供了请求的状态信息和错误信息。
• * PURCHASE_INTENT* :此键提供了* PendingIntent*，用于启动结算activity。
• * REQUEST_ID* :此键提供了请求标识，用它来匹配异步请求的响应。

键与不同类型的请求之间有某种匹配联系。表3展示每个请求类型所返回的相应的键。

• 表3* 应用程序内部付费的请求的每种类型对应的Bundle键的说明。{| style1|- style="background:grey; color:white"| * 请求类型*
  | * 键返回* | * 可能的响应码* |- | * CHECK_BILLING_SUPPORTED*
  | * RESPONSE_CODE* | * RESULT_OK，RESULT_BILLING_UNAVAILABLE，RESULT_ERROR， RESULT_DEVELOPER_ERROR* |- | * REQUEST_PURCHASE*
  | * RESPONSE_CODE，PURCHASE_INTENT，REQUEST_ID*
  | * RESULT_OK，RESULT_ERROR，RESULT_DEVELOPER_ERROR* |- | * GET_PURCHASE_INFORMATION*
  | * RESPONSE_CODE，REQUEST_ID* | * RESULT_OK，RESULT_ERROR，RESULT_DEVELOPER_ERROR* |- | * CONFIRM_NOTIFICATIONS*
  | * RESPONSE_CODE，REQUEST_ID* | * RESULT_OK，RESULT_ERROR，RESULT_DEVELOPER_ERROR* |- | * RESTORE_TRANSACTIONS*
  | * RESPONSE_CODE，REQUEST_ID * | * RESULT_OK，RESULT_ERROR，RESULT_DEVELOPER_ERROR*
  |}

* 应用程序内部付费广播Intent*

一下内容是Google Play发送的应用程序内部付费广播intent的说明。这些广播intent将已发生的内部付费行为通知到你的应用程序。你的应用程序必须接入* BroadcastReceiver_'才能接收广播intent，如'''应用程序内部付费示例'''中的'_BillingReceiver* 。

* com.android.vending.billing.RESPONSE_CODE*

此广播intent含有一个Google Play响应码，在你创建完内部付费请求之后发送。服务器响应码可以表示，付费请求成功发送到Google Play，或者付费请求出现了错误。此intent不是用来报告购买状态的变化（如退款或购买信息）。此响应码相关的更多信息，请参阅* Google Play内部结算响应码_'。示例中赋予此广播intent一个常量'_ACTION_RESPONSE_CODE* 。

• 附加信息[Extras]* :* long* 型的请求ID。请求ID定义特定的付费请求，发出请求后Google Play会返回此ID。:* response_code int* 型的Google Play服务器响应码。

* com.android.vending.billing.IN_APP_NOTIFY*

此响应表明，购买状态发生了改变，购买成功，取消或者退款。该响应包含一个或多个通知ID。每个通知ID对应一个特定的服务器端消息，每一个消息包含一个或多个交易的信息。你的应用程序接收到一个* GET_PURCHASE_INFORMATION_'请求来检索信息的详细信息。该示例赋予此广播intent一个常量'_ACTION_NOTIFY* 。

• 附加信息[Extras]* :* String_'型通知ID，提示购买状态变化。当购买状态发生变化时Google Play会通知你，通知包含一个独一无二的通知ID。使用'_GET_PURCHASE_INFORMATION* 请求发送通知ID，可以获取购买状态改变相关的更多详情。

* com.android.vending.billing.PURCHASE_STATE_CHANGED*

此广播intent包含一个或多个交易的详细信息。交易信息存在于JSON字符串中。JSON字符串带签名，签名是和JSON字符串（未加密）一同发送到你的应用程序的。你的应用程序可以验证这个JSON字符串的签名以确保你的应用内部付费的信息安全。该示例赋予此广播intent一个常量* ACTION_PURCHASE_STATE_CHANGED* 。

• 附加信息[Extras]* :* inapp_signed_data String* 型带签名的JSON字符串。:* inapp_signature String* 型签名。
• 注_'：你的应用程序必须将广播intent和附加信息映射到的常量对应用程序来说必须独一无二。参阅示例中的'_Consts.java* 文件的做法。

JSON字符串中的字段描述如下表（见表4）：

• 表4_' '_PURCHASE_STATE_CHANGED* intent返回的JSON字段描述。{| style1|- style="background:grey; color:white"| 字段| 描述|- | nonce | 只使用一次的数字。你的应用程序生成此随机数，并用* GET_PURCHASE_INFORMATION* 请求发送。Google Play将此随机数作为JSON字符串的一部分回传，这样你就可以验证消息的完整性。|-| notificationId
  | 使用* notificationId_'对应一条在Google Play服务器待检索的特定消息。你的应用程序通过'_notificationId* ，这样Google Play就可以判断哪些信息要检索。|- |orderId
  |交易的唯一标识符，对应Google Wallet Order ID。|- |packageName
  |购买行为发自哪个应用程序包。|- |productId
  |物品的商品标识。每个物品都有一个商品ID，你必须在Google Play发布网站的应用商品列表中指定。|- |purchaseTime
  |商品的购买时间，以毫秒为单位（1970年1月1日之后）。|- |purchaseState
  |订单的购买状态。可能的值为0（已购买），1（取消购买），2（退款），或3（已过期，只用于购买订阅）。|- |purchaseToken
  |标识订阅购买给定物品或和用户对的唯一标记。查询订阅有效性时可以使用该标记指定订阅。只在应用程序内部付费API第2版和更高版本得到支持。|- |developerPayload
  |开发者指定的字符串，其包含订单相关的补充信息。当创建* REQUEST_PURCHASE* 请求时，你可以指定此字段的值。|}

* 验证和取消的HTTP API*

Google Play提供了基于HTTP的API，你可以在任何时间用它来远程查询特定订阅的有效性或取消订阅。此API被设计用于后端服务器安全地管理订阅，以及用其他服务拓展和整合订阅。参阅* Google Play Android开发者API*的更多信息。

* 应用内部付费API版本*

不同版本的API有自己附加功能。运行时，你的应用可以查询Google Play应用以确定它支持哪个版本的API，以及那些功能可用。通常情况下，Google Play应用更新将支持最新版本的API。版本汇总，请参阅* 应用程序内部付费API版本* 。

后面的部分列出了应用程序内部结算API的支持版本。Bundle对象作为参数传给sendBillingRequest()，而使用的API版本由对象的API_VERSION键指定。sendBillingRequest()是在IMarketBillingService.aidl文件中定义的，该文件可在应用程序内部付费* 示例_'中找到。更多详情，请参阅'_应用程序内部付费服务接口*。

* 在应用程序内结算第2版*
2012年5月

• 新增订阅支持。
• * 新增一个字符串值“2”，作为传给* API_VERSION* 键。
• * 新增一个JSON字段，* PURCHASE_STATE_CHANGED_' intent返回给'_orders* 列表。
• * 新增一个purchaseState值，* PURCHASE_STATE_CHANGED_' intent返回给'_orders* 列表。该值表示的订阅已过期，不再有效。
• * 需要Google Play（Play store）3.5或更高版本。

* 在应用程序内结算第1版*

2011年3月
* 最初的版本。
* 需要Google Play/Android Market 2.3.4或更高版本。

category:Android Dev Guide