这些 Adapty CLI 命令用于管理版位、版位上的目标受众，以及目标受众所针对的市场细分。

版位

版位是您的流程、付费墙和用户引导触达用户的入口。版位的内容类型在创建时固定，因此将应用从付费墙迁移到流程意味着需要创建新版位，而非更新现有版位——migrate-placements 技能正是通过这些命令批量完成该操作的。

adapty placements list

列出应用的所有版位。

adapty placements list --app <app-id>

标志	是否必填	描述
--app	是	应用 ID（UUID）

支持分页标志。

每条记录包含 id、developer_id、title 和 is_active。is_active 为 true 表示版位处于上线状态，为 false 表示版位处于未激活状态。

adapty placements get

获取特定版位的详细信息。

adapty placements get --app <app-id> <placement-id>

参数	描述
placement-id	版位 ID（UUID）

标志	必填	描述
--app	是	应用 ID（UUID）

响应包含 id、developer_id、title、is_active 以及一个 audiences 数组。is_active 为 true 表示版位处于上线状态，为 false 表示版位未激活。每个目标受众条目包含 content_type、segment_ids、priority，以及其内容的 ID：付费墙对应 paywall_id，流程对应 flow_id，运行 A/B 测试 的目标受众对应 ab_test_id 和 ab_test_title。默认目标受众的 segment_ids: []，且优先级值最高（最后被评估）。详见 Audiences shape。

adapty placements create

创建新版位。

adapty placements create --app <app-id> --title "Main" --developer-id "main" --audiences '[{"content_type":"paywall","segment_ids":[],"paywall_id":"<paywall-id>","priority":0}]'

参数	是否必填	说明
--app	是	应用 ID（UUID）
--title	是	版位标题
--developer-id	是	在应用代码中用于请求此版位的字符串标识符
--audiences	二选一	受众条目的 JSON 数组，每个条目需显式指定 content_type。详见目标受众格式
--paywall-id	二选一	已废弃。付费墙 ID（UUID）。客户端会将其包装为单个默认目标受众

--audiences 和 --paywall-id 必须且只能传其中一个，同时传入或都不传均会报错。

adapty placements update

替换现有版位的所有字段。

adapty placements update --app <app-id> <placement-id> --title "Main" --developer-id "main" --audiences '[{"content_type":"paywall","segment_ids":[],"paywall_id":"<paywall-id>","priority":0}]'

此命令会替换版位的所有字段，包括完整的目标受众列表。

参数	描述
placement-id	版位 ID（UUID）

参数	是否必填	描述
--app	是	应用 ID（UUID）
--title	是	版位标题
--developer-id	是	在应用代码中用于请求该版位的字符串标识符
--audiences	二选一	目标受众条目的 JSON 数组，每个条目需包含明确的 content_type。详见目标受众结构
--paywall-id	二选一	已弃用。付费墙 ID（UUID）。将所有目标受众替换为单个默认目标受众

目标受众结构

--audiences 参数接受一个 JSON 数组，每个条目包含：

字段	类型	描述
content_type	string	每个条目必填。"paywall"、"flow"、"ab_test"（付费墙 A/B 测试）、"flow_ab_test"（流程 A/B 测试）、"cross_ab_test" 或 "flow_cross_ab_test"（跨版位 A/B 测试）。在付费墙版位中使用 paywall、ab_test 和 cross_ab_test，在流程版位中使用 flow、flow_ab_test 和 flow_cross_ab_test
segment_ids	string[]	此目标受众所针对的市场细分 ID。长度为 0 或 1。空数组表示默认目标受众——即未匹配任何其他市场细分的用户的兜底受众
paywall_id	string	向此目标受众用户展示的付费墙 ID（UUID）。当 content_type 为 "paywall" 时必填
flow_id	string	向此目标受众用户展示的流程 ID（UUID）。当 content_type 为 "flow" 时必填
ab_test_id	string	针对此目标受众用户运行的 A/B 测试 ID。四种 A/B 测试内容类型均必填
ab_test_title	string	A/B 测试标题。只读：写入时 API 会忽略此字段
priority	number	从 0 开始，在版位内唯一。目标受众按从低到高的顺序依次评估；默认目标受众必须具有最高优先级值

每个版位必须有且只有一个默认目标受众。

跨版位 A/B 测试条目（cross_ab_test、flow_cross_ab_test）为只读。API 在写入时会忽略这些条目，并保留已存储的值。

版位的内容类型在创建时即已固定，因此 placements update 无法将付费墙版位切换为流程版位，反之亦然。请为流程单独创建一个版位——详见为你的流程创建新版位。

CLI 在发送请求前会对每条条目进行检查。若条目缺少或包含未知的 content_type，或者缺少 content_type 所要求的 ID，则退出码为 2，且不发送任何内容。对于未知的 content_type，CLI 会打印 this CLI does not know this audience kind; update the CLI。如果该条目来自 placements get，请更新 CLI 而非删除该条目：该条目可能对应一个正在运行的 A/B 测试。

一个流程只有在发布后才能被关联。处于 draft 状态的流程，或者首次发布仍在进行中的流程，将被服务器拒绝；CLI 会识别该拒绝并以退出码 2 退出，同时打印该流程的 flows publish 命令。要发布流程，请使用 flows publish 或 Flow & Paywall Builder，然后等待其状态变为 published。

示例，包含一个定向目标受众和一个默认受众：

adapty placements update <placement-id> --app <app-id> --title "Main" --developer-id "main" \
  --audiences '[{"content_type":"paywall","segment_ids":["<vip-segment-id>"],"paywall_id":"<vip-paywall-id>","priority":0},{"content_type":"paywall","segment_ids":[],"paywall_id":"<default-paywall-id>","priority":1}]'

向所有用户提供已发布流程的版位示例：

adapty placements create --app <app-id> --title "Onboarding" --developer-id "onboarding" \
  --audiences '[{"content_type":"flow","segment_ids":[],"flow_id":"<flow-id>","priority":0}]'

要在多个版位之间替换付费墙，同时保留细分受众的路由规则：

1. 找到受影响的版位：

   adapty paywalls placements --app <app-id> <old-paywall-id>

2. 对每个版位，读取完整的 audiences 数组：

   adapty placements get --app <app-id> <placement-id> --json

3. 在客户端替换匹配的 paywall_id 值。保持其他所有条目不变，包括 A/B 测试条目。

4. 将修改后的数据写回：

   adapty placements update --app <app-id> <placement-id> --title "<title>" --developer-id "<developer-id>" --audiences '<modified-payload>'

市场细分

市场细分通过用户画像属性对用户进行分组。使用以下命令创建市场细分，或在编写版位目标受众时查找细分 ID。如需基于 Apple Ads 广告系列、广告组或关键词创建市场细分，请改用 adapty asa segments create：它会自动为您查找 Apple ID，并按 Ads Manager 的命名方式为细分命名。

adapty segments list

列出应用的所有市场细分。

adapty segments list --app <app-id>

参数	必填	描述
--app	是	应用 ID（UUID）

支持分页参数。

adapty segments get

获取特定市场细分的详细信息。

adapty segments get --app <app-id> <segment-id>

参数	描述
segment-id	市场细分 ID（UUID）

标志	是否必填	描述
--app	是	应用 ID（UUID）

响应包含 id、title、description、filters、profile_count、refresh_in_progress、created_at 和 updated_at。list 仅返回 id、title 和 description。

adapty segments create

从一个或多个过滤器创建市场细分。

adapty segments create --app <app-id> --title "US installs" --filter ip_country:IN:US --filter install_date:>=:2026-01-01

参数	是否必填	描述
--app	是	应用 ID（UUID）
--title	是	市场细分名称
--filter	是	过滤规则，可重复使用。详见过滤器语法
--description	否	市场细分描述

只有当用户匹配所有筛选条件时，才会被纳入该市场细分。响应字段与 segments get 相同。profile_count 初始值为 0，Adapty 会在市场细分创建后重新计算该值。

adapty segments update

替换现有市场细分的标题、描述和过滤条件。

adapty segments update --app <app-id> <segment-id> --title "US installs" --filter ip_country:IN:US,CA

参数	描述
segment-id	市场细分 ID（UUID）

标志	是否必填	描述
--app	是	App ID（UUID）
--title	是	市场细分标题
--filter	是	过滤规则，可重复使用。参见过滤语法
--description	否	市场细分描述

筛选语法

每个 --filter 的格式为 field:OPERATOR:value。若要匹配多个值，用逗号分隔：ip_country:IN:US,CA。

运算符	取值数量	示例
IN, NOT IN	一个或多个	ip_country:NOT IN:US,CA
>, >=, <, <=	一个	age:>:18
BETWEEN	两个	total_revenue_usd:BETWEEN:10,100
IS NULL, IS NOT NULL	无	age:IS NULL

数字请直接以纯数值传入，例如 age:>:18。Adapty 会自动将其转换为数值类型，适用于 age、total_revenue_usd 以及 float 类型的自定义属性。

如果某个筛选条件无法用上述简写形式表达，请将其以 JSON 对象的形式传入：

adapty segments create --app <app-id> --title "Adults" --filter '{"field_name":"age","operator":">","value_list":[18]}'

Adapty 会校验字段名、运算符和值类型，并对每个无效过滤条件单独报错。要查看现有过滤条件的字段名和值格式，可对看板中已创建的市场细分运行 adapty segments get --app <app-id> <segment-id> --json。

下一步

• 命令参考 — 所有 CLI 主题、全局标志和分页标志。