AI Skills
asc-revenuecat-catalog-sync

asc-revenuecat-catalog-sync

熱門

使用 asc 與 RevenueCat MCP，比對並對齊 App Store Connect 的訂閱項目與應用程式內購（IAP）至 RevenueCat 的產品（products）、權益（entitlements）、方案（offerings）及包裹（packages）。適用於跨 ASC 與 RevenueCat 設定或同步訂閱目錄時。

948星標
50分支
更新於 2026/7/31
獲取技能源代碼

相關技能

github-actions-hardening3.9萬dnanexus-integration4.2萬security-and-hardening7.7萬
SKILL.md
唯讀
名稱
asc-revenuecat-catalog-sync
描述

使用 asc 與 RevenueCat MCP，比對並對齊 App Store Connect 的訂閱項目與應用程式內購（IAP）至 RevenueCat 的產品（products）、權益（entitlements）、方案（offerings）及包裹（packages）。適用於跨 ASC 與 RevenueCat 設定或同步訂閱目錄時。

asc RevenueCat catalog sync

使用此 Skill 來保持 App Store Connect (ASC) 與 RevenueCat 之間的設定一致，包含建立缺失的 ASC 項目並將其映射至 RevenueCat 資源。

何時使用

  • 想從現有的 ASC 目錄初始化（bootstrap）RevenueCat。
  • 想建立缺失的 ASC 訂閱項目/IAP，再將其映射至 RevenueCat。
  • 在發布前需要進行差異審計（drift audit）。
  • 需要基於識別碼（identifier）進行確定性的產品映射。

前置條件

  • 已設定 asc 驗證（透過 asc auth login 或 ASC_* 環境變數）。
  • 已設定並驗證 RevenueCat MCP 伺服器。
  • 在 Cursor 與 VS Code 中，RevenueCat MCP 支援 OAuth 驗證，同時也支援 API key 驗證。
  • 您已獲知以下資訊：
    • ASC app ID (APP_ID)
    • RevenueCat project_id
    • 目標 RevenueCat 應用程式類型（app_store 或 mac_app_store）以及用於建立流程的 bundle ID
  • 執行變更時，請使用具備寫入權限的 RevenueCat API v2 key。

安全預設機制

  • 預設先以 審計模式（audit mode） 執行（唯讀）。
  • 在進行任何寫入操作前，必須取得明確確認。
  • 此工作流程中絕不刪除任何資源。
  • 若單一項目執行失敗，繼續處理其餘項目，並於最後統一回報所有失敗項目。

標準識別碼

  • 跨系統主要鍵值（Primary key）：ASC 的 productId == RevenueCat 的 store_identifier。
  • 產品上線後，請保持 productId 穩定不可變。
  • 切勿使用顯示名稱（display name）作為唯一識別碼。

範疇界線

  • RevenueCat MCP 用於設定 RevenueCat 資源；它不會直接建立 App Store Connect 產品。
  • 在進行 RevenueCat 映射前，請使用 asc 指令建立缺失的 ASC 訂閱組（subscription groups）、訂閱項目與 IAP。

執行模式

1) 審計模式（Audit mode，預設）

  1. 讀取 ASC 來源目錄。
  2. 讀取 RevenueCat 目標目錄。
  3. 建立包含以下動作的差異報告（diff）：
    • ASC 中缺失
    • RevenueCat 中缺失
    • 映射衝突（識別碼 / 類型 / 應用程式不符合）
  4. 呈現計畫並等待確認。

2) 套用模式（Apply mode，明確指定）

按以下順序執行已核可的動作：

  1. 確保 ASC 訂閱組 / 訂閱項目 / IAP 已存在。
  2. 確保 RevenueCat 應用程式 / 產品已存在。
  3. 確保權益（entitlements）與產品關聯設定完備。
  4. 確保方案（offerings）/ 包裹（packages）與包裹關聯設定完備。
  5. 驗證並列印最終的比對對齊摘要。

循序工作流程

步驟 A - 讀取當前 ASC 目錄

asc subscriptions groups list --app "APP_ID" --paginate --output json
asc iap list --app "APP_ID" --paginate --output json
# 針對每個訂閱組：
asc subscriptions list --group-id "GROUP_ID" --paginate --output json

步驟 B - 讀取當前 RevenueCat 目錄 (MCP)

使用以下 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

步驟 C - 建立映射計畫

將 ASC 產品類型映射至 RevenueCat 產品類型：

  • 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

建議的權益（entitlement）策略：

  • 訂閱項目：每個訂閱組使用一個權益（或由使用者提供明確映射）
  • 非消耗型 IAP：每個產品使用一個權益
  • 消耗型 IAP：預設不設定權益，除非使用者主動要求

步驟 D - 確保補齊缺失的 ASC 項目（若有要求）

在執行寫入前，請先解析每個父階層與版本。比對組別時請使用精確的 referenceName，比對產品時請使用 productId；絕不可將顯示名稱視為唯一身份。當資源已存在時，請重用其標準 ID；僅在完整分頁讀取後確認缺失時，才執行建立指令。能完成 RevenueCat 產品映射，並不代表對應的 ASC 訂閱項目已具備送審資格（review-ready）。

# 透過精確匹配 referenceName 來解析 GROUP_ID。
asc subscriptions groups list --app "APP_ID" --paginate --output json
# 當且僅當完整分頁列表中完全無匹配項時：
asc subscriptions groups create --app "APP_ID" --reference-name "Premium" --output json
# 若找到一個匹配項，重用其 ID。若找到多個匹配項，請停止執行並要求明確指定 GROUP_ID。

# 透過 GROUP_ID 內精確匹配 productId 來解析 SUB_ID。僅在父階層缺失、或明確核可要對同一 productId 進行比對對齊時才執行 setup。
asc subscriptions list --group-id "GROUP_ID" --paginate --output json
# 當且僅當完整分頁列表中完全無匹配項時，執行 setup：
asc subscriptions setup \
  --app "APP_ID" \
  --group-id "GROUP_ID" \
  --reference-name "Monthly" \
  --product-id "com.example.premium.monthly" \
  --subscription-period ONE_MONTH \
  --review-screenshot "./review.png" \
  --price "3.99" \
  --price-territory "USA" \
  --territories "USA" \
  --no-verify \
  --output json
# 若找到一個匹配項，重用其 ID。若找到多個匹配項，請停止執行並要求明確指定 SUB_ID。
# 僅在明確核可比對對齊時，才對已存在的 SUB_ID 重新執行 setup。

# 解析此審查生命週期中唯一的可變訂閱組版本。
asc subscriptions groups versions list --group-id "GROUP_ID" --state PREPARE_FOR_SUBMISSION --paginate --output json
# 當且僅當列表無任何匹配時：
asc subscriptions groups versions create --group-id "GROUP_ID" --output json
# 若找到一個匹配項，重用 .data[0].id。若找到多個匹配項，請停止執行並要求明確指定 GROUP_VERSION_ID。

# 解析 GROUP_VERSION_ID 上的 en-US 本地化設定。僅在缺失時建立；若已存在但數值不同則更新已解析的本地化 ID。
asc subscriptions groups versions localizations list --version-id "GROUP_VERSION_ID" --paginate --output json
asc subscriptions groups versions localizations create --version-id "GROUP_VERSION_ID" --locale "en-US" --name "Premium" --output json
asc subscriptions groups versions localizations update --id "GROUP_LOC_ID" --name "Premium"

# 解析此審查生命週期中唯一的可變訂閱項目版本。
asc subscriptions versions list --subscription-id "SUB_ID" --state PREPARE_FOR_SUBMISSION --paginate --output json
# 當且僅當列表無任何匹配時：
asc subscriptions versions create --subscription-id "SUB_ID" --output json
# 若找到一個匹配項，重用 .data[0].id。若找到多個匹配項，請停止執行並要求明確指定 SUBSCRIPTION_VERSION_ID。
asc subscriptions versions localizations list --version-id "SUBSCRIPTION_VERSION_ID" --paginate --output json
asc subscriptions versions localizations create --version-id "SUBSCRIPTION_VERSION_ID" --locale "en-US" --name "Premium Monthly" --description "Unlock all premium features." --output json
asc subscriptions versions localizations update --id "SUBSCRIPTION_LOC_ID" --name "Premium Monthly" --description "Unlock all premium features."

# 回讀上述選定的精確版本，隨後執行最終的嚴格驗證器。
asc subscriptions groups versions localizations list --version-id "GROUP_VERSION_ID" --paginate --output table
asc subscriptions versions localizations list --version-id "SUBSCRIPTION_VERSION_ID" --paginate --output table
asc validate subscriptions --app "APP_ID" --strict --output table

# 透過精確匹配 productId 來解析 IAP_ID。
asc iap list --app "APP_ID" --paginate --output json
# 當且僅當完整分頁列表中完全無匹配項時：
asc iap create \
  --app "APP_ID" \
  --type NON_CONSUMABLE \
  --ref-name "Lifetime" \
  --product-id "com.example.lifetime" \
  --output json
# 若找到一個匹配項，重用其 ID。若找到多個匹配項，請停止執行並要求明確指定 IAP_ID。

# 解析此審查生命週期中唯一的可變 IAP 版本。
asc iap versions list --iap-id "IAP_ID" --state PREPARE_FOR_SUBMISSION --paginate --output json
# 當且僅當列表無任何匹配時：
asc iap versions create --iap-id "IAP_ID" --output json
# 若找到一個匹配項，重用 .data[0].id。若找到多個匹配項，請停止執行並要求明確指定 IAP_VERSION_ID。
asc iap versions localizations list --version-id "IAP_VERSION_ID" --paginate --output json
asc iap versions localizations create --version-id "IAP_VERSION_ID" --locale "en-US" --name "Lifetime" --description "Unlock all premium features." --output json
asc iap versions localizations update --localization-id "IAP_LOC_ID" --name "Lifetime" --description "Unlock all premium features."
asc iap versions localizations list --version-id "IAP_VERSION_ID" --paginate --output table

上述每組相鄰的建立/更新配對皆為條件觸發，而非盲目按順序執行的動作：當列表中無匹配時進行建立、當解析出匹配但數值不符合時進行更新、若已完全匹配則不執行任何動作。請從建立回應的 .data.id 或前述列表回應的 .data[].id 擷取作為後續指令使用的標準 ID。針對每個版本列表，若 PREPARE_FOR_SUBMISSION 匹配數為 0 代表需要建立；為 1 代表重用該 ID；大於 1 則必須停止並要求使用者明確選擇版本 ID。切勿為了消除歧義而逕自建立新版本：實測顯示，刪除父項目並無法可靠地級聯（cascade）刪除其下屬的 IAP 或訂閱版本。

subscriptions setup 負責完成父項目、App Review 截圖傳送、完整的 App Store 定價矩陣及銷售可用性設定。版本範疇指令則負責完成 RevenueCat 無法處理的訂閱組與訂閱項目本地化設定。請確保銷售可用性僅限於要求的地區；定價部分仍需符合 Apple 完整的等值地區矩陣。在此拆分工作流程中，使用 --no-verify 是有意的設計，因為最終驗證必須等到版本元資料（metadata）建立完備後才能進行；顯式回讀與驗證器即為最終的把關關卡。

若現有透過 API 建立的訂閱項目即使選定的基準價格未變，狀態仍維持 MISSING_METADATA，請帶入相同 setup 輸入參數並附加 --repair 重新執行。Repair 會以原子化（atomically）方式重建並重新儲存完整的等值價格矩陣，而非發送重複的單一價格 POST。

針對每個解析出的 ASC 訂閱項目，在建立或關聯其 RevenueCat 產品前，皆必須通過此最終關卡。即使該訂閱項目及其選定版本在完全未寫入 ASC 的情況下被重用，在完成最終 ASC 比對對齊後仍必須執行此檢查：

mkdir -p "./audit"
asc validate subscriptions --app "APP_ID" --strict --output json --pretty \
  > "./audit/subscriptions-validation.json"

針對每個解析出的 ASC IAP，在建立或關聯其 RevenueCat 產品前，皆必須通過此 IAP 關卡。即使該 IAP 及其選定版本在完全未寫入 ASC 的情況下被重用，在完成最終 ASC 比對對齊後仍必須執行此檢查：

mkdir -p "./audit"
asc validate iap --app "APP_ID" --strict --output json --pretty \
  > "./audit/iap-validation.json"

這兩條指令為嚴格的映射把關關卡（mapping gates），而非寫入後的冒煙測試（smoke tests）。當驗證報告出現警告、錯誤、MISSING_METADATA、審查截圖狀態非 COMPLETE、或定價覆蓋範圍不完整/未經驗證時，切勿映射任何解析出或重用的訂閱項目。當 IAP 驗證器回報警告或錯誤時，亦切勿映射任何解析出或重用的 IAP。無寫入動作的審核或套用執行，仍必須執行相應的關卡，並確保在建立或關聯 RevenueCat 產品前取得零錯誤回傳狀態碼（zero exit status）。直接重導向可保留每個驗證器的回傳狀態碼。請妥善保留 ./audit/subscriptions-validation.json 與 ./audit/iap-validation.json 作為最終審計依據。

步驟 E - 確保 RevenueCat 應用程式與產品完備

使用 MCP：

  • 若缺失則建立應用程式：mcp_RC_create_app
  • 建立產品：mcp_RC_create_product
    • store_identifier = ASC productId
    • app_id = RevenueCat app ID
    • type 來自上述映射關係

步驟 F - 確保權益與關聯設定完備

使用 MCP：

  • 列出/建立權益：mcp_RC_list_entitlements、mcp_RC_create_entitlement
  • 關聯產品：mcp_RC_attach_products_to_entitlement
  • 驗證關聯：`mcp_RC_get_products_from_entitleme

<!-- truncated for translation batch; full body continues in source -->