版位与市场细分命令
这些 Adapty CLI 命令用于管理版位、版位上的目标受众,以及目标受众所针对的市场细分。
版位
版位是您的流程、付费墙和用户引导触达用户的入口。版位的内容类型在创建时固定,因此将应用从付费墙迁移到流程意味着需要创建新版位,而非更新现有版位——migrate-placements 技能正是通过这些命令批量完成该操作的。
adapty placements list
列出某个应用的所有版位。
adapty placements list --app <app-id>
| 标志 | 是否必填 | 说明 |
|---|---|---|
--app | 是 | 应用 ID(UUID) |
--type | 否 | 仅列出指定类型的版位:paywall、flow 或 onboarding |
支持分页标志。
每个条目包含 id、developer_id、title、is_active 和 type。is_active 为 true 表示该版位已上线,为 false 表示未激活。type 是版位的内容类型:paywall、flow 或 onboarding。在 --json 模式下,未设置类型的版位显示 type: null。--type 标志和 type 字段需要 CLI 0.15.0 或更高版本。
adapty placements get
获取特定版位的详细信息。
adapty placements get --app <app-id> <placement-id>
| 参数 | 描述 |
|---|---|
placement-id | 版位 ID(UUID) |
| 标志 | 必填 | 描述 |
|---|---|---|
--app | 是 | 应用 ID(UUID) |
响应包含 id、developer_id、title、is_active、type 以及一个 audiences 数组。is_active 为 true 表示版位已上线,为 false 表示版位未激活。每个目标受众条目包含 content_type、segment_ids、priority,以及其内容的 ID:paywall 类型对应 paywall_id,flow 类型对应 flow_id,运行 A/B 测试的目标受众则对应 ab_test_id 和 ab_test_title。默认目标受众的 segment_ids: [],且优先级值最高(最后被评估)。详见目标受众结构。
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 必须且只能传其中一个,同时传入或都不传均会报错。
--paywall-id 已弃用,将在后续版本中移除。传入该参数时,CLI 会在 stderr 输出警告,并将该值转换为默认目标受众。新的自动化流程请使用 --audiences。
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)。将所有目标受众替换为单个默认目标受众 |
传入 --paywall-id 会覆盖版位上的所有目标受众,特定市场细分的目标受众将被移除。若要保留它们,请使用 --audiences 并将所有需要保留的条目一并传入。
目标受众结构
--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 开始,在版位内唯一。目标受众按从低到高的顺序依次评估;默认目标受众必须具有最高优先级值 |
每个版位必须有且只有一个默认目标受众。
placements update 会替换完整的目标受众列表,包括正在运行 A/B 测试的目标受众。如需保留正在运行的测试,请从 placements get 中复制对应条目到 --audiences,保持 ab_test_id 和 segment_ids 不变。若写入时移除或替换了该条目,测试将在没有胜出者的情况下终止。若将该条目移至其他市场细分,测试将重新开始;若在另一个目标受众上设置了 ab_test_id,测试将在该目标受众处启动。若仅更改优先级,测试将继续运行。CLI 不会就上述情况发出任何警告。
跨版位 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}]'
要在多个版位之间替换付费墙,同时保留细分受众的路由规则:
-
找到受影响的版位:
adapty paywalls placements --app <app-id> <old-paywall-id> -
对每个版位,读取完整的
audiences数组:adapty placements get --app <app-id> <placement-id> --json -
在客户端替换匹配的
paywall_id值。保持其他所有条目不变,包括 A/B 测试条目。 -
将修改后的数据写回:
adapty placements update --app <app-id> <placement-id> --title "<title>" --developer-id "<developer-id>" --audiences '<modified-payload>'
adapty placements metrics list
显示多个流程版位或多个付费墙版位的全周期数据指标,每个版位占一行。这是看板中版位表格的数据。
adapty placements metrics list --app <app-id> --type flow --ids <placement-id>,<placement-id>
| 标志 | 是否必填 | 说明 |
|---|---|---|
--app | 是 | 应用 ID(UUID) |
--type | 是 | 版位类型,与 placements list 显示的一致:flow 或 paywall |
--ids | 是 | 版位 ID(UUID)。用逗号分隔,或重复使用该标志 |
--csv | 否 | 输出 CSV:每个版位一行,包含版位 ID 和数值指标。不可与 --json 同时使用 |
placements metrics 命令读取版位指标页面上的数据。流程版位需要 CLI 0.15.0 或更高版本,付费墙版位需要 0.16.0 或更高版本。--type 必须与版位类型匹配:Adapty 会拒绝类型不符的版位请求,且用户引导版位没有指标数据。
每行显示版位 ID 及其浏览量、购买量、试用量和收入。对于流程版位,--json 和 --csv 包含全部 27 项指标。
付费墙版位的永久授权行没有浏览量,因此其浏览量列显示 —。该行包含 15 个数据图表,例如 purchases、revenue 和 refunds。如需读取付费墙版位的访客数据,请使用带有时间段参数的 placements metrics get。
adapty placements metrics values
列出流程版位或付费墙版位的过滤键和值:即 placements metrics get --filter 所接受的内容。
adapty placements metrics values --app <app-id> <placement-id> --type flow
| 参数 | 描述 |
|---|---|
placement-id | 版位 ID(UUID) |
| 标志 | 是否必填 | 描述 |
|---|---|---|
--app | 是 | 应用 ID(UUID) |
--type | 是 | 版位类型:flow 或 paywall |
flows metrics values 的输出格式相同:每组的顶层值是过滤键,最内层的值是该键可取的内容。若某个版位没有过滤键,则显示 No filter values.
adapty placements metrics get
以树形结构展示某个流程版位或付费墙版位的数据图表,格式与 版位数据图表 页面一致。流程版位可查看整个生命周期或指定时间段的数据;付费墙版位仅支持查看指定时间段的数据。
adapty placements metrics get --app <app-id> <placement-id> --type flow --based-on flow
| 参数 | 描述 |
|---|---|
placement-id | 版位 ID(UUID) |
| 标志 | 是否必填 | 描述 |
|---|---|---|
--app | 是 | 应用 ID(UUID) |
--type | 是 | 版位类型:flow 或 paywall |
--based-on | 是 | 树的第一层按什么拆分。流程版位可选:audience、flow 或 placement。付费墙版位可选:audience 或 paywall |
--group-by | 否 | 对于流程版位,按 country 或 store 拆分每个目标受众。对于付费墙版位,按 product、store 或 country 对产品分组 |
--date-from | 否 | 时间段的起始日期(含当天,格式 YYYY-MM-DD)。需与 --date-to 和 --date-type 一同传入 |
--date-to | 否 | 时间段的结束日期(含当天,格式 YYYY-MM-DD)。需与 --date-from 和 --date-type 一同传入 |
--date-type | 否 | 时间段所适用的日期类型:purchase_date 或 profile_install_date。需与 --date-from 和 --date-to 一同传入 |
--granularity | 否 | 将时间段拆分为若干数据点:day、week、month、quarter 或 year |
--filter | 否 | 只保留符合指定过滤键值的数据,可重复使用。详见过滤数据图表 |
--timezone | 否 | 时间段数据点所用的 IANA 时区,例如 Europe/Berlin。不传时,Adapty 使用应用时区 |
--depth | 否 | 在 Total 下打印多少层树节点,默认为 1 |
--csv | 否 | 输出 CSV 格式:整棵树的每个节点对应一行。不能与 --json 同时使用 |
对于流程版位,不带 --date-from、--date-to 和 --date-type 时,命令返回全生命周期的数据指标。如需指定时间段,三个参数必须同时传入:缺少 --date-type 时命令会以状态码 4 退出。付费墙版位始终需要这三个参数,缺少时同样以状态码 4 退出。
对于流程版位,输出内容、--depth、--json、--csv 和 --filter 的用法与 flows metrics get 相同。对于付费墙版位,用法与 paywalls metrics get 相同。例如,按应用商店对比某版位的各目标受众数据:
adapty placements metrics get --app <app-id> <placement-id> --type flow --based-on audience --group-by store \
--date-from 2026-09-01 --date-to 2026-10-21 --date-type purchase_date --depth 2
要读取付费墙版位上 A/B 测试的每个分支,可按付费墙拆分树形结构。在每个付费墙下,A/B 测试所在行显示该分支的数据:
adapty placements metrics get --app <app-id> <placement-id> --type paywall --based-on paywall \
--date-from 2026-09-01 --date-to 2026-10-21 --date-type purchase_date --depth 3
A/B 测试的整体汇总数据显示在 --based-on audience 树的独立行中。该汇总对每位用户只计一次,因此可能低于各实验组之和——同时看过两个实验组的用户会在每个实验组中各计一次。
市场细分
市场细分通过用户画像属性对用户进行分组。使用以下命令创建市场细分,或在编写版位目标受众时查找细分 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 | 否 | 市场细分描述 |
segments update 会替换整个市场细分。请传入所有要保留的筛选条件,而不仅仅是要修改的那个。如需查看当前筛选条件,请运行 adapty segments get --app <app-id> <segment-id> --json。
筛选语法
每个 --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 主题、全局标志和分页标志。