添加实时开发者通知

概览

Google Play 结算服务提供服务器推送通知,让您可以监控受 Play 管理的订阅项目的状态变化。启用实时开发者通知后,只要现有订阅项目有更新,您就会直接从 Cloud Pub/Sub 收到购买令牌。

实时开发者通知并不提供与订阅项目状态有关的完整信息,例如用户目前是否有权访问订阅内容。收到令牌后,您应该始终使用购买令牌查询 Google Play Developer API,以获取完整信息,并根据用户当前的权限状态更新后端。

通知类型未来可能会发生变化。您应该能够处理无法识别的通知类型,并且您应该始终依赖 Google Play Developer API 来处理关键业务逻辑。

要启用此功能,请执行以下操作:

  1. 使用您自己的 Google Cloud Platform (GCP) 项目设置 Cloud Pub/Sub
  2. 为您的 Android 应用启用实时开发者通知。

设置 Cloud Pub/Sub

Cloud Pub/Sub 是一种完全托管式的实时消息传递服务,允许您在独立应用之间收发消息。它提供低延迟且持久的消息传递功能,可以帮助您快速集成托管在 Google Cloud Platform 以及外部的系统。

Google Play 结算服务使用 Cloud Pub/Sub 发布与您订阅的主题相关的推送通知。

满足前提条件

要使用 Cloud Pub/Sub,您必须在 Google Cloud Platform (GCP) 上拥有一个项目,并启用 Cloud Pub/Sub API。如果您不熟悉 GCP 和 Cloud Pub/Sub,请参阅快速入门指南

要接收推送通知,您必须创建安全的后端服务器以使用发送到您主题的消息。您的服务器可以使用 Cloud Pub/Sub 客户端库来使用这些消息。

创建主题

要开始接收通知,您需要创建一个主题,以便 Google Play 结算服务向其发布通知。要创建主题,请执行以下操作:

  1. 阅读创建主题中的说明。
  2. 使用 Google Cloud Platform Console 创建主题。

创建 Pub/Sub 订阅项目

要接收发布到主题的消息,您必须针对该主题创建 Pub/Sub 订阅项目。要创建 Pub/Sub 订阅项目,请执行以下操作:

  1. 阅读 Cloud Pub/Sub 订阅者指南,以确定是将订阅项目配置为“推送订阅”还是“提取订阅”。提取订阅要求您的安全后端服务器向 Cloud Pub/Sub 服务器发起请求以检索消息。推送订阅要求 Cloud Pub/Sub 向您的安全后端服务器发起请求以传递消息。
  2. 阅读添加订阅中的说明。
  3. 使用 Google Cloud Platform Console 创建订阅项目。

针对您的主题授予发布权限

Cloud Pub/Sub 要求您按照以下步骤授予 Google Play 结算服务向您的主题发布通知的权限:

  1. 打开 Google Cloud Console
  2. 选择您的项目,然后在左侧导航栏中点击 Pub/Sub
  3. 找到您的主题,然后打开权限详细信息。
    图 1. 访问主题的“权限”配置。
  4. 添加服务帐号 google-play-developer-notifications@system.gserviceaccount.com,然后授予其 Pub/Sub 发布商的角色。
    图 2. 将 Google Play 服务帐号添加为 Pub/Sub 发布商。
  5. 保存以完成主题设置。
    图 3. 主题配置完成。

为您的应用启用实时开发者通知

要为您的应用启用实时开发者通知,请执行以下操作:

  1. 打开 Google Play 管理中心
  2. 选择您的 Android 应用。
  3. 依次转到开发工具 > 服务和 API 页面。
  4. 滚动到页面底部的实时开发者通知部分。

    图 4. “实时开发者通知”部分。

  5. 主题名称字段中,输入您之前配置的完整 Cloud Pub/Sub 主题名称。主题名称应采用 projects/{project_id}/topics/{topic_name} 格式,其中 project_id 是项目的唯一标识符,topic_name 是之前创建的主题的名称。

  6. 点击发送测试消息以发送测试消息。进行发布测试有助于确保一切均已正确设置和配置。如果测试消息发布成功,则系统会显示一条消息,表明测试发布已成功。如果您针对该主题运行了订阅者,则该订阅者应该会收到此测试消息。

    如果发布失败,则系统会显示错误。请确保主题名称正确,并且 google-play-developer-notifications@system.gserviceaccount.com 服务帐号拥有对该主题的 Pub/Sub 发布商访问权限。

  7. 点击更新主题

更改主题名称

要更改主题名称而不丢失消息,请执行以下步骤:

  1. 创建并配置新的主题和订阅项目。
  2. 开始阅读和处理发布到新主题的消息。
  3. 在 Play 管理中心内更新该应用的主题名称。
  4. 借助 Stackdriver 或 Cloud Developer Console,等待旧主题停止接收消息,同时确保新主题在接收消息。
  5. 在旧主题停止接收消息后将其删除。

删除主题

要删除主题,请执行以下操作:

  1. 通过 Google Play 管理中心移除应用的主题名称。
  2. 在停止接收消息后,通过 Google 或 Google Cloud Platform Console 删除相应的 Pub/Sub 主题。

注意:如果先在 Pub/Sub 中删除主题,然后再移除名称,可能会导致消息丢失。您必须使用 Pub/Sub 重新设置该主题才能解决此问题。

调整通知处理方式

由于可能会发送到 Pub/Sub 主题的通知种类繁多,因此对所有通知采用单一的二进制处理方式可能并不现实。在决定如何调整通知处理方式时,有多种选项可供研究。这些选项包括:

  • 使用推送和提取式通知。
  • 为主题设置多个订阅项目。
  • 将通知消息重新发布到其他 Pub/Sub 项目。

例如,单个订阅项目可以拥有多个从此订阅项目中提取消息的进程。来自此订阅项目的消息会在读取器之间自动分配。然后,每个这样的进程都可以处理通知,或将请求路由到更专用的服务。

随着时间的推移,可能会添加新的通知类型。订阅者应该在新通知出现后对其进行恰当的处理,方法通常是确认收到的消息。

注意:如果您选择使用推送订阅,请先注册端点,然后再添加推送端点。有关详情,请参阅注册端点

有关详情,请参阅 Pub/Sub 订阅者概览

监控通知流量

要监控通知流量,请使用 Google Stackdriver 服务。借助此服务,您可以监控主题的流量,并针对特定条件设置提醒。例如,如果您的未确认消息计数过高(可能意味着订阅者出问题了)或发布计数过低(可能意味着发布到主题时出错了),您便可以发出提醒。

确定定价和配额

要详细了解定价和配额,请参阅定价配额

估算流量消耗

订阅通知的流量大约为每个请求 1KB 的流量。每次发布和提取通知都需要一个单独的请求,即每个通知大约 2KB 的流量。每月的通知数量取决于您的结算周期和用户的行为。在一个结算周期内,每个用户应至少有一个通知。

服务等级协议 (SLA)

实时开发者通知服务并不提供官方延迟 SLA。不过,大多数通知都应该在事件发生后的几秒钟内发布。您应该在 Stackdriver 页面中监控流量消耗指标(例如未确认的消息数量),以确保您能够及时处理所有消息。

JSON 规范

发布到 Pub/Sub 主题的每个消息都包含一个以 base64 编码的 DeveloperNotification,其中包含以下字段:

{
  "version": string,
  "packageName": string
  "eventTimeMillis": long
  "subscriptionNotification": SubscriptionNotification
  "testNotification": TestNotification
}
属性名称 说明
version string 此通知的版本。最初,此值将为“1.0”。此版本与其他版本字段不同。
packageName string 与此通知相关的应用的软件包名称(例如,com.some.thing)。
eventTimeMillis long 事件发生的时间戳,以从公元纪年开始计算的毫秒数表示。
subscriptionNotification SubscriptionNotification 如果此字段存在,则此通知与某个订阅项目相关。它包含与此订阅项目相关的其他信息。此字段与 testNotification 互斥。
testNotification TestNotification 如果此字段存在,则此通知与某个测试发布相关。这些通知只通过 Play 管理中心发送。此字段与 subscriptionNotification 互斥。

SubscriptionNotification 包含以下字段:

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

通知的类型。它可以具有以下值:

  • (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 - 订阅已过期。
purchaseToken string 购买订阅时向用户设备提供的令牌。
subscriptionId string 所购买订阅的 ID(例如“monthly001”)。

注意:系统仅针对需要更改用户权限的事件发送通知。例如,Refund API 并不会更改用户权限,因此不会触发通知。

TestNotification 包含以下字段:

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

示例

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

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

以下是测试通知的示例:

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