rc-backend

使用 RevenueCat 的后端架构

使用 RevenueCat 时，无需自行构建收据验证服务器。后端仍然有其职责，但职责是读取 RevenueCat 的状态，而不是验证 Google Play 购买令牌。

阶段 1：了解情况

RevenueCat 的后端就是收据验证服务器。当 Android SDK 提交购买令牌时，RevenueCat 的后端会：

1. 针对 Google Play Developer API 调用 purchases.subscriptionsv2.get 或 purchases.products.get。
2. 验证收据真实有效，并且与预期商品匹配。
3. 在其数据库中记录交易。
4. 向 SDK 返回 CustomerInfo。

Android 应用不会调用 Google Play Developer API。你的服务器也不会调用它。

编写任何后端代码之前，请确认部署的以下情况：

• 你有一个已配置 Android 应用的 RevenueCat 项目。
• 你有 Project Settings → API Keys 中的 Secret API Key（不是嵌入应用中的 Android SDK 公共密钥）。
• 你知道 SDK 使用的 app_user_id 是什么（它与身份验证系统使用的标识符相同）。
• 你已决定后端需要实时状态（REST API），还是事件驱动状态（webhook）。

如果应用只在客户端内控制功能，你可能完全不需要后端组件。RevenueCat 会在 CustomerInfo 到达 SDK 之前在服务器端完成验证，而 EntitlementVerificationMode.INFORMATIONAL 或 .ENFORCED 会在客户端添加签名验证。只有在能够于服务器端验证权益时，才从服务器提供高级内容。

阶段 2：规划

将每项后端职责对应到 RevenueCat 的机制。

用例	机制	说明
响应购买、续订、取消	Webhook 接收器	RevenueCat 会发送规范化事件；你的服务器更新自己的数据库。
检查用户当前的权益	GET /v1/subscribers/{app_user_id}	在 Authorization 标头中使用 Secret API Key。
授予促销访问权限（客服支持、退款、赠送）	POST /v1/subscribers/{app_user_id}/entitlements/{entitlement_id}/promotional	仅限服务器端。
撤销促销访问权限	POST /v1/subscribers/{app_user_id}/entitlements/{entitlement_id}/revoke_promotionals	仅限服务器端。
根据服务器端数据设置订阅者属性	POST /v1/subscribers/{app_user_id}/attributes	适用于 SDK 不知道的 CRM 字段。
批量数据导出	RevenueCat 数据导出	将定期导出数据到你的数据仓库。

后端仍负责：

• 用户身份验证。
• 保存用户及其访问级别的数据库。
• 提供高级内容的 API 端点。
• 处理 RevenueCat 事件的 webhook 接收器。

后端不负责：

• Google Play Developer API 凭据。
• 收据验证代码。
• 遍历 linkedPurchaseToken 链。
• 根据七种订阅状态计算订阅状态。

阶段 3：执行

读取订阅者信息

GET https://api.revenuecat.com/v1/subscribers/{app_user_id}
Authorization: Bearer sk_...
X-Platform: android

响应正文与 Android SDK 返回的 CustomerInfo 结构相同。在控制高级 API 响应的服务器端点中使用它。

授予促销权益

POST https://api.revenuecat.com/v1/subscribers/{app_user_id}/entitlements/{entitlement_id}/promotional
Authorization: Bearer sk_...
Content-Type: application/json

{"duration": "monthly"}

有效的 duration 值包括 daily、three_day、weekly、monthly、two_month、three_month、six_month、yearly、lifetime。将其用于客服支持工作流，切勿从客户端调用。

示例：服务器通过 Kotlin Ktor 发起调用

val response = client.get("https://api.revenuecat.com/v1/subscribers/$appUserId") {
    header("Authorization", "Bearer ${System.getenv("RC_SECRET_KEY")}")
    header("X-Platform", "android")
}

API Key 规则

密钥	存放位置	功能
Android SDK 公共密钥	嵌入 Android 应用中	提交购买记录，为当前用户获取 CustomerInfo。
Secret API Key	仅作为服务器环境变量	读取任意订阅者信息、授予或撤销促销权益、设置属性、执行批量操作。

切勿将 Secret Key 放入 Android APK、BuildConfig 字段或任何客户端程序包中。如果密钥泄露，请立即轮换。请像保护数据库密码一样保护它。

Webhook 接收端概要

post("/revenuecat/webhook") {
    val auth = call.request.header("Authorization")
    require(auth == "Bearer ${System.getenv("RC_WEBHOOK_SECRET")}")
    val event = call.receive<RevenueCatEvent>()
    when (event.type) {
        "INITIAL_PURCHASE", "RENEWAL" -> grantAccess(event.appUserId, event.entitlements)
        "CANCELLATION", "EXPIRATION" -> scheduleRevocation(event.appUserId)
    }
    call.respond(HttpStatusCode.OK)
}

验证你在 RevenueCat 控制面板中配置的授权标头。尽快返回 2xx 响应；对于非 2xx 响应，RevenueCat 会重试。

不要构建的内容

• 不要构建 Google Play 收据验证端点。RevenueCat 已经处理了这项工作。
• 不要将购买令牌从 Android 客户端传到你的服务端进行手动验证。SDK 会处理整个往返流程。
• 除非你要构建绕过 SDK 的自定义集成，否则不要从后端查询 Google Play Developer API。
• 不要在数据库中复刻这套包含七种状态的订阅状态机。请改为使用 CustomerInfo.entitlements.active 或 Webhook 事件。

参考资料

• 完整章节