rc-catalog-management

商品目录管理

通过两个界面管理 Android 商品目录：Google Play Console（商品的事实来源）和 RevenueCat 控制面板（权益、Offering 和定向）。你不会在应用或后端中调用 Google Play Developer 的 monetization.subscriptions 或 monetization.onetimeproducts 端点。

阶段 1：了解

在进行任何操作之前，请先阅读本阶段。

为什么有两个界面

界面	管理内容	示例
Google Play Console	底层商品、基本方案、优惠	premium_monthly、基本方案 p1m、新用户优惠
RevenueCat 控制面板	权益、Offering、Package、定向	pro 权益、default Offering、$rc_monthly Package

Play Console 保存可计费的 SKU。RevenueCat 决定向哪些用户展示哪个 SKU，以及将其关联到哪个权益键。

无需更新应用即可进行的更改

当应用调用 awaitOfferings() 时，会获取 RevenueCat 控制面板中配置的内容。Offering 编辑、Package 替换和定向规则会在应用下次启动时生效。无需发布新的二进制版本。

何时使用 REST API

如果需要从后端自动执行目录编辑（例如，在多个环境中批量创建数十个 Offering），请使用 RevenueCat REST API 管理商品、权益和 Offering。仍然不要直接调用 Google。Play Console 仍然是商品的事实来源。

阶段 2：规划

更改之前，请先确定：

1. 这是新商品，还是对现有商品重新打包？
   • 新商品：从 Play Console 开始。
   • 重新打包（新 Offering、新定向、新权益映射）：在 RevenueCat 中操作。
2. 该商品会解锁哪个权益？ 如果没有匹配的权益，请先创建一个。
3. 使用哪个 Offering 和 Package 标识符？ 确定 Package 标识符（例如 $rc_monthly、$rc_annual），以确保付费墙代码继续正常工作。
4. 是否需要更改定向？ 如果不同用户应看到不同的 Offering，请规划放置名称和定向规则（OS 版本、国家/地区、自定义属性）。

阶段 3：执行

添加新订阅商品的端到端流程。

步骤 1：在 Play Console 中添加商品

1. 打开 Play Console -> 你的应用 -> 变现 -> 商品 -> 订阅。
2. 点击 创建订阅。
3. 设置商品 ID（例如 premium_monthly）、名称和说明。
4. 添加基本方案（计费周期、续订类型、价格）。
5. 可选：添加优惠（新用户定价、免费试用）。
6. 激活订阅。

等待几分钟，让 Play 同步商品。

步骤 2：导入到 RevenueCat 并关联权益

1. 打开 RevenueCat 控制面板 -> 你的项目 -> 商品。
2. 点击 导入，从 Play Console 同步。新商品会显示在列表中。
3. 打开商品，并将其关联到现有权益，或创建新权益。
   • 权益示例：pro。每个可解锁 pro 功能的商品都要关联到 pro。

客户端代码通过键检查权益：

val isPro = customerInfo.entitlements["pro"]?.isActive == true

步骤 3：将商品添加到 Offering 中作为 Package

1. 在控制面板中，打开 Offerings。
2. 选择要编辑的 Offering，或创建一个新的（例如 default）。
3. 添加一个 Package。选择与付费墙匹配的 Package 标识符：
   • 月付使用 $rc_monthly
   • 年付使用 $rc_annual
   • 或使用自定义标识符
4. 将 Play Console 商品关联到该 Package。
5. 保存。如果该 Offering 应作为默认 Offering，请将其设为 Current。

客户端代码保持不变：

val offerings = Purchases.sharedInstance.awaitOfferings()
val monthly = offerings.current?.monthly

步骤 4（可选）：定向

如果不同用户应该看到不同的产品，请使用投放位置。

1. 在控制面板中，打开 Targeting -> Placements。
2. 创建一个投放位置（例如 paywall_upsell）。
3. 添加规则（操作系统版本、国家/地区、自定义属性），将用户映射到特定的产品。

客户端代码：

val offering = offerings.getCurrentOfferingForPlacement("paywall_upsell")
    ?: offerings.current

之后更改定向规则无需更新应用。

第 4 阶段：验证

结束任务前，请确认更改已生效。

检查项	方法
产品已创建	Play Console -> Subscriptions 显示该产品为 Active
产品已导入 RC	控制面板 -> Products 列出了该产品
权益映射	控制面板 -> Entitlements 显示该产品归属正确的权益
产品方案配置	控制面板 -> Offerings 显示该产品已关联到预期的套餐
运行时获取	启动应用，调用 awaitOfferings()，确认套餐已成功解析
权益解锁	完成测试购买，确认 customerInfo.entitlements["pro"].isActive 为 true

如果 awaitOfferings() 对预期的套餐返回 null，最常见的原因是：该产品方案未标记为 Current、该产品未关联到套餐，或者 Play 尚未完成产品信息的传播。

常见错误

• 从后端调用 monetization.subscriptions。请改用 RevenueCat。
• 在导入产品之前创建产品方案。请先导入，再进行关联。
• 在付费墙 UI 中写死产品 ID。请使用套餐标识符，这样无需发布应用更新即可替换产品。
• 忘记将产品方案标记为 Current。调用 offerings.current 的客户端在你切换之前会看到旧产品方案。

参考资料

• 完整章节