实时开发者通知参考指南

本主题列出并描述了您可以从 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,
  "testNotification": TestNotification
}

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

属性名称 说明
version string 此通知的版本。最初,此值为“1.0”。此版本与其他版本字段不同。
packageName string 与此通知相关的应用的软件包名称(例如“com.some.thing”)。
eventTimeMillis long 事件发生的时间戳,以从公元纪年开始计算的毫秒数表示。
subscriptionNotification SubscriptionNotification 如果此字段存在,则此通知与订阅相关,并且此字段包含与订阅相关的其他信息。请注意,此字段与 oneTimeProductNotification、voidedPurchaseNotification 和 testNotification 互斥。
oneTimeProductNotification OneTimeProductNotification 如果此字段存在,则此通知与一次性购买相关,并且此字段包含与购买交易相关的其他信息。请注意,此字段与 subscriptionNotification、voidedPurchaseNotification 和 testNotification 互斥。
voidedPurchaseNotification VoidedPurchaseNotification 如果此字段存在,则此通知与作废的购买交易相关,并且此字段包含与作废的购买交易相关的其他信息。请注意,此字段与 oneTimeProductNotification、subscriptionNotification 和 testNotification 互斥。
testNotification TestNotification 如果此字段存在,则此通知与测试发布相关。这些只通过 Google Play 管理中心发送。请注意,此字段与 oneTimeProductNotification、subscriptionNotification 和 voidedPurchaseNotification 互斥。

SubscriptionNotification

SubscriptionNotification 包含以下字段:

{
  "version": string,
  "notificationType": int,
  "purchaseToken": string,
  "subscriptionId": 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 - 订阅已到期。
  • (20) SUBSCRIPTION_PENDING_PURCHASE_CANCELED - 待处理的交易 项订阅已取消。
purchaseToken string 购买订阅时向用户设备提供的令牌。
subscriptionId string 所购买订阅的商品 ID(例如“monthly001”)。

示例

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

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

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 - 购买交易因基于数量的部分退款而部分作废; 仅适用于多件购买。购买交易可以是 多次部分作废。

请注意,多件购买交易的剩余总数为 已退款,refundTypeREFUND_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:用于指明导致购买交易作废的退款类型。

如果您只需找到正确的购买交易和订单就能调整所有权,那么此时您已有了所需的全部信息。如需了解如何获取与作废的购买交易相关的更多信息,请参阅 Google Play Voided Purchases API 文档;此 API 是一个提取模型,旨在提供给定时间戳之间产生的已作废购买交易的额外数据。

对于部分作废的多件购买交易,refundableQuantity 字段 (由 purchases.products 提供)包含剩余的 未作废的已购产品数。

TestNotification

TestNotification 包含以下字段:

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

示例

下面是测试通知的示例:

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