RevenueCat 设置

这一页把 Google Play 商品接到 RevenueCat，再把 RevenueCat 事件接到 Android 应用读取的 Supabase 权益读模型。

设置链路

Play Console app and products
  -> RevenueCat Android app, products, entitlement, offering
  -> Supabase revenuecat-webhook
  -> REVENUECAT_ANDROID_KEY in local.properties

真正的 Google Play Billing 购买流程需要应用已经上传到 Play 测试轨道。直接从 Android Studio 安装的 debug build 可以渲染付费墙，但商品通常要等 package 被 Play 识别、测试用户通过 opt-in track 安装后，才适合做端到端购买验证。

前置条件

Supabase 项目已经应用 subscriptions 迁移。
revenuecat-webhook 已用 --no-verify-jwt 部署。
REVENUECAT_WEBHOOK_AUTH 已保存为 Supabase Edge secret。
Google Play Console app 的 package name 是 com.soarstarter.kotlin，或你重命名后的 applicationId。
真实商品设置和 license tester 需要 Google Play developer account。

创建 Play 商品

在 Play Console 创建 app

使用 app/build.gradle.kts 里的同一个 package name 创建 Play Console app。模板默认是：

com.soarstarter.kotlin

在期待购买流程端到端工作之前，先上传 .aab 到 Internal testing。

创建订阅商品

在 Play Console 打开 Monetize -> Products -> Subscriptions，创建：

Product id	Name	Base plan
`pro_monthly`	Soar Starter Pro Monthly	Monthly, auto-renewing, active
`pro_yearly`	Soar Starter Pro Yearly	Yearly, auto-renewing, active

设置价格并激活 base plans。

创建 lifetime 商品

在 Monetize -> Products -> In-app products 创建：

Product id	Name	Type
`pro_lifetime`	Soar Starter Lifetime	One-time in-app product

设置各市场价格并激活商品。

添加 license testers

在 Play Console 添加用于购买测试的 Google 账号。这些 tester 也要加入 Internal testing 轨道，并通过 opt-in link 安装应用。

配置 RevenueCat

创建 RevenueCat project 和 Android app

创建 RevenueCat project，添加 Android app，并把 package name 设置成 Play Console 看到的同一个 applicationId。

连接 Google Play credentials

在 RevenueCat 里连接 Play service-account credentials JSON，权限要满足 RevenueCat 读取商品和校验购买的要求。这个 JSON 保存在 RevenueCat / Google Cloud，不要放进 Android 仓库。

添加 products

把这些 Play products 添加到 RevenueCat：

pro_monthly
pro_yearly
pro_lifetime

RevenueCat 会从 Play 读取本地化价格和商品元数据。

创建 entitlement

创建一个 entitlement：

pro

把 monthly、yearly、lifetime 商品都挂到这个 entitlement 下。这对应 PurchasesController.PRO_ENTITLEMENT_ID。

创建 Android offering

创建或更新当前 Android offering，并把 packages 设置为 monthly、annual 和 lifetime。应用会渲染 active offering 返回的任意子集。

复制 Android SDK key

把 public Android SDK key 写入模板的 local.properties：

REVENUECAT_ANDROID_KEY=goog_your_public_android_sdk_key

缺失值会生成空的 BuildConfig 字符串。此时 PurchasesController.isConfigured 为 false，付费墙会显示 unavailable 信息，不会启动 RevenueCat。

连接 webhook

RevenueCat 应调用已部署的 Supabase Edge Function：

https://<ref>.supabase.co/functions/v1/revenuecat-webhook

把 RevenueCat webhook 的 Authorization header 设置为与下面 secret 相同的值：

supabase secrets set REVENUECAT_WEBHOOK_AUTH=<long-random-string> --project-ref <ref>

在 soar-kotlin/supabase 目录部署函数：

supabase functions deploy revenuecat-webhook --no-verify-jwt --project-ref <ref>

RevenueCat 不是已登录的 Supabase 用户，所以这个函数关闭 Supabase JWT 验证。它会校验静态 Authorization header，然后用 service-role key 写入。

当前 Kotlin 函数在接受投递后返回文本 success。有些旧说明可能写着 {"ok":true}；以当前部署代码为准。

事件映射

RevenueCat event data	Supabase row
`app_user_id`	`subscriptions.user_id`
`store = PLAY_STORE`	`provider = play_store`
`product_id`	`product_id`
购买周期或 non-renewing event	`product_type = month`、`year` 或 `one_time`
Event type 和 trial data	`status = trialing`、`active`、`canceled` 或 `expired`
Purchase timestamp	`period_start` 和 `last_paid_at`
Expiration 或 grace timestamp	`period_end`
Transaction ids	`last_order_no` 和 `subscription_id`
RevenueCat original app user id	`customer_id`

不支持的 store、未建模的 event type、非 UUID app_user_id 会被设计性忽略。接受的事件是幂等的，因为表按 user_id 唯一。

验证

RevenueCat 能读取三个 Play products。
pro entitlement 包含 monthly、yearly 和 lifetime 商品。
当前 Android offering 至少返回一个 package。
购买构建的 local.properties 中存在 REVENUECAT_ANDROID_KEY。
RevenueCat webhook 测试投递返回 HTTP 200 和 success。
已登录用户的 sandbox purchase 会把 provider = play_store 写入 public.subscriptions。