版位与市场细分命令

这些 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 必须且只能传其中一个,同时传入或都不传均会报错。

Warning

--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)。将所有目标受众替换为单个默认目标受众
Warning

传入 --paywall-id 会覆盖版位上的所有目标受众,特定市场细分的目标受众将被移除。若要保留它们,请使用 --audiences 并将所有需要保留的条目一并传入。

目标受众结构

--audiences 参数接受一个 JSON 数组,每个条目包含:

字段类型描述
content_typestring每个条目必填。"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_idsstring[]此目标受众所针对的市场细分 ID。长度为 0 或 1。空数组表示默认目标受众——即未匹配任何其他市场细分的用户的兜底受众
paywall_idstring向此目标受众用户展示的付费墙 ID(UUID)。当 content_type 为 "paywall" 时必填
flow_idstring向此目标受众用户展示的流程 ID(UUID)。当 content_type 为 "flow" 时必填
ab_test_idstring针对此目标受众用户运行的 A/B 测试 ID。四种 A/B 测试内容类型均必填
ab_test_titlestringA/B 测试标题。只读:写入时 API 会忽略此字段
prioritynumber从 0 开始,在版位内唯一。目标受众按从低到高的顺序依次评估;默认目标受众必须具有最高优先级值

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

Warning

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}]'

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

  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>'

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否市场细分描述
Warning

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 主题、全局标志和分页标志。