gplay-iap-setup

Google Play 应用内购买设置

需要为 Android 应用设置变现时，请使用此技能。

两种 API：旧版与新版变现

Google Play 为一次性商品提供了两种 API：

	旧版（gplay iap）	新版变现（gplay onetimeproducts）
API	inappproducts	monetization.onetimeproducts
价格格式	priceMicros/currency	units/nanos/currencyCode
结构	扁平的 prices 映射	包含 regionalPricingAndAvailabilityConfigs 的 purchaseOptions
状态	active/inactive	DRAFT → ACTIVE（需要显式激活）
区域定价	--auto-convert-prices 标志	必须指定 --regions-version

新建商品时，优先使用新版变现 API（gplay onetimeproducts）。它支持购买选项，能更好地控制区域定价，而且是目前积极开发的 API。

仅在管理现有旧版商品时使用旧版 API（gplay iap）。

同一商品绝不能混用这两种 API。 通过 gplay iap create 创建的商品无法通过 gplay onetimeproducts 管理，反之亦然。

重要：商品 ID 永久有效

Google Play 删除商品后仍会永久保留其商品 ID。 如果你创建了 premium_unlock，之后又将其删除，那么 premium_unlock 这个 ID 永远无法再次使用，即使换用另一种 API 也不行。请谨慎选择商品 ID。

这意味着：

• 不要使用好 ID 创建“测试”商品后再将其删除
• 不要通过旧版 API 创建商品后，再尝试通过新版 API 重新创建
• 如果某个 ID 已被占用，必须选择新 ID（例如 premium_unlock_v2）

一次性商品（新版变现 API）

列出商品

gplay onetimeproducts list --package com.example.app

创建商品

必须指定 --regions-version — create 命令在内部使用 PATCH 和 allowMissing=true：

gplay onetimeproducts create \
  --package com.example.app \
  --product-id premium_unlock \
  --json @product.json \
  --regions-version "2025/03"

product.json（新版变现格式）

{
  "productId": "premium_unlock",
  "listings": [
    { "languageCode": "en-US", "title": "Premium Unlock", "description": "Unlock all premium features" },
    { "languageCode": "es-ES", "title": "Desbloqueo Premium", "description": "Desbloquea todas las funciones premium" }
  ],
  "purchaseOptions": [
    {
      "buyOption": { "legacyCompatible": true },
      "newRegionsConfig": {
        "availability": "AVAILABLE",
        "usdPrice": { "currencyCode": "USD", "units": "9", "nanos": 990000000 },
        "eurPrice": { "currencyCode": "EUR", "units": "9", "nanos": 990000000 }
      },
      "regionalPricingAndAvailabilityConfigs": [
        { "regionCode": "US", "availability": "AVAILABLE", "price": { "currencyCode": "USD", "units": "9", "nanos": 990000000 } },
        { "regionCode": "GB", "availability": "AVAILABLE", "price": { "currencyCode": "GBP", "units": "7", "nanos": 990000000 } },
        { "regionCode": "IN", "availability": "AVAILABLE", "price": { "currencyCode": "INR", "units": "249", "nanos": 990000000 } }
      ]
    }
  ]
}

激活购买选项

新商品的初始状态为 DRAFT。必须先激活，用户才能购买：

gplay purchase-options batch-update-states \
  --package com.example.app \
  --product-id premium_unlock \
  --json '{"requests":[{"activatePurchaseOptionRequest":{"packageName":"com.example.app","productId":"premium_unlock","purchaseOptionId":"default"}}]}'

更新商品

gplay onetimeproducts patch \
  --package com.example.app \
  --product-id premium_unlock \
  --json @product-updated.json \
  --regions-version "2025/03" \
  --update-mask "purchaseOptions"

获取商品

gplay onetimeproducts get --package com.example.app --product-id premium_unlock

删除商品

gplay onetimeproducts delete \
  --package com.example.app \
  --product-id premium_unlock \
  --confirm

批量操作

# Get multiple products
gplay onetimeproducts batch-get \
  --package com.example.app \
  --product-ids "premium_unlock,coins_100"

# Update multiple products (regionsVersion goes inside JSON)
gplay onetimeproducts batch-update \
  --package com.example.app \
  --json @products-batch.json

旧版应用内商品（IAP）

仅用于管理现有旧版商品。

列出商品

gplay iap list --package com.example.app

创建商品

iap create 没有 --sku 标志 — SKU/productId 位于 JSON 请求体中：

gplay iap create \
  --package com.example.app \
  --json @product.json

product.json（旧版格式）

{
  "sku": "premium_upgrade",
  "status": "active",
  "purchaseType": "managedUser",
  "defaultPrice": {
    "priceMicros": "990000",
    "currency": "USD"
  },
  "prices": {
    "US": { "priceMicros": "990000", "currency": "USD" },
    "GB": { "priceMicros": "799000", "currency": "GBP" }
  },
  "listings": {
    "en-US": { "title": "Premium Upgrade", "description": "Unlock all premium features" },
    "es-ES": { "title": "Actualización Premium", "description": "Desbloquea todas las funciones premium" }
  }
}

更新 / 批量操作 / 删除

# Update
gplay iap update --package com.example.app --sku premium_upgrade --json @product-updated.json

# Batch update
gplay iap batch-update --package com.example.app --json @products.json

# Batch get
gplay iap batch-get --package com.example.app --skus "premium,coins_100,coins_500"

# Delete (permanent — ID cannot be reused)
gplay iap delete --package com.example.app --sku premium_upgrade --confirm

订阅

列出订阅

gplay subscriptions list --package com.example.app

创建订阅

gplay subscriptions create \
  --package com.example.app \
  --json @subscription.json

subscription.json

订阅使用 units/nanos/currencyCode 价格格式：

{
  "productId": "premium_monthly",
  "basePlans": [
    {
      "basePlanId": "monthly",
      "state": "ACTIVE",
      "regionalConfigs": [
        {
          "regionCode": "US",
          "newSubscriberAvailability": true,
          "price": { "currencyCode": "USD", "units": "4", "nanos": 990000000 }
        }
      ],
      "autoRenewingBasePlanType": {
        "billingPeriodDuration": "P1M"
      }
    },
    {
      "basePlanId": "yearly",
      "state": "ACTIVE",
      "regionalConfigs": [
        {
          "regionCode": "US",
          "newSubscriberAvailability": true,
          "price": { "currencyCode": "USD", "units": "49", "nanos": 990000000 }
        }
      ],
      "autoRenewingBasePlanType": {
        "billingPeriodDuration": "P1Y"
      }
    }
  ],
  "listings": [
    { "languageCode": "en-US", "title": "Premium Subscription", "description": "Get all premium features" }
  ]
}

批量本地化不同语言区域的订阅

订阅的 listings 是按语言区域排列的对象数组（而不是以语言区域为键的对象）。每个条目使用 languageCode、title、benefits（数组，最多 4 项）和 description。一次 subscriptions update 调用即可原子性地设置所有语言区域 — 使用 --update-mask listings，以保留基础方案和定价不变。

1. 查明应用已支持的语言区域（至少涵盖以下这些）：

EDIT_ID=$(gplay edits create --package com.example.app | jq -r '.id')
gplay listings list --package com.example.app --edit "$EDIT_ID" --output table

2. 创建仅包含 listings 的 JSON 文件（subscription-listings.json）：

{
  "listings": [
    { "languageCode": "en-US", "title": "Premium Monthly", "benefits": ["Unlimited access", "No ads"], "description": "Premium access to all features." },
    { "languageCode": "de-DE", "title": "Premium Monatlich", "benefits": ["Unbegrenzter Zugang", "Keine Werbung"], "description": "Premium-Zugang zu allen Funktionen." },
    { "languageCode": "es-ES", "title": "Premium Mensual", "benefits": ["Acceso ilimitado", "Sin anuncios"], "description": "Acceso premium a todas las funciones." },
    { "languageCode": "ja-JP", "title": "プレミアム月額", "benefits": ["無制限アクセス", "広告なし"], "description": "すべての機能にプレミアムアクセス。" }
  ]
}

3. 应用于一个订阅：

gplay subscriptions update \
  --package com.example.app \
  --product-id premium_monthly \
  --json @subscription-listings.json \
  --update-mask listings

4. 遍历应用中的每个订阅：

PACKAGE="com.example.app"
gplay subscriptions list --package "$PACKAGE" --paginate \
  | jq -r '.[].productId' \
  | while read -r PRODUCT_ID; do
      gplay subscriptions update \
        --package "$PACKAGE" \
        --product-id "$PRODUCT_ID" \
        --json @subscription-listings.json \
        --update-mask listings
    done

使用 gplay subscriptions get --package com.example.app --product-id premium_monthly --pretty 验证，并确认每个 languageCode 都出现在 listings 数组中。限制：title 最长 55 个字符，description 最长 80 个字符，benefits 最多 4 项。用户只提供一个显示名称时，所有语言区域均使用该名称；用户提供了各语言区域的翻译时，则分别使用对应语言区域的文本。

基础方案

基础方案定义订阅的计费周期和价格。

激活基础方案

gplay baseplans activate \
  --package com.example.app \
  --product-id premium_monthly \
  --base-plan-id monthly

停用基础方案

gplay baseplans deactivate \
  --package com.example.app \
  --product-id premium_monthly \
  --base-plan-id monthly

迁移价格

gplay baseplans migrate-prices \
  --package com.example.app \
  --product-id premium_monthly \
  --base-plan-id monthly \
  --json @migration.json

订阅优惠

优惠可提供折扣、免费试用或入门定价。

列出优惠

gplay offers list \
  --package com.example.app \
  --product-id premium_monthly \
  --base-plan-id monthly

创建优惠

gplay offers create \
  --package com.example.app \
  --product-id premium_monthly \
  --base-plan-id monthly \
  --json @offer.json

offer.json（免费试用）

{
  "offerId": "trial_7day",
  "state": "ACTIVE",
  "phases": [
    {
      "duration": "P7D",
      "pricingType": "FREE_TRIAL"
    }
  ],
  "regionalConfigs": [
    {
      "regionCode": "US"
    }
  ]
}

offer.json（入门价格）

{
  "offerId": "intro_50_off",
  "state": "ACTIVE",
  "phases": [
    {
      "duration": "P1M",
      "pricingType": "SINGLE_PAYMENT",
      "price": {
        "priceMicros": "2490000",
        "currency": "USD"
      }
    }
  ]
}

启用/停用优惠

# Activate
gplay offers activate \
  --package com.example.app \
  --product-id premium_monthly \
  --base-plan-id monthly \
  --offer-id trial_7day

# Deactivate
gplay offers deactivate \
  --package com.example.app \
  --product-id premium_monthly \
  --base-plan-id monthly \
  --offer-id trial_7day

一次性购买选项优惠

管理一次性产品购买选项的优惠：

# List offers
gplay otp-offers list --package com.example.app --product-id premium_unlock --purchase-option-id default

# Activate offer
gplay otp-offers activate --package com.example.app --product-id premium_unlock --purchase-option-id default --offer-id promo_50off

# Deactivate offer
gplay otp-offers deactivate --package com.example.app --product-id premium_unlock --purchase-option-id default --offer-id promo_50off

区域定价

转换价格

gplay pricing convert \
  --package com.example.app \
  --json @price-request.json

price-request.json（ConvertRegionPricesRequest）

请求正文是一个 Money 格式的基础 price——units 是以字符串表示的整货币金额，nanos 是小数部分（990000000 = .99）：

{
  "price": {
    "currencyCode": "USD",
    "units": "9",
    "nanos": 990000000
  }
}

响应会返回所有受支持区域的转换后价格，以及一个 regionVersion，可将其作为 --regions-version 传递给订阅、基础方案、优惠和一次性产品命令。

常见变现模式

模式 1：新建一次性产品（推荐）

# 1. Create product
gplay onetimeproducts create \
  --package com.example.app \
  --product-id premium_unlock \
  --json @premium.json \
  --regions-version "2025/03"

# 2. Activate purchase option
gplay purchase-options batch-update-states \
  --package com.example.app \
  --product-id premium_unlock \
  --json '{"requests":[{"activatePurchaseOptionRequest":{"packageName":"com.example.app","productId":"premium_unlock","purchaseOptionId":"default"}}]}'

# 3. Verify
gplay onetimeproducts get --package com.example.app --product-id premium_unlock

模式 2：带免费试用的订阅

# 1. Create subscription
gplay subscriptions create \
  --package com.example.app \
  --json @sub.json

# 2. Create free trial offer
gplay offers create \
  --package com.example.app \
  --product-id premium \
  --base-plan-id monthly \
  --json @trial.json

模式 3：多层级订阅

{
  "productId": "premium",
  "basePlans": [
    {
      "basePlanId": "basic_monthly",
      "regionalConfigs": [{ "regionCode": "US", "newSubscriberAvailability": true, "price": { "currencyCode": "USD", "units": "2", "nanos": 990000000 } }],
      "autoRenewingBasePlanType": { "billingPeriodDuration": "P1M" }
    },
    {
      "basePlanId": "premium_monthly",
      "regionalConfigs": [{ "regionCode": "US", "newSubscriberAvailability": true, "price": { "currencyCode": "USD", "units": "4", "nanos": 990000000 } }],
      "autoRenewingBasePlanType": { "billingPeriodDuration": "P1M" }
    },
    {
      "basePlanId": "premium_yearly",
      "regionalConfigs": [{ "regionCode": "US", "newSubscriberAvailability": true, "price": { "currencyCode": "USD", "units": "49", "nanos": 990000000 } }],
      "autoRenewingBasePlanType": { "billingPeriodDuration": "P1Y" }
    }
  ]
}

测试

使用测试购买

在应用代码中，使用测试产品 ID：

• android.test.purchased
• android.test.canceled
• android.test.refunded
• android.test.item_unavailable

许可测试

在 Play Console 中添加测试账号： 设置 → 许可测试 → 添加许可测试人员

最佳实践

1. 使用清晰的产品 ID - 例如，使用 premium_monthly，而不是 prod_001。ID 是永久的，删除后无法再次使用。
2. 优先使用新版变现 API - 对于新产品，使用 gplay onetimeproducts，而不是 gplay iap。
3. 本地化说明 - 为所有受支持的语言提供商品详情。
4. 设置区域定价 - 使用 PPP 定价（参见 gplay-ppp-pricing 技能），而不是在所有地区设置相同价格。
5. 创建后启用 - 新的 OTP 产品默认处于 DRAFT 状态。使用 gplay purchase-options batch-update-states 启用。
6. 查找命令 - 运行 gplay --help 查看所有命令组。购买选项管理位于 gplay purchase-options 下，而非 gplay onetimeproducts 下。
7. 全面测试 - 使用测试账号和测试产品 ID。
8. 监控转化率 - 跟踪哪些产品/优惠表现最佳。
9. 谨慎调整价格 - 价格变更会影响现有订阅者。

计费周期

• P1W - 1 周
• P1M - 1 个月
• P3M - 3 个月
• P6M - 6 个月
• P1Y - 1 年