asc-revenuecat-catalog-sync

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

asc RevenueCat catalog sync

ASC与RevenueCat目录同步

Use this skill to keep App Store Connect (ASC) and RevenueCat aligned, including creating missing ASC items and mapping them to RevenueCat resources.

使用此Skill可保持App Store Connect（ASC）与RevenueCat的配置一致，包括创建缺失的ASC项目并将其映射到RevenueCat资源。

When to use

适用场景

You want to bootstrap RevenueCat from an existing ASC catalog.
You want to create missing ASC subscriptions/IAPs, then map them into RevenueCat.
You need a drift audit before release.
You want deterministic product mapping based on identifiers.

你希望从现有的ASC目录快速搭建RevenueCat配置。
你希望创建缺失的ASC订阅/应用内购，然后将其映射到RevenueCat。
发布前需要进行配置差异审计。
你希望基于标识符实现确定性的产品映射。

Preconditions

前置条件

```
asc
```
authentication is configured (
```
asc auth login
```
or
```
ASC_*
```
env vars).
RevenueCat MCP server is configured and authenticated.
In Cursor and VS Code, OAuth auth is available for RevenueCat MCP. API key auth is also supported.
You know:
- ASC app ID (
```
APP_ID
```
  )
- RevenueCat
```
project_id
```
- target RevenueCat app type (
```
app_store
```
  or
```
mac_app_store
```
  ) and bundle ID for create flows
Use a write-enabled RevenueCat API v2 key when applying changes.

已配置
```
asc
```
身份验证（
```
asc auth login
```
或
```
ASC_*
```
环境变量）。
已配置并完成RevenueCat MCP服务器的身份验证。
在Cursor和VS Code中，RevenueCat MCP支持OAuth身份验证，同时也支持API密钥认证。
你需要知晓：
- ASC应用ID（
```
APP_ID
```
  ）
- RevenueCat
```
project_id
```
- 创建流程对应的目标RevenueCat应用类型（
```
app_store
```
  或
```
mac_app_store
```
  ）及Bundle ID
应用变更时，请使用具备写入权限的RevenueCat API v2密钥。

Safety defaults

安全默认设置

Start in audit mode (read-only).
Require explicit confirmation before writes.
Never delete resources in this workflow.
Continue on per-item failures and report all failures at the end.

默认以审计模式启动（只读）。
执行写入操作前需要明确确认。
此工作流中不会删除任何资源。
单个项目处理失败后会继续执行，最终汇总所有失败项。

Canonical identifiers

标准标识符

Primary cross-system key: ASC
```
productId
```
== RevenueCat
```
store_identifier
```
.
Keep
```
productId
```
stable once products are live.
Do not use display names as unique identifiers.

跨系统核心匹配键：ASC
```
productId
```
== RevenueCat
```
store_identifier
```
。
产品上线后请保持
```
productId
```
稳定。
不要将显示名称作为唯一标识符。

Scope boundary

范围边界

RevenueCat MCP configures RevenueCat resources; it does not create App Store Connect products directly.
Use
```
asc
```
commands to create missing ASC subscription groups, subscriptions, and IAPs before RevenueCat mapping.

RevenueCat MCP用于配置RevenueCat资源，不会直接创建App Store Connect产品。
在进行RevenueCat映射前，请使用
```
asc
```
命令创建缺失的ASC订阅组、订阅及应用内购项目。

Modes

模式

1) Audit mode (default)

1) 审计模式（默认）

Read ASC source catalog.
Read RevenueCat target catalog.
Build a diff with actions:
- missing in ASC
- missing in RevenueCat
- mapping conflicts (identifier/type/app mismatch)
Present a plan and wait for confirmation.

读取ASC源目录。
读取RevenueCat目标目录。
生成包含以下操作的差异报告：
- ASC中缺失的项目
- RevenueCat中缺失的项目
- 映射冲突（标识符/类型/应用不匹配）
展示执行计划并等待确认。

2) Apply mode (explicit)

2) 应用模式（需明确指定）

Execute approved actions in this order:

Ensure ASC groups/subscriptions/IAP exist.
Ensure RevenueCat app/products exist.
Ensure entitlements and product attachments.
Ensure offerings/packages and package attachments.
Verify and print a final reconciliation summary.

按以下顺序执行已确认的操作：

确保ASC的订阅组、订阅及应用内购项目已存在。
确保RevenueCat的应用和产品已存在。
确保权益及产品关联配置正确。
确保产品组、套餐及套餐关联配置正确。
验证并打印最终的对账同步总结。

Step-by-step workflow

分步工作流

Step A - Read current ASC catalog

步骤A - 读取当前ASC目录

bash

asc subscriptions groups list --app "APP_ID" --paginate --output json
asc iap list --app "APP_ID" --paginate --output json

bash

asc subscriptions groups list --app "APP_ID" --paginate --output json
asc iap list --app "APP_ID" --paginate --output json

for each subscription group:

asc subscriptions list --group "GROUP_ID" --paginate --output json

undefined

asc subscriptions list --group "GROUP_ID" --paginate --output json

undefined

Step B - Read current RevenueCat catalog (MCP)

步骤B - 读取当前RevenueCat目录（MCP）

Use these MCP tools (with

project_id

and pagination where applicable):

```
mcp_RC_get_project
```
```
mcp_RC_list_apps
```
```
mcp_RC_list_products
```
```
mcp_RC_list_entitlements
```
```
mcp_RC_list_offerings
```
```
mcp_RC_list_packages
```

使用以下MCP工具（需指定

project_id

，按需启用分页）：

```
mcp_RC_get_project
```
```
mcp_RC_list_apps
```
```
mcp_RC_list_products
```
```
mcp_RC_list_entitlements
```
```
mcp_RC_list_offerings
```
```
mcp_RC_list_packages
```

Step C - Build mapping plan

步骤C - 生成映射计划

Map ASC product types to RevenueCat product types:

ASC subscription -> RevenueCat
```
subscription
```
ASC IAP
```
CONSUMABLE
```
-> RevenueCat
```
consumable
```
ASC IAP
```
NON_CONSUMABLE
```
-> RevenueCat
```
non_consumable
```

ASC IAP

NON_RENEWING_SUBSCRIPTION

-> RevenueCat

non_renewing_subscription

Suggested entitlement policy:

subscriptions: one entitlement per subscription group (or explicit map provided by user)
non-consumable IAP: one entitlement per product
consumable IAP: no entitlement by default unless user asks

将ASC产品类型映射到RevenueCat产品类型：

ASC订阅 -> RevenueCat
```
subscription
```
ASC应用内购
```
CONSUMABLE
```
-> RevenueCat
```
consumable
```
ASC应用内购
```
NON_CONSUMABLE
```
-> RevenueCat
```
non_consumable
```

ASC应用内购

NON_RENEWING_SUBSCRIPTION

-> RevenueCat

non_renewing_subscription

推荐的权益策略：

订阅：每个订阅组对应一个权益（或使用用户提供的显式映射）
非消耗型应用内购：每个产品对应一个权益
消耗型应用内购：默认不关联权益，除非用户要求

Step D - Ensure missing ASC items (if requested)

步骤D - 补全缺失的ASC项目（若有需求）

Create missing ASC resources first, then re-read ASC to capture canonical IDs.

bash

undefined

先创建缺失的ASC资源，然后重新读取ASC以获取标准ID。

bash

undefined

create subscription group

创建订阅组

asc subscriptions groups create --app "APP_ID" --reference-name "Premium"

create subscription

创建订阅

asc subscriptions create
--group "GROUP_ID"
--ref-name "Monthly"
--product-id "com.example.premium.monthly"
--subscription-period ONE_MONTH

create iap

创建应用内购

asc iap create
--app "APP_ID"
--type NON_CONSUMABLE
--ref-name "Lifetime"
--product-id "com.example.lifetime"

undefined

asc iap create
--app "APP_ID"
--type NON_CONSUMABLE
--ref-name "Lifetime"
--product-id "com.example.lifetime"

undefined

Step E - Ensure RevenueCat app and products

步骤E - 补全RevenueCat应用与产品

Use MCP:

create app if missing:
```
mcp_RC_create_app
```
create products:
```
mcp_RC_create_product
```
- ```
store_identifier
```
  = ASC
```
productId
```
- ```
app_id
```
  = RevenueCat app ID
- ```
type
```
  from mapping above

使用MCP工具：

若应用缺失则创建：
```
mcp_RC_create_app
```
创建产品：
```
mcp_RC_create_product
```
- ```
store_identifier
```
  = ASC
```
productId
```
- ```
app_id
```
  = RevenueCat应用ID
- ```
type
```
  来自上述类型映射

Step F - Ensure entitlements and attachments

步骤F - 补全权益及关联配置

Use MCP:

list/create entitlements:

mcp_RC_list_entitlements

mcp_RC_create_entitlement

attach products:
```
mcp_RC_attach_products_to_entitlement
```
verify attachments:
```
mcp_RC_get_products_from_entitlement
```

使用MCP工具：

列出/创建权益：

mcp_RC_list_entitlements

、

mcp_RC_create_entitlement

关联产品：
```
mcp_RC_attach_products_to_entitlement
```
验证关联：
```
mcp_RC_get_products_from_entitlement
```

Step G - Ensure offerings and packages (optional)

步骤G - 补全产品组及套餐（可选）

Use MCP:

list/create/update offerings:

```
mcp_RC_list_offerings
```
```
mcp_RC_create_offering
```
```
mcp_RC_update_offering
```
(
```
is_current=true
```
only if requested)

list/create packages:

```
mcp_RC_list_packages
```
```
mcp_RC_create_package
```

attach products to packages:

mcp_RC_attach_products_to_package

with

eligibility_criteria: "all"

Recommended package keys:

```
ONE_WEEK
```
->
```
$rc_weekly
```
```
ONE_MONTH
```
->
```
$rc_monthly
```
```
TWO_MONTHS
```
->
```
$rc_two_month
```
```
THREE_MONTHS
```
->
```
$rc_three_month
```
```
SIX_MONTHS
```
->
```
$rc_six_month
```
```
ONE_YEAR
```
->
```
$rc_annual
```
lifetime IAP ->
```
$rc_lifetime
```
custom ->
```
$rc_custom_<name>
```

使用MCP工具：

列出/创建/更新产品组：

```
mcp_RC_list_offerings
```
```
mcp_RC_create_offering
```
```
mcp_RC_update_offering
```
（仅在用户要求时设置
```
is_current=true
```
）

列出/创建套餐：

```
mcp_RC_list_packages
```
```
mcp_RC_create_package
```

将产品关联到套餐：

使用

mcp_RC_attach_products_to_package

并设置

eligibility_criteria: "all"

推荐的套餐键：

```
ONE_WEEK
```
->
```
$rc_weekly
```
```
ONE_MONTH
```
->
```
$rc_monthly
```
```
TWO_MONTHS
```
->
```
$rc_two_month
```
```
THREE_MONTHS
```
->
```
$rc_three_month
```
```
SIX_MONTHS
```
->
```
$rc_six_month
```
```
ONE_YEAR
```
->
```
$rc_annual
```
终身应用内购 ->
```
$rc_lifetime
```
自定义 ->
```
$rc_custom_<name>
```

Expected output format

预期输出格式

Return a final summary with:

ASC created counts (groups/subscriptions/IAP)
RevenueCat created counts (apps/products/entitlements/offerings/packages)
attachment counts (entitlement-products, package-products)
skipped existing items
failed items with actionable errors

Example:

text

ASC: created groups=1 subscriptions=2 iap=1, skipped=14, failed=0
RC: created apps=0 products=3 entitlements=2 offerings=1 packages=2, skipped=27, failed=1
Attachments: entitlement_products=3 package_products=2
Failures:
- com.example.premium.annual: duplicate store_identifier exists on another RC app

返回最终汇总信息，包含：

ASC创建数量（订阅组/订阅/应用内购）
RevenueCat创建数量（应用/产品/权益/产品组/套餐）
关联数量（权益-产品、套餐-产品）
已跳过的现有项目数量
处理失败的项目及可操作的错误信息

示例：

text

ASC: created groups=1 subscriptions=2 iap=1, skipped=14, failed=0
RC: created apps=0 products=3 entitlements=2 offerings=1 packages=2, skipped=27, failed=1
Attachments: entitlement_products=3 package_products=2
Failures:
- com.example.premium.annual: duplicate store_identifier exists on another RC app

Agent behavior

Agent行为规范

Always run audit first, even in apply mode.
Ask for confirmation before create/update operations.
Match by
```
store_identifier
```
first.
Use full pagination (
```
--paginate
```
for ASC,
```
starting_after
```
for RevenueCat tools).
Continue processing after per-item failures and report all failures together.
Never auto-delete ASC or RevenueCat resources in this skill.

即使在应用模式下，也始终先运行审计流程。
创建/更新操作前需请求确认。
优先通过
```
store_identifier
```
进行匹配。
使用完整分页（ASC使用
```
--paginate
```
，RevenueCat工具使用
```
starting_after
```
）。
单个项目处理失败后继续执行，最终汇总所有失败项。
此Skill中绝不会自动删除ASC或RevenueCat的资源。

Common pitfalls

常见误区

Wrong RevenueCat
```
project_id
```
or app ID.
Creating RC products under the wrong platform app.
Accidentally assigning consumables to entitlements.
Skipping the post-create ASC re-read step.
Missing offering/package verification after product creation.

错误的RevenueCat
```
project_id
```
或应用ID。
在错误的平台应用下创建RevenueCat产品。
意外将消耗型产品关联到权益。
跳过创建后重新读取ASC的步骤。
产品创建后未验证产品组/套餐的配置。

Additional resources

额外资源

Workflow examples: examples.md
Source references: references.md

工作流示例：examples.md
参考资料：references.md