學習如何設定你的產品列表、註冊測試帳戶和處理退款的問題。

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

In this document

Downloads

Sample Application

Creating a Product List建立產品列表

The Android Market publisher site provides a product list for each of your published applications. You can sell an item using Android Market's in-app billing feature only if the item is listed on an application's product list. Each application has its own product list; you cannot sell items that are listed in another application's product list.
You can access an application's product list by clicking the In-App Products link that appears under each of the applications that are listed for your publisher account (see figure 1). The In-App Products link appears only if you have a Google Checkout merchant account and an application's manifest includes the com.android.vending.BILLING permission.
Android市集發佈網站提供您每一個發佈的APP的產品列表，您要銷售的應用程式內商品僅能來至於這張列表上的商品。每一個應用程都擁有自已的列表清單，您無法銷售別隻APP裡的產品列表商品至另一隻APP裡。
存取應用程式產品列表的方式，就是點擊每一個軟體下方的In-App Products連結(見圖1)。In-App Products連結會在如果您擁有Google Checkout merchant帳戶，並且APP裡的Androidmanifest.xml檔有宣告com.android.vending.BILLING權限時，才會出現。

Figure 1. You can access an application's product list by clicking the In-App Products link.
圖1. 您可以透過點擊In-App Products連結的方式來存取應用程式產品列表。

A product list contains information about the items you are selling, such as a product id, product description, and price (see figure 2). The product list stores only metadata about the items you are selling in your application. It does not store any digital content. You are responsible for storing and delivering the digital content that you sell in your applications.
產品列表列出了您目前販賣的商品資訊，像是產品的id、產品描述或價格(見圖2)。產品列表僅會儲存關於您在您APP裡賣的商品的詮釋資料(metadata)。並不會儲任何的數位化內容。儲存和傳遞您售於APP內的數位內容是您的責任。

Figure 2. An application's product list.
圖2. 這是一隻APP裡的產品列表

You can create a product list for any published application or any draft application that's been uploaded and saved to the Android Market site. However, you must have a Google Checkout merchant account and the application's manifest must include the com.android.vending.BILLING permission. If an application's manifest does not include this permission, you will be able to edit existing items in the product list but you will not be able to add new items to the list. For more information about this permission, see Updating Your Application's Manifest.
您可以替任何已發佈出去或上傳並儲存至Android市集網站的草稿型APP建立個別的產品列表。然而，您必須擁有Google Checkout merchant帳戶，APP裡的Androidmanifest.xml檔也必須包含com.android.vending.BILLING的權限宣告。如果沒有做此宣告，您還是可以編輯之前已存在過的產品列表，但您也因而無法再新增商品了。更多關於權限的資訊，請參見Updating Your Application's Manifest。

In addition, an application package can have only one product list. If you create a product list for an application, and you use the multiple APK feature to distribute more than one APK for that application, the product list applies to all APK versions that are associated with the application listing. You cannot create individual product lists for each APK if you are using the multiple APK feature.
附帶一提，一個APP套件僅能擁有一個產品列表。如果您替一個APP建立了產品列表，然後您使用一款應用程式多種版本功能的方式來發佈1隻APP，產品列表接受的是來自各種版本的所有連結。您無法替各個版本的APK建立特定的產品列表。

You can add items to a product list two ways: you can add items one at a time by using the In-app Products UI (see figure 3), or you can add a batch of items by importing the items from a comma-separated values (CSV) file (see figure 2). Adding items one at a time is useful if your application has only a few in-app items or you are adding only a few items to a product list for testing purposes. The CSV file method is useful if your application has a large number of in-app items.
您可以使用2種方式來新增商品至產品列表︰使用同時間單一產品上架的iap產品使用介面(見圖3)，或者您可以CSV檔匯入(見圖2)。如果您的APP只有幾個應用程式內商品要銷售或拿來做測試，前者的方式是很有用的。CSV檔的方式則是在如果有大量的應用程式內商品要銷售時有用。

Adding items one at a time to a product list同時間新增一件商品至產品列表

To add an item to a product list using the In-app Products UI, follow these steps:
如果要使用應用程式商品使用介面來新增商品列表，請跟著底下的步驟︰

Log in to your publisher account.
In the All Android Market listings panel, under the application name, click In-app Products.
On the In-app Products List page, click Add in-app product.
On the Create New In-app Product page (see figure 3), provide details about the item you are selling and then click Save or Publish.

Figure 3. The Create New In-app Product page lets you add items to an application's product list.
圖3. 這是讓您可以新增應用程式產品列表的頁面

You must enter the following information for each item in a product list:
產品列表裡的每件商品，您都必須輸入下列的資訊︰

In-app Product ID Product IDs are unique across an application's namespace. A product ID must start with a lowercase letter or a number, and must be composed using only lowercase letters (a-z), numbers (0-9), underlines (_), and dots (.). The product ID "android.test" is reserved, as are all product IDs that start with "android.test." In addition, you cannot modify an item's product ID after it is created, and you cannot reuse a product ID.

In-app Product ID

Purchase Type The purchase type can be Managed per user account or Unmanaged. You can never change an item's purchase type after you set it. For more information, see Choosing a purchase type later in this document.

Purchase Type

Choosing a purchase type

Publishing State An item's publishing state can be Published or Unpublished . To be visible to a user during checkout, an item's publishing state must be set to Published and the item's application must be published on Android Market.
Note: This is not true for test accounts. An item is visible to a test account if the application is not published and the item is published. See Testing In-app Billing for more information.
Publishing State 商品發佈狀態區分為已發佈或未發佈2種型態。如果要讓商品在付費期間能夠被看見，商品狀態就應該設為已發佈，而且擁有該商品的APP也應該是以「已發佈」的狀態存放在Android市集上。
註︰如果是測試帳戶就不在此限。因為當您在測試時，測試帳戶允許你以不發佈APP、而內部商品為已發佈的狀態來進行。可以查看Testing In-app Billing得到更多資訊。
Language The language setting determines which languages are used to display the item title and item description during checkout. A product list inherits its default language from the parent application. You can add more languages by clicking add language. You can also choose to have the title and description automatically translated from the default language by selecting the Fill fields with auto translation checkbox (see figure 4). If you do not use the auto translation feature, you must provide the translated versions of the title and description.

語系

新增語系

自動翻譯並填入

Title The title is a short descriptor for the item. For example, "Sleeping potion." Titles must be unique across an application's namespace. Every item must have a title. The title is visible to users during checkout. For optimum appearance, titles should be no longer than 25 characters; however, titles can be up to 55 characters in length.

標題

Description The description is a long descriptor for the item. For example, "Instantly puts creatures to sleep. Does not work on angry elves." Every item must have a description. The description is visible to users during checkout. Descriptions can be up to 80 characters in length.

描述

Price You must provide a default price in your home currency. You can also provide prices in other currencies, but you can do this only if a currency's corresponding country is listed as a target country for your application. You can specify target countries on the Edit Application page in the Android Market developer console.
To specify prices in other currencies, you can manually enter the price for each currency or you can click Auto Fill and let Android Market do a one-time conversion from your home currency to the currencies you are targeting (see figure 4).

價格

Figure 4. Specifying additional currencies and additional languages for the item title and description.
圖4. 替每件商品的標題和描述指定其它的匯率和其它的語系。

For more information about product IDs and product lists, see Creating In-App Product IDs. For more information about pricing, see In-App Billing Pricing.

Note: Be sure to plan your product ID namespace. You cannot reuse or modify product IDs after you save them.
更多關於產品IDs和產品列表的資訊，請參閱Creating In-App Product IDs。如果想知道價格的資訊，則參閱 In-App Billing Pricing這篇。
註︰請有計劃的規劃您的產品ID命名。因為一旦商品被儲存，產品ID就無法被更改了。

Adding a batch of items to a product list增加批量商品至產品列表

To add a batch of items to a product list using a CSV file, you first need to create your CSV file. The data values that you specify in the CSV file represent the same data values you specify manually through the In-app Products UI (see Adding items one at a time to a product list). The CSV file uses commas (,) and semi-colons (;) to separate data values. Commas are used to separate primary data values, and semi-colons are used to separate subvalues. For example, the syntax for the CSV file is as follows:
使用CSV檔來新增批量商品，首先您必須建立您的CSV檔。CSV裡的資料呈現方式就如同您在產品使用介面以手動的方式新增商品一樣。 (見 Adding items one at a time to a product list)。CSV檔使用逗號(,)和分號(;)來分隔資料。逗號用來分隔主要資料的值，而分號用來分隔次資料。舉例，一個CSV檔裡的語法應該像下面這樣子︰

"product_id","publish_state","purchase_type","autotranslate ","locale; title; description","autofill","country; price"

Descriptions and usage details are provided below.
底下是描述和使用方式︰

product_id This is equivalent to the In-app Product ID setting in the In-app Products UI. If you specify a product_id that already exists in a product list, and you choose to overwrite the product list while importing the CSV file, the data for the existing item is overwritten with the values specified in the CSV file. The overwrite feature does not delete items that are on a product list but not present in the CSV file.

publish_state This is equivalent to the Publishing State setting in the In-app Products UI. Can be published or unpublished.

purchase_type This is equivalent to the Purchase Type setting in the In-app Products UI. Can be managed_by_android, which is equivalent to Managed per user account in the In-app Products UI, or managed_by_publisher, which is equivalent to Unmanaged in the In-app Products UI.

managed_by_android，不受管理的值是

managed_by_publisher。

autotranslate This is equivalent to selecting the Fill fields with auto translation checkbox in the In-app Products UI. Can be true or false.

自動翻譯並填入

locale This is equivalent to the Language setting in the In-app Products UI. You must have an entry for the default locale. The default locale must be the first entry in the list of locales, and it must include a title and description. If you want to provide translated versions of the title and description in addition to the default, you must use the following syntax rules:

autotranslate is true, you must specify the default locale, default title, default description, and other locales using the following format:

"true,"default_locale; default_locale_title; default_locale_description; locale_2; locale_3, ..."

autotranslate is false, you must specify the default locale, default title, and default description as well as the translated titles and descriptions using the following format:

"false,"default_locale; default_locale_title; default_locale_description; locale_2; locale_2_title; local_2_description; locale_3; locale_3_title; locale_3_description; ..."

locale

title This is equivalent to the Title setting in the In-app Products UI. If the title contains a semicolon, it must be escaped with a backslash (for example, "\;"). A backslash should also be escaped with a backslash (for example, "\\">.

description This is equivalent to the Description in the In-app Products UI. If the description contains a semicolon, it must be escaped with a backslash (for example, "\;"). A backslash should also be escaped with a backslash (for example, "\\">.

autofill This is equivalent to clicking Auto Fill in the In-app Products UI. Can be true or false. The syntax for specifying the country and price varies depending on which autofill setting you use.

autofill is set to true, you need to specify only the default price in your home currency and you must use this syntax:

"true","default_price_in_home_currency"

autofill is set to false, you need to specify a country and a price for each currency and you must use the following syntax:

"false", "

home_country

;

default_price_in_home_currency

;

country_2

;

country_2_price

;

country_3

;

country_3_price

; ..."

country The country for which you are specifying a price. You can only list countries that your application is targeting. The country codes are two-letter uppercase ISO country codes (such as "US") as defined by ISO 3166-2.

ISO 3166-2

price This is equivalent to the Price in the In-app Products UI. The price must be specified in micro-units. To convert a currency value to micro-units, you multiply the real value by 1,000,000. For example, if you want to sell an in-app item for $1.99 you specify 1990000 in the price field.

Table 1. Language codes you can use with the locale field.
表1. 地區欄位裡您可以使用的語系代碼

Language	Code	Language	Code
Chinese	zh_TW	Italian	it_IT
Czech	cs_CZ	Japanese	ja_JP
Danish	da_DK	Korean	ko_KR
Dutch	nl_NL	Norwegian	no_NO
English	en_US	Polish	pl_PL
French	fr_FR	Portuguese	pt_PT
Finnish	fi_FI	Russian	ru_RU
German	de_DE	Spanish	es_ES
Hebrew	iw_IL	Swedish	sv_SE
Hindi	hi_IN	--	--

To import the items that are specified in your CSV file, do the following:
如果想要匯入您指定的CSV檔，請照以下方式︰

登入

In the All Android Market listings panel, under the application name, click In-app Products.

所有Adroid市集列表

應用程式內商品

On the In-app Products List page, click Choose File and select your CSV file. The CSV file must be on your local computer or on a local disk that is connected to your computer.

選擇檔案

Select the Overwrite checkbox if you want to overwrite existing items in your product list. This option overwrites values of existing items only if the value of the product_id in the CSV file matches the In-app Product ID for an existing item in the product list. Overwriting does not delete items that are on a product list but not present in the CSV file.

覆寫

On the In-app Products List page, click Import from CSV.

從CSV匯入

You can also export an existing product list to a CSV file by clicking Export to CSV on the In-app Product List page. This is useful if you have manually added items to a product list and you want to start managing the product list through a CSV file.
您也可以使用iap產品列表頁的匯出至CSV功能將既有的產品列表匯出成CSV檔。如果您已經手動新增商品至產品列表，然後您想要開始透過CSV檔管理您的產品項目時，這個方法會很有用。

Choosing a Purchase Type選擇商品的購買型態

An item's purchase type controls how Android Market manages the purchase of the item. There are two purchase types: "managed per user account" and "unmanaged."
Items that are managed per user account can be purchased only once per user account. When an item is managed per user account, Android Market permanently stores the transaction information for each item on a per-user basis. This enables you to query Android Market with the RESTORE_TRANSACTIONS request and restore the state of the items a specific user has purchased.
商品的購買型態控制了Android市集要以何種方式來管理該商品的購買行為。這裡有2種購買型態，分別為︰「受管理(依用帳戶)」和「不受管理」。經使用帳戶管理的商品僅能被每位使用者購買一次。當商品在這種狀態下， Android市集會以每個使用者當基礎來替每件商品儲存交易資訊，而且會被永久儲存。這種商品型態讓您可以透過發出RESTORE_TRANSACTIONS請求來跟Android市集查詢，並且能針對特定使用者(再次安裝APP時)還原該商品為已購買的狀態。
If a user attempts to purchase a managed item that has already been purchased, Android Market displays an "Item already purchased" error. This occurs during checkout, when Android Market displays the price and description information on the checkout page. When the user dismisses the error message, the checkout page disappears and the user returns to your user interface. As a best practice, your application should prevent the user from seeing this error. The sample application demonstrates how you can do this by keeping track of items that are managed and already purchased and not allowing users to select those items from the list. Your application should do something similar—either graying out the item or hiding it so that it cannot be selected.
如果使用者試圖購買一件被管理的商品，但是該商品他早就買過了，Android市集就會顯示出""商品已經買過了"的錯誤訊息。這個訊息會在當Android市集要在付費頁面顯示價格和商品描述資訊的付費流程中發生。當使用者沒看到這個錯誤訊息時，付費頁面卻消失了，畫面返回您AP的使用介面，這種狀況下，最好的方式我們認為︰您的APP根本不應該讓使用者看到該錯誤訊息！範例程式有說明您可以如何做到被管理類型的商品做出商品追蹤，並且直接將購買過的商品在APP列表裡隱藏。您現在要實作iap機制的APP也應該如此 - 將那些已經買過的商品反灰或隱藏、甚至是設成無法被點選的狀態吧！
The "manage by user account" purchase type is useful if you are selling items such as game levels or application features. These items are not transient and usually need to be restored whenever a user reinstalls your application, wipes the data on their device, or installs your application on a new device.
如果您現在要販售的是遊戲等級或應用程式的特殊功能，「被使用帳戶管理」的類型商品是很有用的。這些商品不會被傳輸、而且通常需要被還原，無論是使用者再度安裝您的APP、或者使用者清除了他們的裝置資料、甚至是在新的裝置上安裝您的APP時，都很有用。
Items that are unmanaged do not have their transaction information stored on Android Market, which means you cannot query Android Market to retrieve transaction information for items whose purchase type is listed as unmanaged. You are responsible for managing the transaction information of unmanaged items. Also, unmanaged items can be purchased multiple times as far as Android Market is concerned, so it's also up to you to control how many times an unmanaged item can be purchased.
「不被管理的商品」，他們的交易資訊不會被儲存在Android市集裡。這意謂著您無法針對購買商品類型被設為"不被管理"的商品，向Android市集做查詢交易資訊的動作。此時，這些不被管理商品的交易資訊，管理責任就落在您的手上了。而且，不被管理的商品可以被無限次數購買，所以，這種類型的商品倒底能被購買幾次，完全交在您的手裡。
The "unmanaged" purchase type is useful if you are selling consumable items, such as fuel or magic spells. These items are consumed within your application and are usually purchased multiple times.
如果您販賣的是消費型商品，像是燃料或者魔法法術，「不被管理」的商品類型就變得很有用了。這些商品都是在您APP裡的消耗型商品，而且通常會被購買多次。

Handling Refunds退費的處理

In-app billing does not allow users to send a refund request to Android Market. Refunds for in-app purchases must be directed to you (the application developer). You can then process the refund through your Google Checkout merchant account. When you do this, Android Market receives a refund notification from Google Checkout, and Android Market sends a refund message to your application. For more information, see Handling IN_APP_NOTIFY messages and In-app Billing Pricing.
iap機制不允許使用者發送退費請求至Android市集的。應用程式內商品的退費完完全全主導於您(APP的開發者)。您可以透過您的Google Checkout merchant帳戶來處理退費流程。當您執行了商品退費，Android市集就會接收到從Google Checkout傳來的退費通知，接著Android市集就會發送商品遭退費的訊息給使用者的APP。更多資訊請見 Handling IN_APP_NOTIFY messages和In-app Billing Pricing這兩篇。

Important: You cannot use the Google Checkout API to issue refunds or cancel in-app billing transactions. You must do this manually through your Google Checkout merchant account. However, you can use the Google Checkout API to retrieve order information.
重要︰您無法使用Google Checkout 的API來處理退費或取消iap交易。您必須以手動方式透過Google Checkout merchant帳戶來處理這些事。然而，您仍然可以使用Google Checkout API來接收訂單資訊。

Setting Up Test Accounts設定測試帳戶

The Android Market publisher site lets you set up one or more test accounts. A test account is a regular Google account that you register on the publisher site as a test account. Test accounts are authorized to make in-app purchases from applications that you have uploaded to the Android Market site but have not yet published.
Android市集發佈網站讓您可以設定一或多組的測試帳號。所謂的測試帳號就是一個標準的Google帳號，您只是將它註冊至發佈網站成為測試帳戶而已。測試帳戶是被驗証的，因此您才可以透過上傳卻未發佈的APP來做出iap購買請求。
You can use any Google account as a test account. Test accounts are useful if you want to let multiple people test in-app billing on applications without giving them access to your publisher account's sign-in credentials. If you want to own and control the test accounts, you can create the accounts yourself and distribute the credentials to your developers or testers.
您可以使用任何的Google帳戶來當測試帳戶。如果您想要讓多個人測試您APP的iap機制，而您不想要把您發佈網站的登入帳戶給他們來使用時，測試帳戶就變得很有用了。如果您想要自己擁有也控制測試帳戶，您可以自行建立帳戶，並且將這組帳戶設成開發者帳戶或測試者帳戶。

Test accounts have three limitations:
測試帳戶有底下的三種限制︰

Test account users can make purchase requests only within applications that are already uploaded to your publisher account (although the application doesn't need to be published).
Test accounts can only be used to purchase items that are listed (and published) in an application's product list.
Test account users do not have access to your publisher account and cannot upload applications to your publisher account.

To add test accounts to your publisher account, follow these steps:
新增測試帳戶至您的發佈帳戶裡，請照以下方式︰

登入

On the upper left part of the page, under your name, click Edit profile.

編輯個人資料

On the Edit Profile page, scroll down to the Licensing & In-app Billing panel (see figure 5).
In Test Accounts, add the email addresses for the test accounts you want to register, separating each account with a comma.
Click Save to save your profile changes.

儲存

Figure 5. The Licensing and In-app Billing panel of your account's Edit Profile page lets you register test accounts.
圖5. 這是您帳戶中編輯個人資料裡的授權和應用程式內結帳區塊，您可以在這裡註冊測試帳戶。

Where to Get Support在哪裡尋求支援

If you have questions or encounter problems while implementing in-app billing, contact the support resources listed in the following table (see table 2). By directing your queries to the correct forum, you can get the support you need more quickly.
如果您在實作iap機制時有問題或者遇到問題，可以聯絡表格中列出的支援的資源列表(見表2)。依您的需求尋求適合的論壇，您可以更快速地獲得您所需要的支援。

Table 2. Developer support resources for Android Market in-app billing.
表2. Android市集iap機制開發者支援的資源。

Support Type支援的型態	Resource資源	Range of Topics主題的範圍
Development and testing issues開發與測試問題	Google Groups: android-developers	In-app billing integration questions, user experience ideas, handling of responses, obfuscating code, IPC, test environment setup. iap機制的整合問題、使用者經驗發想、處理回應、模糊程式碼、內部進程溝通、測試環境的設定。
Development and testing issues開發與測試問題	Stack Overflow: http://stackoverflow.com/questions/tagged/ android
Market billing issue tracker市集金流問題追蹤	Market billing project issue tracker	Bug and issue reports related specifically to in-app billing sample code. 關於iap機制範例程式的BUG與問題回報

For general information about how to post to the groups listed above, see Developer Forums document in the Resources tab.
若想知道如何發文至上面的群組論壇的基本資訊，請見Android API裡Resources頁裡的Developer Forums 文章。

相關文章︰

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(中文翻譯)

小鰻的Android學習筆記

Friday, December 23, 2011

[Android in-app billing第5篇]Administering In-app Billing應用程式內金流機制的管理(中文翻譯)

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

In this document

Downloads

See also

Creating a Product List建立產品列表

Adding items one at a time to a product list同時間新增一件商品至產品列表

Adding a batch of items to a product list增加批量商品至產品列表

Choosing a Purchase Type選擇商品的購買型態

Handling Refunds退費的處理

Setting Up Test Accounts設定測試帳戶

Where to Get Support在哪裡尋求支援

No comments:

Friday, December 23, 2011

[Android in-app billing第5篇]Administering In-app Billing應用程式內金流機制的管理(中文翻譯)

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

In this document

Downloads

See also

Creating a Product List建立產品列表

Adding items one at a time to a product list同時間新增一件商品至產品列表

Adding a batch of items to a product list增加批量商品至產品列表

Choosing a Purchase Type選擇商品的購買型態

Handling Refunds退費的處理

Setting Up Test Accounts設定測試帳戶

Where to Get Support在哪裡尋求支援

No comments:

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