From 197226e4a5a4dca305fbdad52965dfea290b9ed6 Mon Sep 17 00:00:00 2001 From: Kevin Hufnagle Date: Wed, 25 May 2016 13:01:30 -0700 Subject: [PATCH] cherry-pick from mnc-io-docs: docs: Updated descriptions for CSV file settings within IAB. The section titled "Adding a batch of items to a product list," found within the "Administering In-app Billing" page on the DAC site, now contains up-to-date descriptions of the different settings within the CSV files used with product lists within the Google Play Developer Console. Bug: 28767053 Change-Id: I578aaacdaa866d9fbac8a087f22eb1c3617437ba --- docs/html/google/play/billing/billing_admin.jd | 630 +++++++++++++++---------- 1 file changed, 389 insertions(+), 241 deletions(-) diff --git a/docs/html/google/play/billing/billing_admin.jd b/docs/html/google/play/billing/billing_admin.jd index ad09f1f53b40..9936489d7d45 100644 --- a/docs/html/google/play/billing/billing_admin.jd +++ b/docs/html/google/play/billing/billing_admin.jd @@ -51,9 +51,9 @@ apps. You can sell an item using Google Play's in-app billing feature only if th listed on an app's product list. Each app has its own product list; you cannot sell items that appear on another app's product list.

-

You can access an app's product list by opening the In-app Products +

You can access an app's product list by opening the In-app Products page for an app that is listed in your developer account. The link to the -In-app Products page appears only if you have a Google payments merchant +In-app Products page appears only if you have a Google payments merchant account and the app's manifest includes the com.android.vending.BILLING permission. For more information about this permission, see @@ -73,7 +73,7 @@ uploading an unpublished draft version. This functionality is no longer supported; instead, you must publish it to the alpha or beta distribution channel. For more information, see Draft Apps -are No Longer Supported. +are No Longer Supported.

In addition, an app package can have only one product list. If you create a product list for an app, and you use the -

You can add items to a product list two ways: you can add items one at a time on the In-app -Products page, or you can add a batch of items by importing the items from a +

You can add items to a product list two ways: you can add items one at a time on the In-app +Products page, or you can add a batch of items by importing the items from a comma-separated values (CSV) file. Adding items one at a time is useful if your app 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 app has a large @@ -100,14 +100,14 @@ number of in-app items.

  1. Log in to your publisher account.
    2. -
  2. In the All applications panel, click on the - app name, then open the In-app Products page.
    3. +
  3. In the All applications panel, click on the + app name, then open the In-app Products page.

  4. Click Add new product. After you provide the product type and ID for the item you are selling, click Continue.

    Product Type
    -

    The product type can be Managed product or Subscription. You cannot +

    The product type can be "Managed product" or "Subscription." You cannot change an item's product type after you create the item. For more information, see Choosing a Product Type.

    Note: For subscription items, you cannot change the @@ -169,7 +169,7 @@ number of in-app items.

    You can also change prices for other currencies manually, but you can do this only if a currency is used in one of the target countries for your app. You can specify target countries for your app on the - Pricing & Distribution page in the Google Play + Pricing & Distribution page in the Google Play Developer Console.

    @@ -187,266 +187,412 @@ number of in-app items.

    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). +

    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 options that you set when adding in-app products to a product list using the +Google Play Developer Console UI. For more information about using this UI, see +Adding items one at a time to a product list. -

    If you are importing and exporting CSV files with in-app products, keep -country-specific pricing in mind. If you use auto-fill, you can provide a -tax-exclusive default price, and tax-inclusive prices will be auto-filled. If you -do not use auto-fill, prices you provide must include tax.

    +

    Note: Batch upload of in-app product lists +containing subscriptions is not supported. Also, when updating existing items in +a batch upload, you cannot include changes to in-app products that are linked to +a pricing template.

    -

    Note: Batch upload of product lists containing -subscriptions is not supported. Also, when updating existing items in a batch -upload, you cannot include changes to in-app products that are linked to a -pricing template.

    - -

    To import the items that are specified in your CSV file, do the following:

    +

    To import the in-app products that are specified in your CSV file, do the +following:

      -
    1. Log in to your publisher account.
      2. -
    2. In the All applications panel, select the app - name, then open the In-app Products page.
      3. -
    3. On the In-app Products List page, click Import/Export - > Import in-app products from CSV file, then select your - CSV file. -

      The CSV file must be on your local computer or on a local disk that is connected to your - computer.

      -
      4. -
    4. 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 doesn't delete items that are on a product list but not present in the CSV - file.

      +
    5. + Log in to your + publisher account. +
      6. +
    6. In the All applications panel, select the app + name, then open the In-app Products page.
      7. +
    7. +

      On the In-app Products page, click + Import/Export > Import in-app products from CSV + file to open the Import In-app Products dialog.

      +
      8. +
    8. +

      + If you want to overwrite existing in-app products in your product list + during the import process, select the Overwrite existing + products checkbox. +

      +

      + 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 in-app product in the product list. The overwriting process + doesn't delete in-app products that exist in a product list but aren't + included in the CSV file +

      +

      Note: If you choose not to overwrite + existing items, the Product ID given to each item in the CSV + file must be different from any of the Product ID values + assigned to existing in-app products. +

      +
      9. +
    9. + Select Browse files, then choose the CSV file that contains + the items you want to import. The CSV file must be stored locally.
    -

    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.

    +

    + You can also export an existing product list to a CSV file by clicking + Import/Export > Export in-app products to CSV file + on the In-app Products page. This is useful if you have + used the UI to add in-app products to your app but you want to start managing + the product list through a CSV file instead. +

    Formatting batches of items

    -

    The CSV file uses commas (,) and semicolons (;) to separate data values. -Commas are used to separate primary data values, and semicolons are used to -separate subvalues. For example, the syntax for the CSV file is as follows:

    +

    + The CSV file uses commas (,) and semicolons (;) to + separate data values. Commas are used to separate primary data values, and + semicolons are used to separate subvalues. Each item must appear entirely on a + single line within the CSV file. +

    +

    + When creating a CSV file that represents a list of items, you must specify the + CSV syntax on the first row, followed by the items themselves on subsequent + rows, as shown in the following example: +

    + +
    +Product ID,Published State,Purchase Type,Auto Translate,Locale; Title; Description,Auto Fill Prices,Price,Pricing Template ID
+basic_sleeping_potion,published,managed_by_android,false,en_US; Basic Sleeping Potion; Puts small creatures to sleep.; es_ES; Poción básica de dormir; Causa las criaturas pequeñas ir a dormir.,false,,4637138456024710495
+standard_sleeping_potion,published,managed_by_android,false,en_US; Standard Sleeping Potion; Puts all creatures to sleep for 2 minutes.,true, 1990000,
+invisibility_potion,published,managed_by_android,false,en_US; Invisibility Potion; Invisible to all enemies for 5 minutes.,false, US; 1990000; BR; 6990000; RU; 129000000; IN; 130000000; ID; 27000000000; MX; 37000000;
+
    -

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

    + This example contains details for three items, each of which represents an + in-app product:

    +
      +
    • + The first item defines a title and description for the en_US + and es_ES locales. A pricing template defines the item's + price. +
      • +
    • + The second item doesn't use a pricing template. Instead, it specifies a + price for the default country (US). The Google Play Developer Console + uses current exchange rates and locally relevant pricing patterns to + automatically set the prices in all other countries where the app is + distributed. +
      • +
    • + The third item also doesn't use a pricing template. The item's price is + specified manually for each country where the app is distributed. +
      • +
    -

    Descriptions and usage details are provided below.

    +

    + Each row in a CSV file can contain the following values, though at least one + of these values is undefined in each row: +

    -
    product_id
    +
    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. +

    + Setting this value in the CSV file has the same effect as entering a + Product ID when creating a new in-app product. +

    +

    + If you specify a Product ID assigned to an in-app product that already + exists in a product list, and you've checked the Overwrite + existing products checkbox in the Import In-app Products + dialog, the data for the existing in-app product is overwritten with the + values that you specify in the CSV file. +

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

    + This value must be set to published + or unpublished. +

    +

    + Setting this value to published has the same effect as + navigating to an item's Managed Product Details page and choosing + Active in the drop-down list next to the in-app product's + title and product ID. Setting the value to unpublished + has the same effect as choosing Inactive in the same + drop-down list. +

    -
    purchase_type
    +
    Purchase Type
    - This is equivalent to the Product 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. +

    + This value must be set to managed_by_android because batch + upload of product lists containing subscriptions is not supported. +

    +

    + Setting this value to managed_by_android has the same effect + as selecting Managed product in the Add New + Product dialog when creating an in-app product. +

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

    + This value must be set to false because auto-translation of + in-app product details isn't supported. +

    +

    + If you want to provide translations of an in-app product's title and + description, you need to specify these translations explicitly within the + Locale value. +

    -
    locale
    +
    Locale, Title, and Description
    -

    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:

    -
      +

      + If you include only one locale for an item, you must specify your app's + default locale and the item's default title and description: +

      + +
      +app_default_locale; item_default_title; item_default_description;
+
      + +

      + Setting these values has the same effect as performing the following + sequence of actions: +

      +
      1. -

        If 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, ..."

        + Choosing a default language when you add a new app to your + publisher account.
      2. -

        If 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; ..."

        + Navigating to an in-app product's Managed Product Details page.
        3. -
    -

    See table 1 for a list of the language codes you can use with the locale field.

    -
    -
    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, \;). Also, a backslash - must 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, \;). Also, a backslash - must be escaped with a backslash (for example, \\). +
  5. + Specifying the in-app product's default title and description. +
    6. +
+

+ When setting the Locale value, you can use any of the + language codes that appear within the Add Your Own Translations + dialog. You can access this dialog by navigating to an in-app product's + Managed Product Details page and clicking Add + translations or Manage translations. +

+

+ Note: When specifying the Title and + Description values, use backslashes to escape the semicolon + (\;) and backslash (\\) characters. +

+

+ If you want to include translated versions of the item's title and + description, you must list the default locale, title, and description, + followed by the locales, titles, and descriptions for each translation. + In the following example, the in-app product uses en_US + (United States English) as the default locale and es_ES + (Spain Spanish) as a translation: +

+
+en_US; Invisibility Cloak; Makes you invisible.; es_ES; Capote Invisible; Se vuelven invisible.
+
+

+ Note: An app contains a single default language, but each + in-app product maintains its own list of translations. Therefore, although + the first locale in each item's Locale value must be the same + throughout the CSV file, the other locales can differ from one item to + another. +

+

+ Providing values for multiple translations has the same effect as + performing the following sequence of actions: +

+
    +
  1. + Navigating to an in-app product's Managed Product Details page. +
    2. +
  2. + Clicking Add translations. +
    3. +
  3. + Selecting the languages for the translations and clicking + Add. +
    4. +
  4. + Choosing one of the languages you added in the previous step. +
    5. +
  5. + Specifying a new title and description, which serve as translations into + the selected language. +
    6. +
  6. + Repeating steps 4 and 5 to add translations into all other non-default + languages. +
    7. +
-
autofill
+
Auto Fill Prices, Country, and + Price
-

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:

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

- If you use this value, you shouldn't specify a value for the pricing_template_id. + ...you'd set the values of Auto Fill Prices and + Price at the end of a row in the CSV file as follows: +

+ +
+true,1990000,
+
+ +
Not using auto-filled prices
+

+ If you set Auto Fill Prices to false instead, + you specify a series of Country and Price + values for all countries where you distribute your app, including the country corresponding to your app's default locale. + Each Country value is the two-letter uppercase ISO country + code that represents a country where your app is distributed. +

+

+ Note: You must provide a country code and price for each + country that your app is targeting. To view and edit the list of countries + that your app targets, open your app's Pricing & Distribution + page.

- 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. + Each Price value represents the cost of the item in + micro-units of the currency used in that country. Setting Auto Fill + Prices to false has the same effect as performing + the following sequence of actions:

+
    +
  1. + Navigating to an in-app product's Managed Product Details page. +
    2. +
  2. + Selecting Edit in the Price section. +
    3. +
  3. + Explicitly setting tax-inclusive prices for different countries in the + Edit Local Prices dialog that appears. +
    4. +
  4. + Selecting Apply. +
    5. +
+

+ For example, if you're offering your app for the following prices (all + taxes included) in other countries: +

+ +

+ ...you'd set the values of Auto Fill Prices, + Country, and Price at the end of a row in the + CSV file as follows: +

+ +
+false, BR; 6990000; RU; 129000000; IN; 130000000; ID; 27000000000; MX; 37000000;
+
+
-
pricing_template_id
+
Pricing Template ID

- If you use this value, you should set autofill to - false and leave the price column empty. + If an item is linked to a pricing template, you should set Auto Fill + Prices to false, and you shouldn't set a value for the + Price column. If the item isn't linked to a pricing template, + you shouldn't set a value for the Pricing Template ID; instead, + you should set Auto Fill Prices, Country, and + Price based on how you want to set the in-app product's prices.

- This value represents the ID of the pricing template that you've linked to - the in-app product. This ID appears under a pricing template's name - on the Pricing template page. If an in-app product isn't - linked to a pricing template, its pricing_template_id value is - empty. + Setting this value has the same effect as navigating to an in-app product's + Managed Product Details page and linking the product's price to the + pricing template that has the same pricing template ID as the one specified + in the CSV file. This pricing template ID appears underneath a pricing + template's name on the Pricing template page.

- If you import a CSV file and choose to overwrite the product list, you can - update the links between in-app products and pricing templates by changing - the value of an in-app product's pricing_template_id. Leave the - value empty to unlink an in-app product from all pricing templates. + If you import a CSV file, and you've checked the Overwrite existing + products checkbox in the Import In-app Products dialog, + you can update the links between in-app products and pricing templates. To + link the product to a specific pricing template, set the Pricing + Template ID value to that pricing template's ID. To unlink an in-app + product from all pricing templates, don't set a value for its Pricing + Template ID.

- Note: You can link up to 100 app prices or in-app product - prices with a particular pricing template. Therefore, don't specify the same - pricing_template_id value in more than 100 rows of your CSV file. + You can link up to 100 app prices or in-app product prices to a particular + pricing template. Therefore, don't specify the same Pricing Template + ID value in more than 100 rows of a CSV file.

-

Table 1. Language codes you can use -with the locale field.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
LanguageCodeLanguageCode
Chinesezh_TWItalianit_IT
Czechcs_CZJapaneseja_JP
Danishda_DKKoreanko_KR
Dutchnl_NLNorwegianno_NO
Englishen_USPolishpl_PL
Frenchfr_FRPortuguesept_PT
Finnishfi_FIRussianru_RU
Germande_DESpanishes_ES
Hebrewiw_ILSwedishsv_SE
Hindihi_IN----
-

Pricing Templates

@@ -466,7 +612,8 @@ with the locale field.

can apply to paid apps and in-app products. You can link the prices of up to 100 apps and in-app products to a single pricing template.

-

+ +

To add a pricing template, do the following:

@@ -476,14 +623,14 @@ with the locale field.

account. -
  • In the Settings panel, open the Pricing - template page. +
  • In the Settings panel, open the Pricing + template page.

  • - If you are adding your first pricing template, the Add a Pricing - Template banner appears. Select Add template to + If you are adding your first pricing template, the Add a Pricing + Template banner appears. Select Add template to create a new template. The new template's Pricing tab appears.

    @@ -544,8 +691,8 @@ with the locale field.

    account.
    • -
  • In the Settings panel, open the Pricing - template page. This page shows the list of pricing templates you have +
  • In the Settings panel, open the Pricing + template page. This page shows the list of pricing templates you have created for your account.
    • @@ -605,8 +752,8 @@ with the locale field.

    account. -
  • In the All applications panel, select the app name, then - open the In-app Products page. +
  • In the All applications panel, select the app name, then + open the In-app Products page.
  • Choose the in-app product that you want to link to a pricing template. @@ -625,7 +772,7 @@ with the locale field.

    To link the price of a paid app to a pricing template, you follow a similar - process on the app's Pricing & Distribution page. + process on the app's Pricing & Distribution page.

    @@ -657,7 +804,7 @@ with the locale field.

  • Select the app that contains the in-app product you want to delete.
    • -
  • Open the app's In-app Products page. +
  • Open the app's In-app Products page.
  • Choose the in-app product that you want to delete. @@ -731,8 +878,8 @@ with the locale field.

    account.
    • -
  • In the Settings panel, open the Pricing - template page, which shows the list of pricing templates you have +
  • In the Settings panel, open the Pricing + template page, which shows the list of pricing templates you have created for your account.
    • @@ -746,15 +893,15 @@ with the locale field.

    • -

    Choosing a Product Type

    +

    Choosing a Product Type

    An item's product type controls how Google Play manages the purchase of the item. The supported product types include "managed product" and "subscription." Since support for different product types can vary among versions of the In-app Billing API, make sure that you choose a product -type that's valid for the version of the In-app Billing API that your app uses.

    +type that's valid for the version of the In-app Billing API that your app uses.

    For details, refer to the documentation for the In-app Billing API. +href="{@docRoot}google/play/billing/api.html#producttype">In-app Billing API.

    Handling Refunds

    @@ -782,9 +929,10 @@ you at the conclusion of the purchase flow, as the value of the intent.

    - Note: Test purchases don't have an orderId - field. To track test transactions, you use the purchaseToken - field instead. For more information about working with test purchases, see Note: When a user completes a test purchase, the + orderId field remains blank. To track test transactions, use + the purchaseToken field instead. For more information about + working with test purchases, see Testing In-app Billing.

    @@ -799,14 +947,14 @@ assigned and managed by Google.

    For transactions dated 5 December 2012 or later, Google payments assigns a Merchant Order Number (rather than a Google Order Number) and reports the Merchant -Order Number as the value of orderId. Here's an +Order Number as the value of orderID. Here's an example:

    "orderId" : "GPA.1234-5678-9012-34567"

    For transactions dated previous to 5 December 2012, Google checkout assigned a Google Order Number and reported that number as the value of -orderId. Here's an example of an orderId holding a +orderID. Here's an example of an orderID holding a Google Order Number:

    "orderId" : "556515565155651"
    @@ -853,8 +1001,8 @@ app.

    To locate the key for an app, follow these steps:

      -
    1. Open the All applications panel.
      2. -
    2. Click on the app name, then open the Services & APIs +
    3. Open the All applications panel.
      4. +
    4. Click on the app name, then open the Services & APIs page.
    5. Scroll down to the section of the page labeled Your License Key for This Application, as shown in figure 5.
      6. @@ -869,7 +1017,7 @@ for apps that depend on the (former) developer key.

      width="700" alt="">
      Figure 5. You can find the license key for each app on the - Services & APIs page. + Services & APIs page.
      -- 2.11.0