2026年Google Play实时开发者通知(RTDN)教程：从Cloud Pub/Sub配置、推送与拉取订阅到全部事件类型处理

实时开发者通知(RTDN)是 Google Play 告诉你的服务端「某笔购买发生变化」的唯一推送机制。它没有 webhook 面板，也没有按应用发放的密钥：Google Play 把消息发布到你自己的 Google Cloud 项目里的 Cloud Pub/Sub 主题(topic)，你的服务器要么以 HTTPS 推送(push)接收，要么主动拉取(pull)。如果你的收款运营还依赖定时任务轮询 Developer API，RTDN 就是升级方向——Google 官方文档明确写着，低效使用 Play Developer API「可能导致 API 配额受限」。

本文按你实际操作的顺序走完全程：创建主题、授予 Play 发布权限、选择推送或拉取、在 Play Console 开启通知，然后解码消息并处理。下面所有字段名、事件类型编号与控制台步骤都取自 Google 的两篇官方文档，链接见文末。

第一步：在自己的 GCP 项目里创建 Pub/Sub 主题

RTDN 是按 Android 应用逐个配置的，但消息基础设施属于你自己。你需要一个已启用 Cloud Pub/Sub API 的 Google Cloud 项目，以及 Google Play 用来发布消息的主题。项目可以复用现有的 Play Developer API 项目，也可以新建：如果管理多个应用，Play Developer API 必须使用同一个 Google Cloud 项目，但每个应用可以各自使用不同的项目发布通知。

动手前先算容量。通知的数据部分约为每次请求 1 KB，而每次发布与拉取都是独立请求，即每条通知约 2 KB；每月数量取决于结算周期和用户行为，但官方建议按「每个用户每个计费周期至少一条通知」估算，再对照 Pub/Sub 的定价与配额确认成本。

第二步：给 Google Play 授予发布权限

新建的主题在没有授权前会直接拒收 Play 的消息，这一步最常被漏掉。在 Google Cloud Console 中：选择项目，打开 Pub/Sub，找到你的主题，打开权限详情，然后添加服务账号

google-play-developer-notifications@system.gserviceaccount.com

并授予 Pub/Sub Publisher 角色，保存后主题配置才算完成。企业组织还有一处坑：如果组织启用了域限制共享(domain-restricted sharing)，该角色可能根本授不出去，必须为这个 Google Play 服务账号添加例外，否则 Play 无法发布任何通知。

第三步：订阅用推送还是拉取

主题不是一个可以直接读取的邮箱，你需要给它挂一个订阅(subscription)。推送订阅由 Cloud Pub/Sub 主动向你的安全后端发起 HTTPS 请求；拉取订阅则由你的后端主动向 Pub/Sub 请求并取回消息。Google 对 RTDN 的建议是：如果拿不准就用推送，「通常更容易实现」；拉取则常用于消息量很大时优化资源占用。

选定后随之而来两条运维规则。拉取模式：每拉取一条消息都要确认(acknowledge)，否则 Pub/Sub 会反复重投。推送模式：你的端点返回成功状态码即视为确认——端点慢或报错，就意味着重复投递。

第四步：在 Play Console 开启 RTDN 并发送测试消息

1. 打开 Google Play Console，选择应用，进入 Monetize → Monetization setup。
2. 在页面顶部的 Real-time developer notifications 区域，勾选 Enable real-time notifications。
3. 在 Topic name 中填入完整主题名，格式为 projects/{project_id}/topics/{topic_name}。
4. 点击 Send Test Message。拉取模式：到 Cloud Console 的订阅里点 View Messages 拉取，并确认消息；推送模式：确认测试消息到达你的端点。
5. 选择通知范围。订阅与全部已作废购买只推订阅与作废购买事件；订阅与一次性商品的全部通知还会推送 ONE_TIME_PRODUCT_PURCHASED、ONE_TIME_PRODUCT_CANCELED 等一次性商品事件。
6. 点击 Save changes。

测试发布失败时控制台会给出错误，实际原因基本只有两个：主题名写错，或者 google-play-developer-notifications@system.gserviceaccount.com 没有该主题的 Pub/Sub Publisher 权限。要修的是授权，不是应用本身。

消息里到底有什么

发布到主题的每条消息结构一致：一个 attributes 映射、base64 编码的 data 字段、messageId，以及 subscription 路径。把 data 解码后得到 DeveloperNotification，含四个顶层事实——version、packageName、eventTimeMillis——外加恰好一个载荷字段。这四个载荷字段互斥：subscriptionNotification、oneTimeProductNotification、voidedPurchaseNotification、testNotification。

messageId 是这条通知的唯一标识，官方参考文档建议校验其唯一性，避免重复处理通知、发起冗余的后端 API 调用——那正好会消耗掉 RTDN 本想帮你省下的 API 配额。

订阅事件类型一览

subscriptionNotification 里带整数 notificationType、purchaseToken 和它自己的 version。当前完整取值：

• 1 — SUBSCRIPTION_RECOVERED：从账号保留(account hold)恢复，或从暂停恢复。
• 2 — SUBSCRIPTION_RENEWED：有效订阅续订。
• 3 — SUBSCRIPTION_CANCELED：主动或被动取消；主动取消在用户操作时即发送。
• 4 — SUBSCRIPTION_PURCHASED：新订阅购买成功。
• 5 — SUBSCRIPTION_ON_HOLD：进入账号保留(若你已启用)。
• 6 — SUBSCRIPTION_IN_GRACE_PERIOD：进入宽限期(若你已启用)。
• 7 — SUBSCRIPTION_RESTARTED：用户从 Play → 账号 → 订阅中恢复了尚未到期的已取消订阅。
• 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：价格阶梯上调的同意期开始，或用户已同意；仅在要求价格阶梯上调的地区发送。

编号 8(SUBSCRIPTION_PRICE_CHANGE_CONFIRMED) 在官方参考中已标注为废弃，不要基于它写新逻辑。另外要记住：这些编号不是可推断的生命周期，事件只告诉你状态变了，从不告诉你变成什么。

一次性商品通知

只有在你勾选了更宽的范围时才会发送。oneTimeProductNotification 在 token 之外多一个 sku 字段，两个取值：1 — ONE_TIME_PRODUCT_PURCHASED(一次性商品购买成功)、2 — ONE_TIME_PRODUCT_CANCELED(待处理的一次性购买被用户取消)。两种情况都仍需调用 Developer API，因为购买通知并没说清你是否已经消耗(consume)或确认(acknowledge)该商品。

已作废购买与 refundType 字段

voidedPurchaseNotification 是收款团队最关心的一类，2026 年的载荷比过去多了信息：purchaseToken、orderId、productType、refundType。productType 为 1 表示订阅、2 表示一次性购买；refundType 为 1 — REFUND_TYPE_FULL_REFUND(整笔作废)或 2 — REFUND_TYPE_QUANTITY_BASED_PARTIAL_REFUND(按数量的部分退款，仅适用于多数量购买，且可被多次部分作废；当剩余总量被全部退还后，类型会变为全额退款)。

官方参考明确指出：若只是为了定位应调整权益的购买与订单，通知本身已足够；需要更多作废购买数据时，用 Google Play Voided Purchases API——它是以时间戳区间拉取的 pull 模型。对多数量购买的部分退款，purchases.productsv2 返回的 refundableQuantity 表示尚未作废的数量。这与我们此前梳理的2026 年 Play 退款与拒付指南正好衔接。

让管道保持正确的服务端规则

• 把通知当提问，而不是答案。每次收到 RTDN 后都调用 Developer API 获取完整状态，再决定授予、顺延还是撤销权益。
• 按 messageId 去重。Pub/Sub 是至少一次投递；重复处理等于重复调用 API、重复变更状态。
• 先确认，再处理。拉取模式逐条确认；推送模式返回成功码。如果处理时间超过确认时间，就接受重投，并把处理逻辑写成幂等。
• 预期同一用户多条事件。同一个 purchaseToken 会依次产生购买、取消、到期通知，处理函数必须可反复执行。
• 不要用轮询兜底。在 RTDN 之外继续轮询 Developer API，正是触发配额限制的典型失败模式。

验证配置是否真的通了

控制台的 Send Test Message 是最快的端到端验证：只要挂了订阅就应当收到。testNotification 的正文只含一个 version 字段，非常适合作为处理函数的测试断言载荷。若还没有后端，可用 gcloud 从订阅里拉取消息——记得确认。一条健康的管道表现为：事件持续到达，packageName 与你的应用一致，eventTimeMillis 跟随真实订阅行为。

最后一个时间点提示：服务端 RTDN 与客户端结算库的截止日期是相邻的工程。所有新应用与更新必须使用 Billing Library 8 或更高版本，可申请延期至 2026 年 11 月 1 日——而消费 RTDN 的服务端校验应当同步就绪。

资料来源

• Real-time developer notifications reference guide — Android Developers
• Getting ready：配置 Real-time developer notifications — Android Developers