adapty-cli

Adapty CLI 技能

安装

npm install -g adapty

或者无需安装即可运行：

npx adapty@latest

---

两种模式：设置（新用户，通过问答引导）和管理（现有用户，直接执行命令）。

模式：设置（初次使用 Adapty）

设置流程分为 3 个阶段：问答 → 创建 → 指引。先收集所有信息，再创建所有内容，最后告知用户接下来该做什么。

阶段 1：问答

创建任何内容之前，先检测平台，然后运行交互式问答以收集所有数据。

重要：每个问答问题都必须使用 AskUserQuestion 工具。 不要将问题作为普通文本输出。每个问题都必须单独调用 AskUserQuestion 工具，这样用户才能看到交互式输入提示。用户每回答一个问题后，再继续调用下一个 AskUserQuestion。这是必须遵守的要求。

步骤 1：检测平台 — 静默地对代码库执行 glob 匹配：

平台	Glob 模式
iOS/Swift	**/*.swift、**/Package.swift、*.xcodeproj
Android/Kotlin	**/*.kt、**/build.gradle.kts
Flutter	**/pubspec.yaml（查找 flutter: 键）
React Native	**/react-native.config.js、包含 RN 依赖的 **/app.json
Unity	**/ProjectSettings/ProjectSettings.asset
Capacitor	**/capacitor.config.ts、**/capacitor.config.json
KMP	包含 kotlin("multiplatform") 的 **/build.gradle.kts

步骤 2：提问 — 使用 AskUserQuestion 工具调用。将相关的子问题合并到一次 AskUserQuestion 调用中，尽量减少来回交互（例如，应用名称 + 平台 + Bundle ID 合并为一个问题）。提供建议默认值，让用户只需确认或选择编号。总共控制在 2-3 次 AskUserQuestion 调用，而非每个字段调用一次。

合并为 2-3 次 AskUserQuestion 调用：

AskUserQuestion 1：应用 + 产品 — 合并应用信息和产品选择：

应用名称：[根据 package.json、Info.plist 或 AndroidManifest 建议] Bundle ID：[根据检测到的配置文件建议] 平台：1. 仅 iOS / 2. 仅 Android / 3. 两者

产品：1. 月度（monthly）/ 2. 年度（annual）/ 3. 月度 + 年度 / 4. 周度（weekly）/ 5. 终身（lifetime）/ 6. 自定义

有效的 --period 值：weekly、monthly、two_months、trimonthly、semiannual、annual、lifetime。不要使用 month、year、yearly 或任何其他别名——必须使用这些确切的 API 值。 产品名称前缀：[根据应用名称建议，例如“Premium”]

收到此答案后，你就有足够的信息来生成商店产品 ID。按照 <bundle_id>.<prefix>.<period> 的约定预先填入这些 ID，并在下一个问题中提供。

AskUserQuestion 2：商店 ID + 展示位置 + 付费墙方案 — 确认生成的 ID 并收集剩余信息：

商店产品 ID — 这些 ID 必须与您在 App Store Connect / Google Play Console 中创建或即将创建的 ID 一致。 确认或修改建议的 ID：

• iOS：com.example.app.premium.monthly / com.example.app.premium.annual
• Android 产品 ID：premium_monthly / 基础方案：monthly-base（适用于 Android）

如果 iOS 和 Android 的 ID 不同，请分别填写（例如：“iOS: com.app.monthly, Android: monthly_sub / base plan: monthly-bp”）。 如果尚未创建商店产品，可以使用这些建议值——稍后在 App Store Connect / Google Play Console 中设置时使用相同的 ID 即可。

展示位置：1. 引导流程（onboarding）/ 2. 设置（settings）/ 3. 功能门控（feature_gate）/ 4. 以上全部 / 5. 自定义

付费墙 UI：1. Paywall Builder（可视化编辑器，无需编写 UI 代码）/ 2. 自定义（使用您自己的 UI）

阶段 2：创建

收集完所有答案后，先用摘要表格与用户确认计划，然后按顺序创建所有内容。创建过程中不要提问——使用已收集的数据。

重要：创建后无法完全编辑产品和付费墙（周期、商店产品 ID、基础方案 ID 都是永久的）。因此，阶段 1 的确认至关重要。

执行顺序（每一步都使用上一步的输出）：

1. adapty auth login（如果尚未通过身份验证，请使用 adapty auth whoami 检查）
2. adapty apps create --title "..." --platform ... --apple-bundle-id/--google-bundle-id ... → 保存输出：id（用作 --app）、sdk_key（用于 SDK），以及创建后显示的默认访问级别 id 和 sdk_id
3. 对每个产品执行：adapty products create --app <APP_ID> --title "..." --period ... --access-level-id <DEFAULT_AL_ID> --ios-product-id/--android-product-id ... [--android-base-plan-id ...] → 保存产品 ID。Android 订阅（非终身订阅）需要 --android-base-plan-id。Web 产品则绑定 Stripe/Paddle：--stripe-product-id+--stripe-price-id 或 --paddle-product-id+--paddle-price-id（每组参数都必须同时提供）。
4. adapty paywalls create --app <APP_ID> --title "..." --product-id <ID1> --product-id <ID2> ... → 保存付费墙 ID
5. 对每个版位执行：adapty placements create --app <APP_ID> --title "..." --developer-id ... --audiences '[{"content_type":"paywall","segment_ids":[],"paywall_id":"<PAYWALL_ID>","priority":0}]'
   • --paywall-id <PAYWALL_ID> 仍可作为旧版简写形式使用，但会输出弃用警告到 stderr。规范的默认受众格式优先使用 --audiences。

随着创建进度打印状态（例如：“已创建应用 ✓”“已创建产品‘月度’✓”）。 如果某一步失败，请停止并询问用户如何继续——不要盲目重试。

第 3 阶段：引导（交互循环）

创建所有实体后，打印包含关键值的简短摘要：

Dashboard:              https://app.adapty.io
Your SDK key:           <sdk_key from apps create>
Placement developer IDs: <list of developer_ids>
Access level SDK ID:    <sdk_id from access level, e.g. "premium">

然后使用 AskUserQuestion 询问他们接下来想做什么。每完成一个子指南后，都重复此步骤，直到用户表示已完成。 根据他们的设置回答动态生成选项：

接下来想做什么？

1. 将 SDK 集成到代码库
2. 配置 Apple 端的应用/产品 （仅限 iOS）
3. 配置 Google 端的应用/产品 （仅限 Android）
4. 在 Paywall Builder 中设计付费墙 （仅当他们选择了 Paywall Builder 时）
5. 暂时到此为止

选项 1：SDK 集成 — 打印适用于其平台和付费墙方案的快速入门链接，以及上面的关键值。使用 Context7 MCP 获取最新的 SDK 代码示例：

resolve-library-id: "adaptyteam/adapty-docs"
query-docs: topic="<platform> <feature>"

Paywall Builder 快速入门：

• iOS：https://adapty.io/docs/ios-quickstart-paywalls.md
• Android：https://adapty.io/docs/android-quickstart-paywalls.md
• Flutter：https://adapty.io/docs/flutter-quickstart-paywalls.md
• React Native：https://adapty.io/docs/react-native-quickstart-paywalls.md

自定义付费墙快速入门：

• iOS：https://adapty.io/docs/ios-quickstart-manual.md
• Android：https://adapty.io/docs/android-quickstart-manual.md
• Flutter：https://adapty.io/docs/flutter-quickstart-manual.md
• React Native：https://adapty.io/docs/react-native-quickstart-manual.md

选项 2：Apple 端 — 打印检查清单：

• 在 App Store Connect 中创建订阅产品，ID 为：<list ios_product_ids>
• Adapty Dashboard → App Store Connect：上传 In-App Purchase Key (.p8)，输入 Key ID、Issuer ID、Bundle ID、App Apple ID → https://adapty.io/docs/app-store-connection-configuration.md
• App Store Connect → Server Notifications V2：设置 Adapty Dashboard 中的 URL → https://adapty.io/docs/enable-app-store-server-notifications.md

选项 3：Google 端 — 打印检查清单：

• 在 Google Play Console 中创建订阅产品，ID 为：<list android_product_ids>，基本方案：<list base_plan_ids>
• Adapty Dashboard → Google Play：上传服务账号 JSON 密钥，输入 Package Name → https://adapty.io/docs/google-play-store-connection-configuration.md
• Google Play Console → RTDN：配置 Adapty Dashboard 中的 Pub/Sub 主题 → https://adapty.io/docs/enable-real-time-developer-notifications-rtdn.md

选项 4：Paywall Builder — 提供指向控制面板付费墙部分的链接和指南：https://adapty.io/docs/adapty-paywall-builder.md

显示任一选项的指南后，返回循环 — 再次使用相同的 AskUserQuestion 询问“接下来做什么？”，如果用户表示某个步骤已完成，则移除相应选项。只有当用户选择“暂时到此为止”时才停止。

---

模式：管理（现有 Adapty 用户）

对于已有 Adapty 应用且想要管理实体的用户，请参阅 references/cli-commands.md 获取完整的命令参考。

要点：

• 产品、付费墙、展示位、访问级别和细分群体命令需要 --app <APP_ID>（UUID）
• apps get <app_id> 和 apps update <app_id> 使用位置参数（不使用 --app 标志）
• 对于产品、付费墙、展示位和访问级别，get/update 使用位置资源 ID 以及 --app
• 这些实体及应用的列表支持 --page 和 --page-size；migrations list 不支持
• 所有命令都支持 --json
• 应用、产品、付费墙、展示位和访问级别使用 --title；migrations create 使用 --name
• 使用 --apple-bundle-id / --google-bundle-id（不要使用 ios/android）

迁移

有关迁移到 Adapty 的信息，请阅读 命令参考中的迁移。 服务会提供可用流程、操作 ID 和输入架构。

• 对于新应用，使用 --name 创建；对于现有应用，则像 migrations list 提供的那样，同时使用 --flow 和 --app
• 在脚本中显式传入 -m；否则，CLI 会依次使用 ADAPTY_MIGRATION，然后使用通过 use 或 create 保存的选择
• 使用 create --no-select 保留共享默认值；current 显示所选项，unuse 清除已保存的选择
• 运行操作前，使用 status --json 查看当前操作的 reads、input_schema 和 confirm
• 传入 --yes 前，请先查看 confirm；迁移命令不会显示交互式确认提示
• 每次操作后检查 migration.state，或等待其更新；退出码为 0 并不表示迁移已完成

---

Apple Ads

adapty asa 命令已包含在此 CLI 中，并列于 references/cli-commands.md 的 asa 部分； asa metrics 是归因交叉映射中由 Apple 报告的一侧。有关管理 Apple Ads 广告系列的 Agent 指南（写入规则、操作手册和垂直领域指南）位于 adaptyteam/apple-ads-cli 中的 apple-ads 技能里。读取操作（asa whoami、任何 list、 asa metrics）可直接安全运行；执行任何 asa 写入操作前，请先打开 apple-ads，因为写入操作会花费真实资金 且无法撤销。

---

应用分析

Adapty 控制面板所展示的单个应用分析数据（如收入和 MRR 图表、转化、漏斗、 留存、LTV、群组）位于只读的 adapty analytics 主题中。请参阅 references/cli-commands.md 中的 analytics 部分。查询前先发现数据：运行 adapty analytics catalog --app <APP_ID>，然后在筛选时运行 values，再运行一个数据命令。先显示总计；null 表示没有值，绝不表示零。切勿将这些数字与 attribution 数字相加。

---

归因分析

跨渠道归因分析数据（支出、安装、收入、ROAS、群组值和预测，即 归因控制面板所展示的数据）位于只读的 adapty attribution 主题中。请参阅 references/cli-commands.md 中的 attribution 部分。查询前先发现数据：依次运行 adapty attribution metrics、dimensions、 values 和 report。null 值表示无法计算，绝不表示零。

---

Adapty 概念

• Product — 订阅或一次性购买项，与商店产品 ID 对应。具有一个周期，并授予一个访问级别。
• Paywall — 展示产品的屏幕。可使用 Paywall Builder（可视化编辑器）或远程配置（自定义 JSON）。
• Placement — 应用中展示 Paywall 的位置。由 developer_id 标识。包含一个或多个受众；每个受众按优先级将某个细分群体路由到一个 Paywall。默认受众（segment_ids: []）是回退选项，且必须具有最高优先级。
• Access Level — 权限门槛（例如“高级版”）。购买产品后会授予访问级别。由 sdk_id 标识。
• Segment — 筛选规则（例如“VIP 用户”）。adapty segments list|get|create|update --app <APP_ID>；筛选条件格式为 field:OPERATOR:value[,value...]（field:IS NULL 不带值；数字使用普通格式，例如 age:>:18；类型化值使用单个 JSON 对象）。来自 Apple Search Ads 广告系列、广告组或关键词的细分群体：adapty asa segments create（使用控制面板中的名称，Apple ID 会自动解析）。将细分群体组合到 Placement 受众中，即可在同一 Placement 上向不同细分群体展示不同的 Paywall。
• Audience — Placement 内的 (segments, content, priority) 元组；content 可以是 Paywall、流程或正在运行的 A/B 测试。根据细分群体组合自动生成。CLI 通过 placements create/update 上的 --audiences JSON 结构公开受众。placements get 会显示每个受众，也包括 A/B 测试受众（content_type 为 ab_test 或 flow_ab_test，并带有 ab_test_id 和 ab_test_title；跨 Placement 测试以只读形式显示为 cross_ab_test / flow_cross_ab_test）。将 placements get 返回的列表写回时，只更改你想修改的内容：写入操作若移除或替换 A/B 测试条目，该测试将停止且不会产生胜出者；若只更改优先级，则测试会继续运行。

---

文档

• 完整文档索引：https://adapty.io/docs/llms.txt
• 单独的页面：https://adapty.io/docs/<slug>.md
• SDK 代码示例：使用包含 adaptyteam/adapty-docs 的 Context7 MCP