添加实时开发者通知

概览

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. 找到您的主题，然后打开权限详细信息。

   

   图 3.访问主题的“权限”配置。

4. 添加服务帐号 [e-mail]，然后授予其 Pub/Sub 发布商的角色。

   

   图 2.将 Google Play 服务帐号添加为 Pub/Sub 发布商。

5. 保存以完成主题设置。

   

   图 3.主题配置完成。

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

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

1. 打开 Google Play 管理中心。
2. 选择您的 Android 应用。
3. 依次转到开发工具 > 服务和 API 页面。

4. 滚动到页面底部的实时开发者通知部分。

   

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

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

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

   如果发布失败，则系统会显示错误。请确保主题名称正确，并且 [e-mail] 服务帐号拥有对该主题的 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
  "oneTimeProductNotification": OneTimeProductNotification
  "subscriptionNotification": SubscriptionNotification
  "testNotification": TestNotification
}

属性名称	值	说明
version	string	此通知的版本。最初，此值将为“1.0”。此版本与其他版本字段不同。
packageName	string	与此通知相关的应用的软件包名称（例如，com.some.thing）。
eventTimeMillis	long	事件发生的时间戳，以从公元纪年开始计算的毫秒数表示。
oneTimeProductNotification	OneTimeProductNotification	如果此字段存在，则此通知与某个一次性商品相关。它包含与此一次性产品相关的其他信息。此字段与 testNotification 和 subscriptionNotification 互斥。
subscriptionNotification	SubscriptionNotification	如果此字段存在，则此通知与某个订阅项目相关。它包含与此订阅项目相关的其他信息。此字段与 testNotification 和 oneTimeProductNotification 互斥。
testNotification	TestNotification	如果此字段存在，则此通知与某个测试发布相关。这些通知只通过 Play 管理中心发送。此字段与 subscriptionNotification 和 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”）。

注意：系统仅针对待处理交易发送一次性商品通知。有关详情，请参阅 Google Play 结算库 2.0 版本说明。

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"
  }
}