实时开发者通知参考指南

本文档列出并描述了您可以从 Google Play 收到的 实时开发者通知的类型。

编码

发布到 Cloud Pub/Sub 主题的每条消息都包含一个以 base64 编码的数据字段。

{
  "message": {
    "attributes": {
      "key": "value"
    },
    "data": "eyAidmVyc2lvbiI6IHN0cmluZywgInBhY2thZ2VOYW1lIjogc3RyaW5nLCAiZXZlbnRUaW1lTWlsbGlzIjogbG9uZywgIm9uZVRpbWVQcm9kdWN0Tm90aWZpY2F0aW9uIjogT25lVGltZVByb2R1Y3ROb3RpZmljYXRpb24sICJzdWJzY3JpcHRpb25Ob3RpZmljYXRpb24iOiBTdWJzY3JpcHRpb25Ob3RpZmljYXRpb24sICJ0ZXN0Tm90aWZpY2F0aW9uIjogVGVzdE5vdGlmaWNhdGlvbiB9",
    "messageId": "136969346945"
  },
  "subscription": "projects/myproject/subscriptions/mysubscription"
}

对以 base64 编码的数据字段进行解码后，DeveloperNotification 包含以下字段：

{
  "version": string,
  "packageName": string,
  "eventTimeMillis": long,
  "oneTimeProductNotification": OneTimeProductNotification,
  "subscriptionNotification": SubscriptionNotification,
  "voidedPurchaseNotification": VoidedPurchaseNotification,
  "pendingRefundReviewNotification": PendingRefundReviewNotification,
  "testNotification": TestNotification
}

下表对这些字段进行了说明。

属性名称 值 说明
version string 此通知的版本。最初，此值为“1.0”。此版本与其他版本字段不同。
packageName string 与此通知相关的应用的软件包名称（例如“com.some.thing”）。
eventTimeMillis long 事件发生的时间戳，以从公元纪年开始计算的毫秒数表示。
subscriptionNotification SubscriptionNotification

如果此字段存在，则此通知与 订阅相关，并且此字段包含与订阅相关的其他信息。

请注意，此字段与 pendingRefundReviewNotification、oneTimeProductNotification、 voidedPurchaseNotification 和 testNotification 互斥。
oneTimeProductNotification OneTimeProductNotification

如果此字段存在，则此通知与单次购买相关，并且此字段包含与购买交易相关的其他信息。

请注意，此字段与 pendingRefundReviewNotification、subscriptionNotification、voidedPurchaseNotification 和 testNotification 互斥。
voidedPurchaseNotification VoidedPurchaseNotification

如果此字段存在，则此通知与作废的购买交易相关，并且此字段包含与作废的购买交易相关的其他信息。

请注意，此字段与 pendingRefundReviewNotification、oneTimeProductNotification、subscriptionNotification 和 testNotification 互斥。
pendingRefundReviewNotification PendingRefundReviewNotification

如果此字段存在，则此通知与您可建议解决方案的 退款请求相关。 如需响应此通知，请调用 `ReviewRefund` API。

请注意，此字段与 subscriptionNotification, oneTimeProductNotification, voidedPurchaseNotification, 和 testNotification 互斥。
testNotification TestNotification

如果此字段存在，则此通知与某个 测试发布相关。这些只通过 Google Play 管理中心 发送。

请注意，此字段与 pendingRefundReviewNotification、oneTimeProductNotification、 subscriptionNotification 和 voidedPurchaseNotification 互斥。

SubscriptionNotification

SubscriptionNotification 包含以下字段：

{
  "version": string,
  "notificationType": int,
  "purchaseToken": string
}
属性名称 值 说明
version string 此通知的版本。最初，此值为“1.0”。此版本与其他版本字段不同。
notificationType int 订阅的 notificationType 可以具有以下值：
  • (1) SUBSCRIPTION_RECOVERED - 从 账号保留状态恢复了订阅，或从暂停状态恢复了订阅。
  • (2) SUBSCRIPTION_RENEWED - 续订了处于活动状态的订阅。
  • (3) SUBSCRIPTION_CANCELED - 自愿或非自愿地取消了订阅。如果是自愿取消，在用户取消时发送。
  • (4) SUBSCRIPTION_PURCHASED - 购买了新的订阅。
  • (5) SUBSCRIPTION_ON_HOLD - 订阅已进入账号保留状态（如果已启用）。
  • (6) SUBSCRIPTION_IN_GRACE_PERIOD - 订阅已进入宽限期（如果已启用）。
  • (7) SUBSCRIPTION_RESTARTED - 用户已通过 Play > 账号 > 订阅恢复了订阅。订阅已取消，但在用户恢复时尚未到期。如需了解详情，请参阅 恢复。
  • (8) SUBSCRIPTION_PRICE_CHANGE_CONFIRMED（已废弃）- 用户已成功确认订阅价格变动。
  • (9) SUBSCRIPTION_DEFERRED - 订阅的续订时间点已 延期。
  • (10) SUBSCRIPTION_PAUSED - 订阅已暂停。
  • (11) SUBSCRIPTION_PAUSE_SCHEDULE_CHANGED - 订阅暂停计划已更改。
  • (12) SUBSCRIPTION_REVOKED - 用户在到期时间之前已撤消订阅。
  • (13) SUBSCRIPTION_EXPIRED - 订阅已到期。
  • (17) SUBSCRIPTION_ITEMS_CHANGED - 订阅包中的商品已更改。
  • (18) SUBSCRIPTION_CANCELLATION_SCHEDULED - 分期付款订阅的取消已安排在承诺期结束时生效。
  • (19) SUBSCRIPTION_PRICE_CHANGE_UPDATED - 订阅商品的价格 变动详情已更新。
  • (20) SUBSCRIPTION_PENDING_PURCHASE_CANCELED - 订阅的待处理交易 已取消。
  • (22) SUBSCRIPTION_PRICE_STEP_UP_CONSENT_UPDATED - 订阅的 价格上调同意期已开始，或者用户已同意价格 上调。此 RTDN 仅针对需要价格上调的区域中的订阅发送。
purchaseToken string 购买订阅时向用户设备提供的令牌。

示例

下面是新订阅购买的通知示例：

{
  "version":"1.0",
  "packageName":"com.some.thing",
  "eventTimeMillis":"1503349566168",
  "subscriptionNotification":
  {
    "version":"1.0",
    "notificationType":4,
    "purchaseToken":"PURCHASE_TOKEN"
  }
}

OneTimeProductNotification

OneTimeProductNotification 包含以下字段：

{
  "version": string,
  "notificationType": int,
  "purchaseToken": string,
  "sku": string
}
属性名称 值 说明
version string 此通知的版本。最初，此值为“1.0”。此版本与其他版本字段不同。
notificationType int 通知的类型。它可以具有以下值：
  • (1) ONE_TIME_PRODUCT_PURCHASED - 用户成功购买了一次性商品。
  • (2) ONE_TIME_PRODUCT_CANCELED - 用户已取消待处理的一次性商品购买交易。
purchaseToken string 购买时向用户设备提供的令牌。
sku string 购买的一次性商品的商品 ID（例如“sword_001”）。

示例

下面是一笔新的一次性购买交易的通知示例：

{
  "version":"1.0",
  "packageName":"com.some.thing",
  "eventTimeMillis":"1503349566168",
  "oneTimeProductNotification":
  {
    "version":"1.0",
    "notificationType":1,
    "purchaseToken":"PURCHASE_TOKEN",
    "sku":"my.sku"
  }
}

VoidedPurchaseNotification

VoidedPurchaseNotification 包含以下字段：

属性名称 值 说明

purchaseToken

string

与作废的购买交易关联的令牌。当有新的购买交易发生时，系统会向开发者提供此信息。

orderId

string

与作废的交易关联的唯一订单 ID。对于一次性购买，此字段代表了为这笔购买交易生成的唯一订单 ID。对于自动续订型订阅，系统会为每笔续订交易生成一个新的订单 ID。

productType

int

作废的购买交易的 productType 可以具有以下值：

  • (1) PRODUCT_TYPE_SUBSCRIPTION - 订阅购买交易已作废。
  • (2) PRODUCT_TYPE_ONE_TIME - 单次购买交易 已作废。

refundType

int

作废的购买交易的 refundType 可以具有以下值：

  • (1) REFUND_TYPE_FULL_REFUND - 购买交易已完全作废。
  • (2) REFUND_TYPE_QUANTITY_BASED_PARTIAL_REFUND - 购买交易已通过基于数量的部分退款而部分作废，仅适用于多件购买交易。购买交易可以 多次部分作废。

请注意，当多件购买交易的剩余总数量得到退款时，refundType 将为 REFUND_TYPE_FULL_REFUND。

示例

下面是一笔新的作废购买交易的通知示例：

{
  "version":"1.0",
  "packageName":"com.some.app",
  "eventTimeMillis":"1503349566168",
  "voidedPurchaseNotification":
  {
    "purchaseToken":"PURCHASE_TOKEN",
    "orderId":"GS.0000-0000-0000",
    "productType":1
    "refundType":1
  }
}

使用 VoidedPurchaseNotification

当您的 RTDN 客户端收到 VoidedPurchaseNotification 时，请注意以下信息：

  • packageName：用于标识应用。
  • eventTimeMillis：用于告知您状态更改发生的时间。
  • purchaseToken：购买商品时向用户设备提供的令牌。
  • orderId：用于标识与作废的交易相关联的订单。
  • productType：用于指明作废的购买交易是应用内购买还是订阅。
  • refundType：用于指定使购买交易作废的退款类型。

PendingRefundReviewNotification

当用户针对购买交易请求退款，且该请求需要开发者审核时，系统会发送 PendingRefundReviewNotification。收到此通知后，您应评估该请求，并在 24 小时内通过调用 ReviewRefund API 提供退款 建议和购买交易使用情况证据。

PendingRefundReviewNotification 包含以下字段：

{
  "version": string,
  "pendingRefundToken": string,
  "orderId": string,
  "refundReason": int,
  "obfuscatedAccountId": string,
  "obfuscatedProfileId": string
}
属性名称 值 说明
version string 此通知的版本。最初，此值为“1.0”。此版本与其他版本字段不同。
pendingRefundToken string 用于标识待审核退款请求的唯一令牌。调用 ReviewRefund API 时传递此令牌。
orderId string 待审核退款所涉及的购买交易的订单 ID。
refundReason int 退款请求的原因。待审核退款仅支持将 CHARGEBACK (7) 作为退款原因。您的代码应 在有新原因可用时对其进行处理。
obfuscatedAccountId string （如果适用）购买时提供的经过混淆处理的开发者指定的用户账号 ID。
obfuscatedProfileId string （如果适用）购买时提供的经过混淆处理的开发者指定的个人资料 ID。

示例

下面是待审核退款通知的示例：

{
  "version":"1.0",
  "packageName":"com.some.thing",
  "eventTimeMillis":"1503350156918",
  "pendingRefundReviewNotification":
  {
    "version":"1.0",
    "pendingRefundToken":"example-token",
    "orderId":"GPA.1234-5678-9012-34567",
    "refundReason":7,
    "obfuscatedAccountId":"user-account-id",
    "obfuscatedProfileId":"user-profile-id"
  }
}

TestNotification

TestNotification 包含以下字段：

{
  "version": string
}
属性名称 值 说明
version string 此通知的版本。最初，此值为“1.0”。此版本与其他版本字段不同。

示例

下面是测试通知的示例：

{
  "version":"1.0",
  "packageName":"com.some.thing",
  "eventTimeMillis":"1503350156918",
  "testNotification":
  {
    "version":"1.0"
  }
}