ads-manager

通过 Adapty CLI 使用 Apple Search Ads

读取数据和运行 automations run --dry-run 不花钱。其他所有 asa 命令都会在几秒内访问 Apple 并花费真金白银，而且创建的内容都无法删除或撤销——asa segments 除外，它会将受众写入 Adapty，不会访问 Apple（工作流 13）。

运行命令前，请先阅读工作流中提到的参考文档：

• references/asa-management.md — 广告系列、广告组、广告、关键词和关键词推荐、否定关键词、产品页面、创意、受众、自动化、变更历史。
• references/asa-metrics.md — metrics、metrics overview、search-terms list、competitors summary。

你的表达方式

用户读到的每一句话都要符合以下要求：

• 用“我”描述你做的事，用“你”描述用户做的事。 直接给出答案——数字或变更——并以一个后续步骤结尾。不加开场白，也不复述用户的请求。
• 每段最多加粗一处内容。 表格行无需加粗。
• 仅在用户需要输入或会在其他地方看到时才使用原始值——例如 Apple Ads 中显示的广告系列、广告组或关键词名称、其货币单位的金额、用户要运行的命令。实体 UUID 仅可出现在命令中。
• 变更前，准确说明哪些内容会变、哪些不会变——实体、旧值和新值——然后只询问一次。
• 提供完整且可点击的链接。 使用用户的语言回复；Apple Ads 中的名称保持与 Apple Ads 中的显示一致。

CLI

在首次调用 asa 之前解析一次 $ADAPTY，并在运行的每条命令中使用它。 全局安装的 adapty 通常版本过旧。asa 主题随 0.4.0 推出，但 ad-groups create --automated 和五个 --invoice-* 标志随 0.8.2 推出，metrics 作用域标志和 automations 操作标志随 0.8.3 推出，而 keywords recommend 随 0.8.7 推出，因此请将 0.8.7 视为此技能要求的最低版本。asa segments 在 0.9.3 之后推出，是唯一的例外：在运行工作流 13 之前，请先探测 $ADAPTY asa segments --help，而不要因此提高所有人的最低版本要求。旧版本安装会返回 unknown command 或未知标志错误，这看起来像是命令不存在，而不像 CLI 版本过旧：

adapty --version                                   # >= 0.8.7 ?  ADAPTY="adapty", done
npm i -g adapty@latest >/dev/null 2>&1 \
  && ADAPTY="adapty" \
  || ADAPTY="npx --yes adapty@latest"              # fallback: prefix not writable

安装一次即可；不要在每次调用时都用 npx 包装。 相比已安装版本的 0.07 秒，包装器每次调用会多花约 1 秒，而优化流程会调用几十次。如果全局前缀不可写，仍可使用 npx 形式；此时 --yes 不是可选项：不加它，npx 会停下来询问是否允许安装，而无头运行时没有人可以回答。

要为用户写出命令时，请将其展开为字面形式的 adapty。 他们的 shell 中没有 $ADAPTY。这和下文的 --yes 遵循相同的区分——你运行时使用变量，用户运行时使用命令名称。

在 zsh（macOS 默认 shell）中，多词的 $ADAPTY 不会拆分成多个词，因此命令会以 command not found: npx --yes adapty@latest 失败。请在同一个 shell 中运行一次 setopt shwordsplit，或完整写出 npx --yes adapty@latest。这是 shell 问题，绝不代表 CLI 或命令不存在。

只有在 --help 确认某个 asa 命令不可用后，才能将其声明为不可用——切勿根据你从别处看到的版本号来判断。此技能依据的版本是 @latest，但某条命令可能仍处于 beta 阶段，尚未包含在正式版本中，因此在认定该功能尚未发布前，请先尝试一次 npx --yes adapty@beta asa <topic> --help。

账户概览

• $ADAPTY asa whoami — 公司、访问授权方式、Apple 连接状态，以及公司在 limits 下的有效请求额度。请先运行此命令。access_source: trial 在试用结束前的行为与订阅相同；试用结束后，每个数据命令都会返回 402。
• $ADAPTY asa connect [--no-wait] — 输出 Apple 授权链接并等待；--no-wait 会立即返回。
• $ADAPTY asa orgs list — ASA 组织。每行包含两个不可互换的标识符：internal_id 是 UUID，campaigns create 使用 --org 指定它；接受范围筛选的列表命令使用 --campaign-group 指定它。org_id 是 Apple 的数字 ID，以上两种命令都会拒绝该 ID。--org 仅适用于 campaigns create；没有任何列表命令接受它。每行的 payment_model（LOC/PAYG）决定该组织中的广告系列是否需要 Invoicing Options。
• $ADAPTY asa apps list — 在 Apple Search Ads 中推广的应用。每行包含两个不可互换的标识符：Apple 的数字 adam-id（--adam-id）和 ASA 应用 UUID（--app）。
• 以上两个命令和 automations list 只支持分页，不支持范围筛选。
• 范围由令牌所属的公司决定。没有任何 asa 命令可通过 --app 选择范围；--app 仅用于列表筛选。asa segments 是例外：此处的 --app 指要写入细分的 Adapty 应用，可通过 $ADAPTY apps list 获取；切勿使用 asa apps list 输出的 UUID。
• 402 ads_manager_subscription_required — 没有 Ads Manager 订阅。404 — 不属于他们，或不存在。
• 读取操作可使用 --json 输出机器可读内容；使用 --json 执行写入操作会被拒绝并以 2 退出。 每个列表命令都支持 --page（默认值为 1）和 --page-size（默认值为 100，最大值为 1000）；建议一次获取较大页面，而不是循环分页。
• ADAPTY_ASA_API_URL 可覆盖 ASA 基础 URL，且独立于 ADAPTY_API_URL。

两种模板

填好每个槽位。无法从阅读资料中填入的槽位，就要询问，而不是省略。

$ADAPTY asa <topic> list --<filter-from-that-list-s-matrix-row> <id-from-a-previous-list> [--status <enum>]
$ADAPTY asa <topic> <create|update|add> [<id>] <field flags> --idempotency-key <key>

范围筛选器是必填槽位，而且矩阵是它唯一的来源——阅读 references/asa-management.md 中 ## Scope filters 下该列表自己的行，并据此填写槽位。你在创建命令或其他列表命令中看到的标志，不是此列表的筛选器：--org 属于 campaigns create，而所有支持范围筛选器的列表命令，其对应选项是 --campaign-group。会话中第一次列出时就必须填写，与第五次列出时一样——筛选器会改变服务端排序的查询，而分页大小只会改变你看到多少错误答案。

用户分别提到的两个实体，需要分别查询。“表现最佳的广告系列”和“品牌广告组”并非父子关系，除非用户明确这样说。分别按名称解析（ad-groups list --search <name>），绝不要用解析其中一个得到的 ID 来限定另一个查询——该筛选器会擅自断定用户未说明的关系，后续写入会落在看似合理却错误的位置，而且不会报错。若匹配项不止一个，就应该询问，而不是自行选择。

--idempotency-key 是必填槽位，在一连串写入中的每次写入之间，以及一次写入中的每个批次之间，都必须使用不同的键。CLI 自动生成的键只能覆盖同一次调用中的网络重试，无法覆盖用户在结果不明确时重新运行创建步骤的情况——新调用、全新键、第二个广告系列。相关内容，以及 422 cli_idempotency_key_reuse 和 409 cli_idempotency_in_progress，请见 references/asa-management.md 中的 ## Writes and idempotency。asa segments create|update 完全不接受键——此时应通过读取来填充槽位：每次创建前，立即运行 asa segments list --campaign|--ad-group <id>。

模板中没有 --yes，因为是否需要它取决于谁来运行命令。

• 由用户运行——你是在为用户编写命令。省略 --yes。在用户的终端上，CLI 会打印确切的请求正文并等待；该提示就是用户的确认，而 --yes 是唯一会将其取消的标志。周围的文字无法恢复这个确认步骤，因此，无论是警告、STOP 块还是明确说明假设，都不能代替不加此标志。
• 由你运行——在本次会话中。先询问并取得明确同意，然后在你运行的命令后加上 --yes。

metrics、metrics overview、search-terms list 和 competitors summary 在每家公司共用一个并发池（whoami 中的 limits.metrics_inflight_limit）：429 cli_analytics_busy 表示并发池已满，429 cli_rate_limit_exceeded 表示限流窗口已满，而 429 cli_cooldown_active 表示不断升级的 5m → 30m → 3h 锁定期。503 cli_upstream_unavailable 表示 Adapty 服务不可用，而不是命令有误。请见 references/asa-metrics.md 中的 ## The analytics pool。

一个问题，一次调用

由服务端汇总并排序。开始操作前，先确定回答问题所需的单次调用。每家公司都有各自的指标预算——从 whoami 读取 limits.metrics_limit_per_minute；默认每分钟 15 次调用，每 10 秒最多 5 次（references/asa-metrics.md）。

• 总计：调用一次 metrics overview。
• 最佳或最差的 N 项：调用一次 metrics --metric <m> --order-by <metric> --page-size N；查询最差项时使用 --order asc。
• 趋势或期间比较：调用一次——按期间划分的序列已包含两个期间。
• 统计实体数量：完全不需要调用指标接口。任何列表只要设置 --page-size 1，就会返回 meta.pagination.count。
• metrics 必须指定 --metric，且所有指定的指标都会针对整个实体集计算。请明确指出要读取哪些列。（metrics overview 仍可选填此项。）
• 使用 --app、--campaign 或 --ad-group 限定 metrics 调用的范围——这些 UUID 可重复指定。这是降低调用成本的唯一方法，因为成本取决于汇总的实体数量，而非页面大小。除非调用指定了 --campaign 或 --ad-group 范围，否则会拒绝 subscribers、paid_subscribers、arppu 和 arpas。metrics overview 不接受范围标志；此时应按实体级别和时间窗口缩小范围，再将结果行与限定范围的列表中的 ID 匹配。
• 时间窗口对于分组粒度过宽时，应通过降低粒度解决，而不是拆分窗口——两个命令在按天粒度上的限制不同。metrics：按天分组时为 28 天，不按期间分组时为 90 天，按周分组时为 180 天，按月及更粗粒度分组时为 365 天。metrics overview：按天分组时为 90 天，其余限制相同。一整年的数据只需在一次调用中使用 --group-by month（或 --period-unit month），而不是调用四次、每次查询 90 天。
• metrics 页面的细分行数上限为 limits.max_breakdown_rows_per_page（实体 × 国家/地区 × 期间；默认 5000）；超过上限时调用会失败并返回 422 cli_response_too_large。应降低粒度、缩小范围或限定调用范围——切勿循环请求更小的页面。按天粒度时，拒绝响应会给出适用的 page[size]：直接使用该数字，不要自行计算。
• 如果 --by-days 窗口超出 meta.max_valid_day，则该时间段尚不可查询，返回的会是最后一个实际数据点的数值。切勿将其报告为平台期；比较时只使用所有行都已达到的时间窗口。
• 金额使用的是广告系列组的货币，而不是 USD——陈述或比较金额前，请先从 orgs list 读取货币。

切勿在客户端对多个页面求和，切勿按期间逐次调用，也切勿加入用户未要求的比较——如有需要，可在回答中提出。

禁止事项

• 绝不要自行判定最高级结论。“表现最佳”“表现落后”“ROAS 糟糕”都属于业务定义，而不是查询结果。先说清指标和时间范围，征得用户对该定义的认可，再进行操作。
• 绝不要在聊天中先说明变更内容之前就进行写入——涉及哪个广告系列、多少预算、多少个关键词。
• **单次 keywords add 或 negative-keywords add 调用中，绝不要添加超过 15 个关键词。**上限是 100 个；实际应控制在 15 个。
• **遇到 429 绝不要反复重试。**CLI 已按 Retry-After 指定的时长等待，并重试了一次；因此传到你这里的 429 意味着配额确实已用尽。减少调用次数，或告知用户何时重试。
• **绝不要猜测或试探指标名称。**指标词汇表位于 references/asa-metrics.md。名称错误时，系统会列出所有有效名称；拼写错误会浪费一次调用——通过调用来试出正确名称，就是失误。队列指标按其展开后的名称排序：使用 --order-by gross_roas，而不是 --order-by roas。
• **绝不要编造 id、adam-id、预算或出价。**从对应列表中读取，或直接询问。
• **绝不要在用户要运行的命令中加入 --yes。**这会跳过用户本应查看的预览。只有在获得明确同意后，才可在自己运行的命令中使用 --yes。
• 绝不要让 Max Conversions 广告系列缺少其自动广告组，也绝不要在 LOC 组织中启动广告系列时漏掉五个 --invoice-* 标志。这两种情况都会顺利创建，但之后永远不会投放；直到有人查看 serving_status，故障看起来都像是广告系列已正常启动。
• 绝不要在未先查看 --preview 的情况下提交转换后的模板，也绝不要因为批量操作超时就重新提交。--timeout 只会结束轮询，不会终止操作；重新提交会创建两份结构，而且 asa 主题中没有任何工具可以删除其中任何一份。
• 绝不要编写拆除操作。asa 主题中没有删除功能，也无法撤销；--status PAUSED 是唯一的停止方式。
• 绝不要在先列出之前创建细分。asa segments create 没有幂等键，因此在结果不明确时重新运行，会多创建一个 [ASA] Campaign: <name>，并将相同用户导流过去——之后各版位对哪个细分算数也会意见不一。
• **绝不要重命名用户未要求重命名的 [ASA] 细分。**前缀是仪表板和 asa segments list 查找该细分的依据；改成自定义标题后，它就会从两处消失。

自我辩解

Agent 对自己说的话	实际情况
“40 个关键词低于 CLI 每次调用 100 个的批次上限，所以这只是一轮调用，不是循环。”	没超过上限不代表安全。40 项响应中有 9 行被拒，需要进行修复；而在 15 项调用中，只需重新运行即可。
“我会默认用滚动时间范围内的 ROAS 来定义‘表现最佳’，并在第 5 步之前询问用户是否确认或更改——不过这里先给出能得出答案的命令。”	提供命令并不能获得你刚说必须先取得的同意。如果定义还需要确认，就应停在定义这一步。

红旗 — 立即停止

• 未指定范围筛选条件的 list，包括第一次 list，以及你“只是瞄一眼”的那次
• 在 orgs list、apps list 或 automations list 上使用范围筛选条件
• 使用你没有从矩阵中该列表对应的行读取的筛选条件——创建标志（例如 --org）或其他列表的筛选条件都不算
• 向用户提供的命令中带有 --yes——这会跳过用户本来要查看的预览
• 使用用户另外提及的某个实体所解析出的 id 来限定查询范围
• 一连串相互依赖的创建操作中，有创建操作没有固定 --idempotency-key
• 在一次 keywords add 或 negative-keywords add 调用中添加超过 15 个关键词——此上限不适用于 bulk-create 结构，其预览本身就是审核环节
• 未查看预览就提交 bulk-create --from-file，或将 --org-id 填成 internal_id UUID，而不是数字 org_id
• 根据你自己对“最好”“表现差”或“糟糕”的定义选择目标并执行写入
• 使用 --order-by-day，但同一次调用中没有对应的 --by-days 窗口
• 将从 asa apps list 复制的 --app 用于 asa segments——那是 Apple 端的应用，不是 Adapty 的应用
• 执行 asa segments create 前没有立即针对同一实体运行 asa segments list
• 对某个版位执行 update 时添加受众分群，却没有一并传回所有现有条目
• 你声明了一条规则，三条命令之后却悄悄破例

以下情况是在 CLI 端会话中观察到的，并非此技能自身的基线行为：

• 循环执行 --page 1..4 来汇总总数，而不是调用一次 overview 或使用一个较大的页面
• 花一次调用去查找哪些指标名称有效
• 添加用户没有要求的周期对比
• 遇到 429 后猜一个 sleep 值重试，而不是使用 Retry-After 的值

以上任何一种情况都意味着：停止，先阅读，再询问。

工作流

1. 了解情况。 whoami → 如果 Apple 尚未关联则执行 connect → orgs list → apps list。 以下所有操作的前置步骤。→ references/asa-management.md， ## Account and discovery。

2. 报告效果。 总计和趋势使用第一种格式；最优或最差的 N 项使用第二种格式，最差项使用 --order asc。两种格式都必须指定日期，且 metrics 必须指定 --metric——否则命令会在连接到 Apple 之前退出。只要能确定 id，就尽量使用 --app、--campaign 或 --ad-group 限定 metrics 的范围；没有 --campaign 或 --ad-group 时，不允许查询 subscribers、paid_subscribers、arppu 和 arpas。计数无需调用 metrics：任何列表使用 --page-size 1 都会返回 meta.pagination.count。--by-days 每次最多接受 16 个窗口，而 --order-by-day 只能指定其中一个值。→ references/asa-metrics.md，## Cohort windows。

$ADAPTY asa metrics overview --entity <level> --date-from <YYYY-MM-DD> --date-to <YYYY-MM-DD> [--period-unit <bucket>]
$ADAPTY asa metrics --entity <ad|ad-group|campaign|keyword> --date-from <YYYY-MM-DD> --date-to <YYYY-MM-DD> --metric <metric> [--campaign <uuid>] --order-by <metric> --page-size <n>

3. 启动营销活动。 先读取 orgs list → --org 和 apps list → --adam-id；之后每个创建操作都使用前一个操作输出的 id。顺序和密钥都不可省略。每次启动都生成一次 <run>，避免第二次启动时发生冲突。创建处于 PAUSED 状态的营销活动，验证其结构，然后通过工作流 6 启用——在此之前不会产生任何支出。自行设置 --match-type：默认值为 BROAD，这是范围最广、成本最高的定向方式。用户没有提供关键词列表？先读取一个推荐词池：keywords recommend --adam-id <adam-id> --type <brand|generic|competitor>——使用同一个 --adam-id——并向用户展示你打算添加的词项。推荐词池不包含出价或匹配类型，因此这两项由用户决定。→ references/asa-management.md，## Keywords 和 ## Writes and idempotency。

$ADAPTY asa campaigns create --org <id> --adam-id <adam-id> --name <name> --country <country-code> --daily-budget <amount> --status PAUSED --idempotency-key <run>-camp
$ADAPTY asa ad-groups create --campaign <id> --name <name> --default-bid <amount> --idempotency-key <run>-ag
$ADAPTY asa creatives list --app <app-uuid>   # → --creative-id; no creatives create exists
$ADAPTY asa ads create --ad-group <id> --creative-id <id> --name <name> --idempotency-key <run>-ad
$ADAPTY asa keywords add --ad-group <id> --text <keyword> --match-type <EXACT|BROAD> --idempotency-key <run>-kw-1   # ≤15 per call, fresh key per batch

在运行创建广告系列之前，orgs list 中的两个信息会影响创建操作。payment_model 为 LOC 时，五个 --invoice-* 标志都变为必填项——必须在同一次调用中提供全部五个，否则广告系列会创建成功，但永远不会投放。如果使用 --bidding-strategy MAX_CONVERSIONS，前两次写入就成为一个整体：只有当广告系列拥有一个通过 --automated 创建的广告组时才会投放，而该标志不能与 --default-bid 和 --start-time 一起使用。向用户询问开票信息；绝不要编造。→ references/asa-management.md，### Max Conversions campaigns 和 ### Line of credit organizations。

**4. 发掘关键词。**读取 search-terms list --ad-group <id> --date-from <YYYY-MM-DD> --date-to <YYYY-MM-DD>（日期默认是今天，因此请显式传入），然后使用 keywords add --ad-group <id> 提升带来转化的搜索词，并使用 negative-keywords add --ad-group <id> 屏蔽无效搜索词——每次调用最多 15 个，每次调用使用独立的键。→ references/asa-metrics.md，## The analytics pool，以及 references/asa-management.md。

**5. 优化。**读取 metrics --entity keyword --date-from <YYYY-MM-DD> --date-to <YYYY-MM-DD> --metric roas --metric spend --ad-group <id> --by-days 7 --by-days 90 --order-by gross_roas --order-by-day 90——--order asc 会让同一次调用返回表现不佳的关键词，而非表现出色的关键词——并使用 keywords list --ad-group <id> --status ACTIVE 获取 ID。任何写入操作之前，先向用户确认阈值。然后对表现出色的关键词使用 keywords update <ids> --bid <amount>，对表现不佳的关键词使用 keywords update <ids> --status PAUSED，并使用 campaigns update <id> --daily-budget <n> 调整支出——每项操作都使用各自的 --idempotency-key。单独确认预算与出价；这是两项独立决策。→ references/asa-metrics.md，## Cohort windows，以及 references/asa-management.md。

**6. 暂停或恢复。**广告系列、广告组和广告： update <id> --status ENABLED|PAUSED --idempotency-key <key>。关键词： update <id> [<id>…] --status ACTIVE|PAUSED --idempotency-key <key>。关键词的枚举值与其他所有实体都不同，整个接口中也没有 DISABLED。先通过指定范围的列表获取 ID。→ references/asa-management.md，## Status。

7. 自定产品页面 → 广告。product-pages sync [--adam-id <adam-id>] --idempotency-key <key> ——这是写入操作，只会排队，不会等待完成。然后执行 product-pages list --app <app-uuid> → creatives list --app <app-uuid> → ads create --ad-group <id> --creative-id <id> --name <name> --idempotency-key <key>。→ references/asa-management.md。

**8. 诊断无投放的广告或未开始的广告系列。**执行 ads get <id>，查看 serving_state_reasons；如果仍无法解释，则向上检查 ad-groups get <id> 的状态，再检查 campaigns get <id> 的状态和每日预算。广告系列也带有 serving_status 和 serving_state_reasons，其中两个原因有已知修复方法，而非仅供诊断： AUTOMATED_KEYWORDS_REQUIRED_AD_GROUP_MISSING 表示需要执行 ad-groups create --automated，而 MISSING_BO_OR_INVOICING_FIELDS 表示需要在 campaigns update 中提供五个 --invoice-* 标志。以上均为读取操作。 → references/asa-management.md。

9. 规则自动化。automations create --file rule.json --idempotency-key <key> → automations run <id> --dry-run → 使用 automations runs <id> 查看它将执行的操作 → 只有在用户看过结果后，才执行 automations update <id> --start。所有涉及出价或预算的规则都必须先进行试运行。对于 add-as-keyword-to 规则，请传入操作标志，而不要手动编写 actions[0].params——--target-ad-group、--match-type 和 --cpt-bid-type 都是必填项，API 不提供默认值；如果手写的代码块有一个键位置错误，系统仍会以 200 接受，但之后不会将关键词添加到任何位置。执行 update 时，操作标志会重新读取规则并整体写回操作，因此可能覆盖期间在控制面板中所做的编辑：请先告知用户。→ references/asa-management.md，### The add-as-keyword action flags。 10. 检查竞争对手。 competitors summary --app-ids <adam-id>,<adam-id> — 1–5 个 Apple App Store ID。覆盖每个国家/地区的上一个完整月份；没有周期或国家/地区标志。这是只读操作，与 分析共享资源池；缓存未命中时速度较慢。→ references/asa-metrics.md。

11. 一次启动多个广告系列。 对整个结构（广告系列 → 广告组 → 关键词/否定关键词/广告）执行一次 bulk-create，而不是循环执行工作流 3。使用 Apple Ads 模板时，先转换并读取模板；预览就是审核环节。 创建出的结构即便不完全正确，也无法撤销或删除。使用 JSON 时，--file - 会从标准输入读取结构。

$ADAPTY asa campaigns bulk-create --from-file <template.xlsx|keywords.csv> --org-id <numeric-org-id> --preview
$ADAPTY asa campaigns bulk-create --file <structure.json> --idempotency-key <run>-bulk
$ADAPTY asa campaigns bulk-status <operation-id>

--org-id 是 orgs list 返回的数字 org_id，而不是 campaigns create --org`` 所需的 internal_idUUID——这是整个命令集中唯一需要 Apple 数字 ID 的命令。该命令会轮询至success、partial或failed；如果结果为 partial，已成功创建的对象会保留，并列出其余对象及 Apple 给出的原因。--timeout只会结束轮询，不会终止操作，因此应使用bulk-status查看结果，而不是 重新提交。→references/asa-management.md，### Bulk operations`。

12. 谁改了它。 “是谁暂停了这个？”“为什么出价变了？”“上周有什么变动？”——先查看变更历史，再 判断是否由自动化或 Apple 导致。每次调用仅支持一个组织，且最多查询 14 天；需要 CLI 0.9.4。其 ID 筛选器使用数据行中的 Apple 数字 ID，而非 UUID；modified_by 是 Apple 用户 ID，不是电子邮件地址。 所有操作均为只读。→ references/asa-management.md，## Change history。

$ADAPTY asa change-history list --campaign-group <uuid> --date-from <YYYY-MM-DD> --date-to <YYYY-MM-DD> [--entity-type Campaign] [--event-type UPDATE] [--fields]
$ADAPTY asa change-history get <detail-id> --campaign-group <uuid>

13. 为广告系列指定专属付费墙。 来自某个广告系列、广告组或关键词的用户会看到不同的付费墙或流程—— 这正是创建细分受众的原因，因此要继续处理请求，将其配置到展示位置，而不是停留在细分受众这一步。 → references/asa-management.md，## Segments。

1. 涉及哪些实体。 用户指定名称 → 按名称解析（campaigns list --search）。按表现筛选（“我表现最好的 广告系列”）→ 这是最高级描述：明确指标和时间范围，获得确认后，通过一次排名 metrics 调用获取 ID （工作流 2）。关键词必须指定其所属广告组：--keyword 只会在且仅在一个 --ad-group 内解析。

2. 创建一个还是多个细分受众。 请先询问，因为这会决定展示位置的效果：每个广告系列各建一个细分受众， 每个广告系列就能使用自己的付费墙；多个广告系列共用一个细分受众（--campaign a --campaign b），则 它们都会使用同一个付费墙。用户说“每个”时，默认按实体分别创建。

3. 使用哪个 Adapty 应用。 $ADAPTY apps list — 这是 Adapty 应用，不是 asa apps list。如果有多个， 请询问用户。

4. 先检查，再创建，每个细分受众都如此。列表为空即可创建；如果有匹配项，则应复用该细分受众——说明 这一点，不要创建重复项。

   $ADAPTY asa segments list --app <adapty-app-uuid> --campaign <campaign-uuid>
   $ADAPTY asa segments create --app <adapty-app-uuid> --campaign <campaign-uuid>
   

   先在聊天中说明将创建的细分受众数量和标题，然后一次性请求用户确认整批操作。 保留默认的 [ASA] … 标题。

5. 正确解读结果。 新建细分受众的 profile_count: 0 是正常情况——Adapty 会在之后统计匹配的用户资料。 如果之后该数量仍为零，通常意味着 Adapty 没有这些用户的 Apple Ads 归因数据，而不是筛选条件有误； 请引导用户访问 https://adapty.io/docs/apple-search-ads，而不要重新创建细分受众。

6. 使用 audiences 技能配置。 该技能负责将细分受众添加到展示位置：新受众相对于现有细分受众的位置、 条目格式，以及用户确认的前后对比表。将细分受众 ID 和展示位置交给它。如果该受众还没有付费墙或流程， 则先用 flow-generator 创建。

创建时返回 405 表示服务尚未开放细分受众写入功能——请引导用户访问 https://adapty.io/docs/ads-manager-create-segments，通过控制面板创建相同的细分受众，然后从第 6 步继续， 使用用户在那里获取的 ID。

此处未涵盖的内容

1. 此文件及其两份参考资料是 asa 接口的权威来源。
2. $ADAPTY asa <topic> <command> --help — 查看已安装版本的准确标志语法。
3. CLI 仓库 https://github.com/adaptyteam/adapty-cli（默认分支）：先看 README.md，然后看 skills/adapty-cli/references/cli-commands.md — 这两份资料可能滞后于已安装的 CLI — 再看 src/commands/asa/**；其中，命令自身的 static flags 声明优先于任何表格，并用于解决说明文字与命令之间的分歧。

不要猜测标志、命令或 URL 路径。如果这三处都无法确认，请如实说明。

对于完全无关 asa 接口的 Adapty 问题 — 例如控制面板中的 Apple Ads 概念、归因、分析等产品相关问题 — 请使用 adapty-docs 技能查找相应页面，而不是搜索网络。