[Android in-app billing第6篇(末)]In-app Billing Reference應用程式金流的相關API(中文翻譯)

這篇能獲得關於Android Market回應碼(response codes)和應用程式內部金流接口的詳細資訊。

原文連結︰In-app Billing Reference
翻譯︰小鰻
翻譯版本號︰v.1.1
如需轉載請註明出處「小鰻的Android學習筆記」
讓我參與最直接的討論以及錯誤修正， 謝謝！

In this document

1. Server Response Codes for In-app Billing
2. In-app Billing Service Interface
3. In-app Billing Broadcast Intents

Downloads

1. Sample Application

See also

1. Overview of In-app Billing
2. Implementing In-app Billing
3. Security and Design
4. Testing In-app Billing
5. Administering In-app Billing

The following document provides technical reference information for the following:

• Android Market Server Response Codes for In-app Billing
• In-app Billing Interface Parameters
• In-app Billing Broadcast Intents

 

Android Market Server Response Codes for In-app Billing針對應用程式金流機制，Android市集伺服器傳來的回應代碼

The following table lists all of the server response codes that are sent from Android Market to your application. Android Market sends these response codes asynchronously as response_code extras in the com.android.vending.billing.RESPONSE_CODE broadcast intent. Your application must handle all of these response codes.
底下的表格列出了我們APP發送給Android市集後，Android伺服器回傳過來的回應代碼。Android市集會以異步的方式，依response_code的extras在com.android.vending.billing.RESPONSE_CODE這個廣播意圖裡，回傳這些回應代碼。您的APP必須針對這些代碼做出相對應的處理。

Table 1. Summary of response codes returned by Android Market.
表1. 藉由Android市集回傳過來的回應碼摘要

Response Code回應代碼	Value值	Description描述
RESULT_OK	0	Indicates that the request was sent to the server successfully. When this code is returned in response to a CHECK_BILLING_SUPPORTED request, indicates that billing is supported. 此回應指出這次的購買請求已經成功的發送至Android市集伺服器了。當這個代碼在我們發出CHECK_BILLING_SUPPORTED請求時被回傳，就表示了此裝置的Android市集有支援iap機制。
RESULT_USER_CANCELED	1	Indicates that the user pressed the back button on the checkout page instead of buying the item. 此回應指出使用者在付費頁面下按了返回鍵而非購買商品。
RESULT_SERVICE_UNAVAILABLE	2	Indicates that the network connection is down. 此回應指出網路連線失效。
RESULT_BILLING_UNAVAILABLE	3	Indicates that in-app billing is not available because the API_VERSION that you specified is not recognized by the Android Market application or the user is ineligible for in-app billing (for example, the user resides in a country that prohibits in-app purchases). 此回應指出iap機制不被支援，主因是您指定的API_VERSION無法被Android市集軟體識別，或者使用者是無資格使用iap機制(舉例，使用者住在禁止使用iap機制的國家)
RESULT_ITEM_UNAVAILABLE	4	Indicates that Android Market cannot find the requested item in the application's product list. This can happen if the product ID is misspelled in your REQUEST_PURCHASE request or if an item is unpublished in the application's product list. 此回應指出Android市集無法找到此請求的應用程式內產品列表的商品。這可能是因為您在發送REQUEST_PURCHAS請求時，產品ID拚錯了，或者是在應用程式產品列表上的商品尚未被發佈。
RESULT_DEVELOPER_ERROR	5	Indicates that an application is trying to make an in-app billing request but the application has not declared the com.android.vending.BILLING permission in its manifest. Can also indicate that an application is not properly signed, or that you sent a malformed request, such as a request with missing Bundle keys or a request that uses an unrecognized request type. 此回應指出您的APP試圖發送iap請求，但是APP的AnddroidManifest.xml裡卻沒有宣告com.android.vending.BILLING權限。也可能是因為應用程式沒有正確的被簽署，或者您發送了一個非正確格式的請求，像是忘了傳Bundle的key值或者是使用了一個無法被識別的請求類型。
RESULT_ERROR	6	Indicates an unexpected server error. For example, this error is triggered if you try to purchase an item from yourself, which is not allowed by Google Checkout. 此回應指出Android市集傳來了一個無法預期的伺服器錯誤。舉例來說，這個錯誤是出自您居然想要購買您自己在販售的商品，而這個商品卻沒有被Google Checkout允許販售。

 

In-app Billing Service Interface應用程式金流服務的接口

The following section describes the interface for Android Market's in-app billing service. The interface is defined in the IMarketBillingService.aidl file, which is included with the in-app billing sample application.
底下的段落將描述Android市集iap機制服務的接口。這個接口被定義在IMarketBillingService.aidl檔裡，這個檔被包在iap範例程式裡。
The interface consists of a single request method sendBillingRequest(). This method takes a single Bundle parameter. The Bundle parameter includes several key-value pairs, which are summarized in table 2.
這個接口是由一個叫sendBillingRequest()的請求函式組成的。這個函式有一個Bundle參數，該Bundle參數包含數對key-value，這些key-value會在表2做摘要說明。

Table 2. Description of Bundle keys passed in a sendBillingRequest() request.
表2. 描述在sendBillingRequest()請求裡，傳送Bundle給市集的key有哪些

Key	Type型態	Possible Values 有效值	Required? 需要？	Description描述
BILLING_REQUEST	String	CHECK_BILLING_SUPPORTED, REQUEST_PURCHASE, GET_PURCHASE_INFORMATION, CONFIRM_NOTIFICATIONS, or RESTORE_TRANSACTIONS	Yes	The type of billing request you are making with the sendBillingRequest() request. The possible values are discussed more below this table. 這些是您在發送sendBillingRequest()請求時回應您的的金流請求類型值。這些有效值會在這個表格的下面被討論。
API_VERSION	int	1	Yes	The version of Android Market's in-app billing service you are using. The current version is 1. 告知您正在使用的iap機制服務的Android市集版號。正確值為1
PACKAGE_NAME	String	A valid package name.有效的套件名稱	Yes	The name of the application that is making the request. 請求購買商品的應用程式名稱。
ITEM_ID	String	Any valid product identifier.有效的產品識別碼	Required for REQUEST_PURCHASE requests. 當發出REQUEST_PURCHASE請求時會需要	The product ID of the item you are making a billing request for. Every in-app item that you sell using Android Market's in-app billing service must have a unique product ID, which you specify on the Android Market publisher site. 您正在請求購買的產品ID。每次您所販售Android市集iap服務的產品ID都必須是唯一。這些ID被您在Android市集發佈網站指定。
NONCE	long	Any valid long value.任何有效的long值	Required for GET_PURCHASE_INFORMATION and RESTORE_TRANSACTIONS requests. 當發出GET_PURCHASE_INFORMATION和RESTORE_TRANSACTIONS請求時會需要。	A number used once. Your application must generate and send a nonce with each GET_PURCHASE_INFORMATION and RESTORE_TRANSACTIONS request. The nonce is returned with the PURCHASE_STATE_CHANGED broadcast intent, so you can use this value to verify the integrity of transaction responses form Android Market. 僅用一次的數值。您的APP必須在每次發出GET_PURCHASE_INFORMATIONhdr RESTORE_TRANSACTIONS請求時，產生並發生出一個隨機數。這組隨機數會在Android市集發出PURCHASE_STATE_CHANGED這個廣播意圖時回傳給您。因此您可以用這個值來驗証從Android市集傳來的完整交易回應。
NOTIFY_IDS	Array of long values	Any valid array of long values有效的long型態陣列值	Required for GET_PURCHASE_INFORMATION and CONFIRM_NOTIFICATIONS requests. 當發出GET_PURCHASE_INFORMATION和CONFIRM_NOTIFICATIONS請求時會需要。	An array of notification identifiers. A notification ID is sent to your application in an IN_APP_NOTIFY broadcast intent every time a purchase changes state. You use the notification to retrieve the details of the purchase state change. 這是一個訊息通知識別碼的陣列值。訊息通知ID在每次購買狀態遭改變時，Android市集發送IN_APP_NOTIFY廣播意圖時夾帶並傳送給您。
DEVELOPER_PAYLOAD 開發者的酬載  (譯者註︰在資料安全領域裡，往往在資料的傳輸過程會加入一些特定值，來確認每一次的傳輸皆為安全的。payload就是一個為了資料安全而存在的值)	String	Any valid String less than 256 characters long.有效值在256個字元內	No	A developer-specified string that can be specified when you make a REQUEST_PURCHASE request. This field is returned in the JSON string that contains transaction information for an order. You can use this key to send supplemental information with an order. For example, you can use this key to send index keys with an order, which is useful if you are using a database to store purchase information. We recommend that you do not use this key to send data or content. 這是一個開發者自訂的字串值。每當您發出REQUEST_PURCHASE請求時可以拿這組字串值做特殊的標註。這個字串會在市集回傳包含訂單的交易資訊JSON字串時被夾帶並回傳回來。您可以使用這個key來發送訂單補充說明的資訊。舉例，您可以使用這個key來發送訂單的索引key，這在假設您正使用資料庫來儲存購買資訊時會很有用。我們建議您不要使用這個key值來發送資料或內容。

The BILLING_REQUEST key can have the following values:
BILLING_REQUEST的key值可以帶下列這些︰

• CHECK_BILLING_SUPPORTED This request verifies that the Android Market application supports in-app billing. You usually send this request when your application first starts up. This request is useful if you want to enable or disable certain UI features that are relevant only to in-app billing.
CHECK_BILLING_SUPPORTED 這樣請求是拿來做Android市集軟體是否支援iap機制的驗証用的。通常在您的APP第1次啟動時，會發出這個請求。這個請求在您想要啟動或取消特定的使用介面的功能(這些功能是提供給付費功能用的)時，是很有用的。

• REQUEST_PURCHASE This request sends a purchase message to the Android Market application and is the foundation of in-app billing. You send this request when a user indicates that he or she wants to purchase an item in your application. Android Market then handles the financial transaction by displaying the checkout user interface.
REQUEST_PURCHASE 這個請求是iap機制的基礎，會發送購買訊息至Android市集軟體。當使用者想要購買應用程式內商品時，您就可以發送此請求。Android市集會呈現付費使用介面給使用者並處理接著會處理金融交易。

• GET_PURCHASE_INFORMATION This request retrieves the details of a purchase state change. A purchase state change can occur when a purchase request is billed successfully or when a user cancels a transaction during checkout. It can also occur when a previous purchase is refunded. Android Market notifies your application when a purchase changes state, so you only need to send this request when there is transaction information to retrieve.
GET_PURCHASE_INFORMATION這個請求會去接收購買狀態遭改變的詳細資訊。當購買請求付費成功或當使用者在付費途中取消了交易，都會發生購買狀態遭改變這個事件。當然，這也可能是使用者退費了之前的商品購買。Android市集一旦遇到商品狀態遭改變時，就會通知您的APP，因此，這個請求只要在Android市集要求您接收交易資訊時再發出即可。
• CONFIRM_NOTIFICATIONS This request acknowledges that your application received the details of a purchase state change. That is, this message confirms that you sent a GET_PURCHASE_INFORMATION request for a given notification and that you received the purchase information for the notification.
CONFIRM_NOTIFICATIONS 這個請求目的是向Android市集承認您已經收到購買狀態遭改變的詳細資訊。因此，這個訊息也可以說是向Android市集再次確認您之前發送過GET_PURCHASE_INFORMATION出去，您已經接收到了購買資訊的通知了。

• RESTORE_TRANSACTIONS This request retrieves a user's transaction status for managed purchases (see Choosing a Purchase Type for more information). You should send this message only when you need to retrieve a user's transaction status, which is usually only when your application is reinstalled or installed for the first time on a device.
RESTORE_TRANSACTIONS 這個請求接收了使用者被管理的購買商品的交易狀態(見Choosing a Purchase Type查看更多資訊)。若要發送此請求，應該只會在當您需要接收使用者的交易狀態，由其是您的APP被再次安裝或者在裝置上第1次安裝時。

Every in-app billing request generates a synchronous response. The response is a Bundle and can include one or more of the following keys:
每次iap請求都會產生從Android市集來的同步回應。這些回應都以Bundle傳送， 裡面也包含了一至多組的key值，key值如下︰

• RESPONSE_CODE This key provides status information and error information about a request.
RESPONSE_CODE 這個key值提供關於請求的狀態資訊和錯誤資訊。

• PURCHASE_INTENT This key provides a PendingIntent, which you use to launch the checkout activity.
PURCHASE_INTENT 這個請求提供了一個PendingIntent，它讓您可以啟動付費的Activity。
• REQUEST_ID This key provides you with a request identifier, which you can use to match asynchronous responses with requests.
REQUEST_ID 這個key值提供您請求的識別碼，可以用這個碼來替傳來的異步回應做比對是否相符。

Some of these keys are not relevant to certain types of requests. Table 3 shows which keys are returned for each request type.
這裡的有些key值跟某些特定類型的請求並不相關。表3顯示了每個請求類型各會傳回哪些key值。

Table 3. Description of Bundle keys that are returned with each in-app billing request type.
表3. 每個iap機制請求類型各回傳的Bundle key值描述

Request Type請求類型	Keys Returned傳回的key值	Possible Response Codes可能傳回的回應碼
CHECK_BILLING_SUPPORTED 檢查裝置是否支援iap	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 還原交易狀態至APP裡	RESPONSE_CODE, REQUEST_ID	RESULT_OK, RESULT_ERROR, RESULT_DEVELOPER_ERROR

 

In-app Billing Broadcast Intents應用程式金流傳來的廣播意圖

The following section describes the in-app billing broadcast intents that are sent by the Android Market application. These broadcast intents inform your application about in-app billing actions that have occurred. Your application must implement a BroadcastReceiver to receive these broadcast intents, such as the BillingReceiver that's shown in the in-app billing sample application.
底下的段落會描述由Android市集軟體傳來的iap機制廣播意圖。這些廣播意圖會通知您的APP關於iap機制的動作發生了。您的APP必須去實作一個廣播接收機制(BroadcastReceiver)去接收這些傳來的廣播意圖，像是iap範例程式裡的BillingReceiver就是這樣的一個元件。

com.android.vending.billing.RESPONSE_CODE

This broadcast intent contains an Android Market response code, and is sent after you make an in-app billing request. A server response code can indicate that a billing request was successfully sent to Android Market or it can indicate that some error occurred during a billing request. This intent is not used to report any purchase state changes (such as refund or purchase information). For more information about the response codes that are sent with this response, see Android Market Response Codes for In-app Billing. The sample application assigns this broadcast intent to a constant named ACTION_RESPONSE_CODE.
這個廣播意圖包含了從Android市集而來的回應碼，是在您發送了iap金流請求後傳來的。回應碼可以表示金流請求是否成功的傳至Android市集。這個意圖不是用來報告任何購買狀態遭改變(像是退費或購買資訊)。更多發送請求得到此回應的資訊，請見Android Market Response Codes for In-app Billing這一篇。範例程式裡將這個廣播意圖指派到一個叫ACTION_RESPONSE_CODE的實體。

Extras其它傳來的值

• request_id—a long representing a request ID. A request ID identifies a specific billing request and is returned by Android Market at the time a request is made.
• request_id - 代表這次請求ID的一個long值。請求的ID是拿來識別特定金流請求，而且是由Android市集在請求的同一時間回傳過來的。
• response_code—an int representing the Android Market server response code.
• response_code - 代表Android市集伺服器的一個int值回應碼。

com.android.vending.billing.IN_APP_NOTIFY

This response indicates that a purchase has changed state, which means a purchase succeeded, was canceled, or was refunded. This response contains one or more notification IDs. Each notification ID corresponds to a specific server-side message, and each messages contains information about one or more transactions. After your application receives an IN_APP_NOTIFY broadcast intent, you send a GET_PURCHASE_INFORMATION request with the notification IDs to retrieve the message details. The sample application assigns this broadcast intent to a constant named ACTION_NOTIFY.
這個回應指出購買狀態遭到改變了，也就是說購買成功了，也或者取消、甚至退費了。這個回應包含了一至多個訊息通知IDs。每一個訊息通知ID都與特定的伺服端訊息相對應，每個訊信也包含了關於一或多個交易的資訊。當您的APP接收到了IN_APP_NOTIFY這個廣播意圖後，您就要發送含這個訊息通知ID的GET_PURCHASE_INFORMATION請求出去，接收詳細的交易訊息。範例程式將這個廣播意圖指派至一個名叫ACTION_NOTIFY的實體。

Extras其它傳來的值

• notification_id—a String representing the notification ID for a given purchase state change. Android Market notifies you when there is a purchase state change and the notification includes a unique notification ID. To get the details of the purchase state change, you send the notification ID with the GET_PURCHASE_INFORMATION request.
• notification_id - 代表購買狀態遭改變的訊息通知ID，是一個String值。Android市集會在當購買狀態遭到改變時，傳送一個唯一性的訊息通知ID給您。如果想要取得購買狀態改變的詳細資訊，就要發送一個含訊息通知ID的GET_PURCHASE_INFORMATION請求至Android市集。

com.android.vending.billing.PURCHASE_STATE_CHANGED

This broadcast intent contains detailed information about one or more transactions. The transaction information is contained in a JSON string. The JSON string is signed and the signature is sent to your application along with the JSON string (unencrypted). To help ensure the security of your in-app billing messages, your application can verify the signature of this JSON string. The sample application assigns this broadcast intent to a constant named ACTION_PURCHASE_STATE_CHANGED.
這個廣播意圖夾帶了一或多個交易的詳細資訊。 交易的詳細資訊是由JSON字串傳來的，此外，這個JSON不僅被簽署過，還順便傳來一個數位簽章(未加密的狀態)。為了幫助您確認您iap機制訊息的安全，您的APP可以驗証這個JSON字串傳來的數位簽章。範例程式中將PURCHASE_STATE_CHANGE這個廣播意圖指派到一個叫ACTION_PURCHASE_STATE
_CHANGED的實體。

Extras其它傳來的值

• inapp_signed_data—a String representing the signed JSON string.
• inapp_signed_data - 一個簽署過的JSON字串。
• inapp_signature—a String representing the signature.
• inapp_signature - 一個數位簽章字串。

Note: Your application should map the broadcast intents and extras to constants that are unique to your application. See the Consts.java file in the sample application to see how this is done.

The fields in the JSON string are described in the following table (see table 4)
註︰您應該在您的APP裡詳細的計劃每一個廣播意圖和其它傳來的值的實體都具有唯一性。 請見範例程式裡Consts.java檔是如何做的。
JSON字串的值都描述至下列的表格中(見表4)

Table 4. Description of JSON fields that are returned with a PURCHASE_STATE_CHANGED intent.
表4. 藉由PURCHASE_STATE_CHANGE意圖傳來的JSON值的描述

Field值	Description描述
nonce 隨機數	A number used once. Your application generates the nonce and sends it with the GET_PURCHASE_INFORMATION request. Android Market sends the nonce back as part of the JSON string so you can verify the integrity of the message. 僅用一次的一個數值。當要發送GET_PURCHASE_INFORMATION請求時，您的APP要產生一組隨機數一起發送。Android市集會再將這個隨機數塞進JSON字串當中，傳回給您。因此您可以用這個方法來驗証Android市集傳來的訊息的完整性。
notificationId 訊息通知id	A unique identifier that is sent with an IN_APP_NOTIFY broadcast intent. Each notificationId corresponds to a specify message that is waiting to be retrieved on the Android Market server. Your application sends back the notificationId with the GET_PURCHASE_INFORMATION message so Android Market can determine which messages you are retrieving. 這是從IN_APP_NOTIFY廣播意圖一起傳來的唯一性識別碼(unique identifier)。每次Android市集發出IN_APP_NOTIFY時，市集伺服器自己會留住這組識別碼，因此當您的APP之後透過GET_PURCHASE_INFORMATION訊息傳送這組識別碼回去時，Android市集就能清楚的知道您剛才接收的是哪一個訊息。
orderId 訂單id	A unique order identifier for the transaction. This corresponds to the Google Checkout Order ID. 這是這次交易的唯一性訂單識別碼(unique order identifier) ，這個識別碼會和Google Checkout的訂單編號ID相符。
packageName 套件名稱	The application package from which the purchase originated. APP套件的購買起源(譯者註︰不確定是否正確)
productId 產品id	The item's product identifier. Every item has a product ID, which you must specify in the application's product list on the Android Market publisher site. 商品的產品識別碼。每個商品都有產品ID，您必須在Android市集發佈網站裡的應用程式產品列表裡指定這些產品ID。
purchaseTime 購買時間	The time the product was purchased, in milliseconds since the epoch (Jan 1, 1970). 購買商品的時間。 從32位元的起源時間算起(1970/07/01)的毫秒時間。 (譯者註︰可以到此網站換算現在時間。)
purchaseState 購買狀態	The purchase state of the order. Possible values are 0 (purchased), 1 (canceled), or 2 (refunded). 訂單的購買狀態。有效值為0(已購買)、1(購買中途取消)、2(退費)。
developerPayload 開發者的酬載	A developer-specified string that contains supplemental information about an order. You can specify a value for this field when you make a REQUEST_PURCHASE request. 開發者指定的一組字串，用來補充關於訂單的資訊。當您要發出REQUEST_PURCHASE請求時，可以指定這個值。

相關文章︰

1.[Android in-app billing前言]In-app Billing應用程式內部付費機制(中文翻譯)
2.[Android in-app billing第1篇]In-app Billing Overview應用程式內部付費機制概述(中文翻譯)
3.[Android in-app billing第2篇]Implementing In-app Billing實作應用程式內部金流機制(中文翻譯)
4.[Android in-app billing第3篇]Security and Design安全與設計(中文翻譯)
5.[Android in-app billing第4篇]Testing In-app Billing測試應用程式內金流機制(中文翻譯)
6.[Android in-app billing第5篇]Administering In-app Billing應用程式內金流機制的管理(中文翻譯)
7.[Android in-app billing第6篇(末)]In-app Billing Reference應用程式金流的相關API(中文翻譯)