Google Play 计费之外的货币化后端集成指南

Google Play 开发者 API 现在包含了额外的功能,可以报告来自 替代计费外部优惠 系统的交易。本指南介绍了如何报告替代计费或外部优惠交易。

可能需要一些组件来处理来自您后端的应用内购买。要构建它们,您需要根据 配置 Google Play 开发者 API 中的说明设置您的后端集成。对于所有不特定于替代计费或外部优惠 API 的开发者后端功能,Google Play 计费系统文档 中的说明适用。

向 Google Play 报告新的外部交易

Externaltransactions API 集成以 **报告在支持的国家/地区 Google Play 计费系统之外发生的交易,包括从免费试用购买产生的 0 美元交易**。替代计费或外部优惠系统上的交易应仅在根据 替代计费外部优惠 计划允许的合格用户国家/地区启动和报告,否则 API 调用将被拒绝。这适用于所有交易,包括新购买、续订、充值、升级、降级和其他交易。

外部交易报告

您应在通过替代计费或外部优惠系统授权付款后,调用 Externaltransactions API 来报告外部交易。这适用于所有交易,包括首次收费、续订、退款和其他交易。所有交易都需要在交易发生后的 24 小时内报告。

每个外部交易都使用外部交易 ID 进行报告。对于循环购买(例如自动续订订阅),您需要在任何后续交易(包括退款)中将与循环购买中的首次交易相关的外部交易 ID 作为参数发送。这会记录该购买的一系列交易。当产品发生变化(例如升级或降级),或者当循环交易被取消或过期并且稍后再次购买相同产品时,您会发送一个新的外部交易 ID 用于购买。您不得将任何个人身份信息、专有信息或机密信息作为此外部交易 ID 的一部分包含在内。

报告新购买

每次在替代计费或外部优惠系统中成功进行新购买时,都需要调用 Externaltransactions API。对于这些新购买,您需要在后端提供与购买相关的 **唯一** externalTransactionId 作为查询参数。此 externalTransactionId 不能在同一应用程序的包 ID 中重复使用。

应用通过 UserChoiceBillingListenerAlternativeBillingOnlyReportingDetailsListenerExternalOfferReportingDetailsListener 回调接收到的 externalTransactionToken 也是一次性购买和循环购买(如订阅)中首次交易的请求主体的一部分。这两种情况都称为*初始交易*。在初始交易后,不再需要 externalTransactionToken,您可以通过提供新的唯一 externalTransactionId 来报告后续交易(如订阅续费)。有关如何报告后续交易的更多详细信息,请参阅 报告购买的后续交易

示例:

  1. 开发人员在他们的应用中配置和启用替代计费。
  2. 用户 1 位于韩国(支持的国家/地区),正在尝试以 12634.10KRW/月的价格购买 product1,并享受为期一个月的免费试用优惠。
  3. 应用使用 ProductDetails 启动购买流程,用于 product1 和用户选择的优惠。
  4. 用户 1 选择开发人员的替代计费系统。
  5. UserChoiceBillingListener 接收 my_token 作为 externalTransactionToken 的值。
  6. 然后,开发人员将相关信息发送到他们的后端(externalTransactionToken 值和正在购买的产品)。然后,他们启动替代计费系统中 product1 的购买流程。此交易在开发人员端分配了一个唯一的交易 ID,用于将其报告给 Google Play:123-456-789。即使用户正在享受免费试用,也需要此交易 ID。
  7. 在替代计费系统中完成购买交易后,开发人员将使用以下请求将交易报告给 Google Play。它最初被报告为零美元交易,因为用户获得了免费试用期。
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
"transactionTime" : "2022-02-22T12:45:00Z",
 "recurringTransaction" : {
   "externalTransactionToken": "my_token",
   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

如果您与居住在印度的用户进行交易,而印度的税收因其行政区域(如州或省)而异,那么请确保在 userTaxAddress 下包含该区域。有关适用行政区域的预定义字符串列表,请参阅 API 参考指南。

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "INR"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "INR"
 },
"transactionTime" : "2023-11-01T12:45:00Z",
 "recurringTransaction" : {
   "externalTransactionToken": "my_token",
   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   # Tax varies in India based on state, so include that information in
   # administrativeArea
   "regionCode": "IN"
   "administrativeArea": "KERALA"
 }
}

报告购买的后续交易

在某些情况下,同一外部购买会关联多个用户付款(例如,订阅续订或预付计划充值)。您可以使用 Externaltransactions 中的相同 API 报告这些后续交易。如 报告新的购买 中所述,externalTransactionToken 不需要用于后续交易。相反,每个续订或充值交易都将发送新的唯一 externalTransactionId 作为查询参数,并将初始交易的 ID 包含在 initialExternalTransactionId 字段中。

继续前面的示例

  1. 用户 1 的第一次续费发生在替代计费系统中。初始交易 ID 为 123-456-789
  2. 开发人员在 URL 查询参数中报告交易循环作为此新交易的外部交易 ID,同时在 initialExternalTransactionId 字段中引用初始交易的外部交易 ID。

示例请求:

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=abc-def-ghi

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "12634000000",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "1263000000",
   "currency": "KRW"
 },
"transactionTime" : "2022-02-22T12:45:00Z",
 "recurringTransaction" : {
   "initialExternalTransactionId": "123-456-789",

   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

报告升级或降级

当用户在替代计费系统中拥有订阅时,要报告升级或降级,请使用 Externaltransactions API 中的相同端点和功能,发送提供给应用用于升级或降级交易的 externalTransactionToken。这与 报告新的购买 类似。

从手动报告替代计费交易迁移

要迁移在您提供替代计费(未进行自动化报告)时开始的活动订阅,请使用 migratedTransactionProgram 字段创建一个新的零成本交易,而不是指定 initialExternalTransactionIdexternalTransactionToken。将 transactionTime 设置为用户最初注册每个活动订阅的时间。之后,通过 API 以正常方式报告这些订阅的每个后续交易,提供上面用于创建续订交易的 initialExternalTransactionId。一旦订阅迁移完成,您将不再需要手动报告订阅的后续交易,前提是这些交易通过本页面中描述的自动化方法进行报告。

在迁移订阅时,请注意 配额限制,以确保迁移不会导致配额不足。如果需要迁移大量订阅,请将它们分散到多个日期,或者 请求提高配额

migratedTransactionProgram 字段仅可在从手动报告迁移时使用。当不再支持手动报告时,它将被弃用。

示例请求:

# Note that the externalTransactionId specified here will used to report subsequent
# transactions.

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=abc-def-ghi

Body
 {
 # Be sure to set the price to 0 for this transaction since it does not reflect
 # an actual subscription renewal.
 "originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },

 # The transaction time should be set to when the user signed up for this
 # subscription.
 "transactionTime" : "2022-02-22T12:45:00Z",
  "recurringTransaction" : {
    "migratedTransactionProgram": "USER_CHOICE_BILLING",

    "externalSubscription" {
      "subscriptionType": "RECURRING"
    }
  },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

报告 Play 合作伙伴计划

参与合作伙伴计划(如 Play 媒体体验计划)的开发人员必须在报告外部交易时提供 transaction_program_code。如果您是合格的开发人员,请联系您的业务发展经理,以获取有关如何设置此字段的更多信息。

将购买退款报告给 Google Play

Externaltransactions API 集成,以报告在 Google Play 计费系统之外向用户退款的交易。为了使 Play 正确识别已退款的交易,您应将先前报告交易的相应 externalTransactionId 作为 URL 参数的一部分包括在内。

在报告订阅购买退款时,请引用正在退款的订阅的特定循环的 externalTransactionId

示例:假设订阅有以下交易

  • 外部交易 ID 为 ABC.1234-5678-9012-34567 的初始交易
  • 外部交易 ID 为 ABC.1234-5678-9012-34567..0 的第一次循环交易
  • 外部交易 ID 为 ABC.1234-5678-9012-34567..1 的第二次循环交易

要报告订阅的所有交易的退款,您需要进行三个单独的退款请求:一个用于初始交易,两个用于后续交易。

此方法接受 全额退款(金额与用户在原始外部交易中支付的金额相同)和 部分退款(金额小于用户在原始外部交易中支付的金额)。对于部分退款,您需要指定已退款的税前金额。

API 配额

Externaltransactions API 与 Google Play 开发者 API 中的任何其他端点一样,受 每日 API 配额 的约束。

此外,Externaltransactions API 对 Externaltransactions.createexternaltransactionExternaltransactions.refundexternaltransaction 的调用有每分钟 1200 次查询(QPM)的限制。对 Externaltransactions.getexternaltransaction 的调用不计入此 1200 QPM 限制。