2013年5月29日水曜日

Google Play In-app Billingを訳してみる「In-app Billing Reference (IAB Version 3)」


In-app Billing レファレンス(IABバージョン3)

この文書はIn-app Billingバージョン3APIを使うための技術的レファレンス情報を提供するものである。

サーバーレスポンスコード

後述のテーブルはすべてのサーバーレスポンスコードを列記している。このレスポンスコードはGoogle Playからあなたのアプリへ送られるものである。Google Playはレスポンスコードを同期的に送る。レスポンスバンドル内でRESPONSE_CODEキーへマッピングされた整数値として。

レスポンスコード　値　詳細
BILLING_RESPONSE_RESULT_OK　0　成功
BILLING_RESPONSE_RESULT_USER_CANCELED　1　ユーザーが戻るボタンを押したかキャンセルダイアログを押した
BILLING_RESPONSE_RESULT_BILLING_UNAVAILABLE　3　Billing APIバージョンがこのタイプのリクエストをサポートしていない
BILLING_RESPONSE_RESULT_ITEM_unAVAILABLE　4　リクエストされた商品が決済で使えない
BILLING_RESPONSE_RESULT_DEVELOPER_ERROR　5　APIに不当な引数が与えられた。このエラーはアプリが正しく署名されていない、Google Play内のIn-app Billingに対して適切に設定されていない、マニュフェストに必要なパーミッションがないことも示している。
BILLING_RESPONSE_RESULT_ERROR　6　API挙動内での致命的エラー
BILLING_RESPONSE_RESULT_ITEM_ALREADY_OWNED　7　アイテムが既に所持されていることによる決済エラー
BILLING_RESPONSE_RESULT_ITEM_NOT_OWNED　8　アイテムが所持されていないことによる消費エラー


APIレファレンス

In-app Billingバージョン3APIはIInAppBillingService.aidlファイル内で定義されている。このファイルはバージョン3のサンプルアプリを含んでいる。

getSkuDetails()メソッド

このメソッドはプロダクトID一覧に対する商品詳細を返す。Google Playによって送られるレスポンスバンドル内で、クエリ結果はDETAILS_LISTキーにマッピングされたArrayList文字列内で保存される。詳細一覧内の各々の文字列はJSON形式の単体商品に対する商品詳細を含んでいる。商品詳細に伴うJSON文字列内のフィールドはtable2でまとめられている。

Table2。商品アイテム詳細に伴うJSONフィールドの詳細はgetSkudetailsリクエストから返される
キー　詳細
productId：商品に対するプロダクトID
type：値はin-app商品に対する"inapp"か定期購入に対する"subs"でなければならない
price：通貨単位を含む商品の定型化された価格。この価格は税を含まない
title：商品タイトル
description：商品の詳細


getBuyIntent()メソッド

このメソッドはRESPONSE_CODEキーでマッピングされたレスポンスコードの整数値を返す。またBUY_INTENTキーでマッピングされたin-appアイテムに対する決済フローを開始するためのPendingIntentを返す。PendingIntentを受け取ったとき、Google Playは決済注文に対するデータと共にレスポンスIntentを送る。レスポンスIntent内で返されたこのデータはtable 3でまとめられている。

Table 3.In-app Billinバージョン3決済リクエストからのレスポンスデータ

キー　詳細
RESPONSE_CODE　もし決済が成功した場合は0、エラーはそれ以外
INAPP_PURCHASE_DATA　JSON形式の文字列。JSONには決済注文に関する詳細を含んでいる。JSONフィールドの詳細に関してはtable4を参照。
INAPP_DATA_SIGNATURE　決済シグネチャーを含む文字列。この決済データはデベロッパーのプライベートキーで署名されている。データ署名はRSASSA-PKCS1-v1_5スキームを用いている

Table4は決済注文に対するレスポンスデータ内で返されるJSONフィールドについて述べている

Table4 INAPP_PURCHASE_DATAに対するJSONフィールドの詳細

フィールド　詳細
orderId：トランザクションに対するユニークなオーダー識別子。これはグーグルウォレットのOrderIDと一致する
packageName：決済が由来するアプリのパッケージ
productId：アイテム商品識別子。すべてのアイテムは商品IDを持っている。このIDはGoogle Playデベロッパーコンソール上でアプリ商品一覧内で定義しなければならない
purchaseTime：商品が決済された時間エポック(1970/1/1)からのミリセコンドで表記。
purchaseState：注文の決済状態。取りうる値は0(purchased),1(canceled),2(refunded)
developerPayload：デベロッパーが定義した文字列。この文字列は注文に関する追加情報を含んでいる。あなたはgetBuyIntentリクエストを生成した際にこのフィールドに対する値を規定することができる。
purchaseToken：付与されたアイテムとユーザーのペアに対する決済を一意に識別するトークン


getPurchases()メソッド

このメソッドはユーザーが所持している現在未消費の商品を返す。Table 5はバンドル内で返されたレスポンスデータを列挙している。

Table 5 getPurchaseリクエストからのレスポンスデータ

キー　詳細
RESPONSE_CODE：リクエストが成功なら0、エラーならそれ以外
INAPP_PURCHASE_ITEM_LIST：このアプリからの決済の商品ID一覧を含むStringArrayList
INAPP_PURCHASE_DATA_LIST：このアプリからの決済詳細を含むStringArrayList。一覧の各々のINAPP_PURCHASE_DATAアイテム内で保存された詳細情報の一覧を参照。
INAPP_DATA_SIGNATURE_LIST：このアプリの決済シグネチャーを含むStringArrayList
INAPP_CONTINUATION_TOKEN：ユーザーが所持しているin-app商品の次のセットを取り出すための連続トークンを含む文字列。ユーザーが所持している商品数がとても多い場合にこれはGoogle Playサービスによってのみセットされる。レスポンス内に連続トークンが存在する場合、あなたはgetPurchasesに対して別のコールを生成しなければならない。そしてあなたが取り出した連続トークンを通さなければならない。次のgetPurchasesコールはより多くの決済を返し、さらなる連続トークンを返すこともありうる。



In-app Billing Reference (IAB Version 3)

This documentation provides technical reference information for using the In-app Billing Version 3 API.

Server Response Codes

The following table lists all of the server response codes that are sent from Google Play to your application. Google Play sends the response code synchronously as an integer mapped to the RESPONSE_CODE key in the response Bundle. Your application must handle all of these response codes.
Table 1. Summary of response codes for In-app Billing Version 3 API calls.
Response Code Value Description
BILLING_RESPONSE_RESULT_OK 0 Success
BILLING_RESPONSE_RESULT_USER_CANCELED 1 User pressed back or canceled a dialog
BILLING_RESPONSE_RESULT_BILLING_UNAVAILABLE 3 Billing API version is not supported for the type requested
BILLING_RESPONSE_RESULT_ITEM_UNAVAILABLE 4 Requested product is not available for purchase
BILLING_RESPONSE_RESULT_DEVELOPER_ERROR 5 Invalid arguments provided to the API. This error can also indicate that the application was not correctly signed or properly set up for In-app Billing in Google Play, or does not have the necessary permissions in its manifest
BILLING_RESPONSE_RESULT_ERROR 6 Fatal error during the API action
BILLING_RESPONSE_RESULT_ITEM_ALREADY_OWNED 7 Failure to purchase since item is already owned
BILLING_RESPONSE_RESULT_ITEM_NOT_OWNED 8 Failure to consume since item is not owned

API Reference

The In-app Billing Version 3 API is defined in the IInAppBillingService.aidl file, which is included with the Version 3 sample application.

The getSkuDetails() method

This method returns product details for a list of product IDs. In the response Bundle sent by Google Play, the query results are stored in a String ArrayList mapped to the DETAILS_LIST key. Each String in the details list contains product details for a single product in JSON format. The fields in the JSON string with the product details are summarized in table 2.
Table 2. Description of JSON fields with product item details returned from a getSkuDetails request.
Key Description
productId The product ID for the product.
type Value must be “inapp” for an in-app product or "subs" for subscriptions.
price Formatted price of the item, including its currency sign. The price does not include tax.
title Title of the product.
description Description of the product.

The getBuyIntent() method

This method returns a response code integer mapped to the RESPONSE_CODE key, and a PendingIntent to launch the puchase flow for the in-app item mapped to the BUY_INTENT key. When it receives the PendingIntent, Google Play sends a response Intent with the data for that purchase order. The data that is returned in the response Intent is summarized in table 3.
Table 3. Response data from an In-app Billing Version 3 purchase request.
Key Description
RESPONSE_CODE 0 if the purchase was success, error otherwise.
INAPP_PURCHASE_DATA A String in JSON format that contains details about the purchase order. See table 4 for a description of the JSON fields.
INAPP_DATA_SIGNATURE String containing the signature of the purchase data that was signed with the private key of the developer. The data signature uses the RSASSA-PKCS1-v1_5 scheme.

Table 4 describes the JSON fields that are returned in the response data for a purchase order.
Table 4. Descriptions of the JSON fields for INAPP_PURCHASE_DATA.
Field Description
orderId A unique order identifier for the transaction. This corresponds to the Google Wallet Order ID.
packageName The application package from which the purchase originated.
productId The item's product identifier. Every item has a product ID, which you must specify in the application's product list on the Google Play Developer Console.
purchaseTime The time the product was purchased, in milliseconds since the epoch (Jan 1, 1970).
purchaseState The purchase state of the order. Possible values are 0 (purchased), 1 (canceled), or 2 (refunded).
developerPayload A developer-specified string that contains supplemental information about an order. You can specify a value for this field when you make a getBuyIntent request.
purchaseToken A token that uniquely identifies a purchase for a given item and user pair.

The getPurchases() method

This method returns the current un-consumed products owned by the user. Table 5 lists the response data that is returned in the Bundle.
Table 5. Response data from a getPurchases request.
Key Description
RESPONSE_CODE 0 if the request was successful, error otherwise.
INAPP_PURCHASE_ITEM_LIST StringArrayList containing the list of productIds of purchases from this app.
INAPP_PURCHASE_DATA_LIST StringArrayList containing the details for purchases from this app. See table 4 for the list of detail information stored in each INAPP_PURCHASE_DATA item in the list.
INAPP_DATA_SIGNATURE_LIST StringArrayList containing the signatures of purchases from this app.
INAPP_CONTINUATION_TOKEN String containing a continuation token to retrieve the next set of in-app products owned by the user. This is only set by the Google Play service if the number of products owned by the user is very large. When a continuation token is present in the response, you must make another call to getPurchases and pass in the continuation token that you received. The subsequent getPurchases call returns more purchases and possibly another continuation token.
投稿者 時刻: