从 CLI 运行 A/B 测试
Adapty CLI 通过 adapty ab-tests 命令,让你直接在终端中管理付费墙或流程的 A/B 测试。你可以将测试创建为草稿、在某个版位的某个目标受众上启动测试、指定获胜者并停止测试、用修改后的版本替换正在运行的测试、归档旧测试,以及查看每个实验变体的结果。
无论是让 AI 代理自动运行测试、在多个应用中批量执行测试脚本,还是不打开看板直接启动或停止测试,都可以使用该工具。
普通测试会将某个版位的一个目标受众的用户分配到两个或多个付费墙,或两个或多个流程之间。若要跨多个版位运行测试,请在看板中使用跨版位测试。若要读取结果(例如”最优概率”),请使用 ab-tests metrics 命令。看板中相同的结果说明请参阅 A/B 测试结果与数据指标。若要读取某个测试用户的分析数据,请通过 adapty analytics catalog 中的 A/B tests 维度对分析命令进行筛选。
开始之前
ab-tests 主题与 CLI 其他部分使用相同的安装和登录方式。如果尚未完成配置,请按照快速入门指南中的步骤 1 和 2 操作。该主题需要 CLI 0.14.0 或更高版本,ab-tests metrics 命令需要 0.18.0 或更高版本。运行 adapty --version 可查看当前版本。
每个命令都需要通过 --app 传入应用的 UUID。运行以下命令可查找:
adapty apps list
A/B 测试使用已存在的内容:
- 流程(Flows):流程只有在发布后才能加入测试。草稿状态或有未发布更改的流程将被拒绝。如需发布流程,请运行
adapty flows publish。 - 付费墙(Paywalls):如需使用 Adapty 中已有的产品创建付费墙,请运行
adapty paywalls create。如需为付费墙设计新样式,请使用付费墙编辑工具。 - 版位(Placements):付费墙测试在付费墙版位上运行,流程测试在流程版位上运行。如需创建版位,请运行
adapty placements create。在应用代码获取新版位之前,该版位不会向用户展示任何内容。 - 市场细分(Segments):如需仅针对部分用户运行测试,请先使用
adapty segments create创建市场细分。
有关这些命令,请参阅命令参考。
列出和读取测试
list 默认显示流程测试,除非你传入 --type paywall。要查看某个应用的所有测试,请分别执行以下命令:
adapty ab-tests list --app <app-id> --type flow --page-size 100
adapty ab-tests list --app <app-id> --type paywall --page-size 100
测试的状态包括以下几种:draft、live、completed、inactive 或 archived。
要读取某个测试及其实验分组,请运行:
adapty ab-tests get --app <app-id> <test-id>
在 get --json 中,segment_ids 表示测试的目标受众:[] 代表所有用户,null 表示尚未设置受众。每个实验变体包含其 weight 以及对应的付费墙或流程 ID。如需识别某个实验变体,请使用 paywall_title 或 flow_name。实验变体的 title 默认为空,除非你手动设置。
创建测试
新测试以草稿形式存在。草稿对任何用户均不可见,因此你可以随时创建和修改。
-
查找内容 ID,使用
adapty paywalls list或adapty flows list。 -
创建草稿,包含两个或更多实验分组。每个分组对应一个付费墙或流程,并附有权重。权重表示看到该分组的用户比例,所有权重之和必须等于 100:
adapty ab-tests create --app <app-id> --title "Annual vs monthly" \ --goal "More revenue per user" --placement <placement-id> \ --paywalls '[{"paywall_id":"<paywall-a>","weight":50},{"paywall_id":"<paywall-b>","weight":50}]'--placement为必填项。付费墙测试需要付费墙版位,流程测试需要流程版位。如需进行流程测试,请传入--flows并在每个分组中使用flow_id。分组还可以包含title字段,例如"title":"A"。 -
使用
ab-tests get查看草稿。
草稿的版位仅为计划状态。create 也可以接受计划中的目标受众,通过 --segment 或 --all-users 指定。这些计划值不会对用户产生任何影响。启动测试时,请再次将版位和目标受众传递给 start。
开始测试
开始后无法撤销。测试一旦启动,你指定的目标受众中的用户将不再看到他们当前的付费墙或流程。
要启动草稿,需指定版位和一个目标受众:--all-users,或通过 --segment 指定一个市场细分 ID:
adapty ab-tests start --app <app-id> <test-id> --placement <placement-id> --segment <segment-id>
CLI 会打印本次启动的具体操作,并在发送任何内容之前询问 Apply? [y/N]。测试运行的位置取决于版位的目标受众配置:
- 版位中已有该市场细分的目标受众(或”所有用户”):测试将在该目标受众中运行。当前在此处运行的测试将停止并进入
completed状态。 - 版位中没有该市场细分的目标受众:
start会在版位上添加一个优先级最高的新目标受众。当前属于该市场细分且匹配其他目标受众的用户将被纳入本次测试。
要使测试的优先级低于另一个目标受众,请先将该市场细分作为目标受众添加,并设置相应优先级。为其分配这些用户当前看到的付费墙或流程,然后在该目标受众上启动测试。请参阅更改目标受众优先级。
市场细分目标受众的变更最多需要 20 分钟才能传达到所有用户。
只有草稿状态的测试才能启动。如需再次运行测试,请创建新测试:先用 get 读取旧测试,再用 create 以相同的实验变体创建一个新测试。
修改测试
update 会重新提交整个测试。每次都需要传入所有参数,包括必填的 --placement。如果遗漏某个参数,Adapty 会清除对应的值,例如目标或已规划的目标受众。
adapty ab-tests update --app <app-id> <test-id> --title "Annual vs monthly, Q4" \
--goal "More revenue per user" --placement <placement-id> \
--paywalls '[{"paywall_id":"<paywall-a>","weight":70},{"paywall_id":"<paywall-b>","weight":30}]'
在实时测试中,update 仅更改标题和目标。传入的实验组、版位和目标受众必须与 get 返回的完全一致;传入其他实验组或其他版位将被拒绝。测试的开始时间保持不变,用户的实验组分配也不会改变。已完成或已归档的测试无法更改。
如需更改实时测试的实验组或权重,请使用替换操作。replace 对应看板中的 Modify 操作:
adapty ab-tests replace --app <app-id> <test-id> --title "Annual vs monthly v2" \
--placement <placement-id> \
--paywalls '[{"paywall_id":"<paywall-a>","weight":80},{"paywall_id":"<paywall-b>","weight":20}]'
正在运行的测试会停止并转为 completed 状态,其结果保留在原 ID 下。一个新的测试以新 ID 在相同目标受众上启动,Adapty 会重新为该目标受众中的每位用户分配实验变体。如果在 --placement 中传入不同的版位,Adapty 会将目标受众移至该版位。“所有用户”测试无法移动。
读取测试结果
使用 ab-tests metrics 命令读取 A/B 测试各组的表现。每个命令都需要 --type 参数:即 ab-tests get 返回的 type,值为 paywall 或 flow。若类型与测试不匹配,命令将被拒绝。
要查看哪个分组处于领先,可读取测试的完整生命周期数据:
adapty ab-tests metrics total <test-id> --app <app-id> --type flow
每个实验组均显示其流量权重、收入、购买次数、展示次数、成为最优方案的概率(P2BB %),以及每 1,000 名独立访客的收入区间。若流程 A/B 测试恰好包含两个实验组,还会额外显示 p 值。在停止测试之前,请先在此处确认领先方案。
- P2BB 是某个实验分支按每位浏览者收益计算成为最优分支的概率(百分比)。每个分支的 P2BB 均为
0表示未计算。某个分支为0而另一个分支高于0,则表示真实值为0。所有分支 P2BB 相同且任何分支均无购买记录,也表示未计算。若所有分支均无浏览量,则无结果。 - 区间 是每 1,000 名独立浏览者收益的 99% 置信区间,包含低值、均值和高值。若某分支的付费用户少于 50 人,区间则为
0、均值和两倍均值。若无付费用户,则为0、0、0。 - p 值 仅在恰好包含两个分支的流程测试中存在。否则为空,或在
--json中为null。
要比较同类型的多个测试,请使用 ab-tests metrics list。要查看某段时间内各实验组的数据,请使用 ab-tests metrics get。get 中某个时段的 P2BB 并不等于该实验组的 P2BB,因此请勿据此选出获胜者。
停止测试
stop 命令用于结束测试。你需要选择测试结束后,该目标受众的用户将看到什么内容。以下标志恰好传一个:
| 标志 | 停止后的效果 |
|---|---|
--winner <id> | 整个目标受众将看到测试某个分支的内容。传入该分支的付费墙 ID 或 flow ID。 |
--other <id> | 整个目标受众将看到一个未参与本次测试的付费墙或 flow,且类型需与测试相同。 |
--no-content | 该目标受众从版位中移除,其用户将匹配下一个符合条件的目标受众。“所有用户”测试不支持此选项。 |
adapty ab-tests stop --app <app-id> <test-id> --winner <paywall-b>
测试将进入 completed 状态。如需再次测试相同的分组,请按照启动测试中的说明创建新测试。如需选择获胜方,请参阅 A/B 测试结果与数据图表。
归档测试
您可以归档任何未上线的测试。如需归档正在运行的测试,请先停止它。归档后的测试无法恢复。
adapty ab-tests archive --app <app-id> <test-id>
脚本和代理中的确认操作
start、stop、replace 和 archive 操作不可撤销,因此每个命令在发送请求前都会显示其影响。确认方式取决于命令的运行方式:
| 命令运行方式 | 执行结果 |
|---|---|
| 在终端中 | CLI 打印操作效果并询问 Apply? [y/N]。如果回答 y 或 yes,CLI 发送请求。其他任何回答,CLI 以代码 1 退出且不发送任何内容。 |
使用 --yes | CLI 无需询问直接发送请求。 |
使用 --json、在管道中或无终端时 | CLI 不发送任何内容并以代码 6 退出。错误信息会描述操作效果。 |
这样,脚本或代理就可以先了解命令的效果:先不带 --yes 运行,读取提示信息,待人工确认后再带 --yes 重新运行。
错误
| 退出代码 | 原因 | 解决方法 |
|---|---|---|
| 1 | 您在提示时输入了 y 以外的内容,未发送任何请求。 | 如需继续,请重新运行该命令。 |
| 2 | CLI 在发送前拒绝了输入:UUID 无效、arms 不是 JSON 数组、arm 缺少 ID 或整数权重、--paywalls 和 --flows 同时传入或均未传入,或指定了两个停止选项。 | 根据提示信息修正对应的参数。 |
| 3 | 您未登录,或您的 Adapty 用户无权访问该应用。 | 使用 adapty auth login 登录,并通过 adapty apps list 查找应用 ID。 |
| 4 | Adapty 拒绝了请求,消息中说明了原因。 | 请参阅 来自 Adapty 的消息。 |
| 5 | CLI 无法连接到 Adapty。 | 确认网络连接正常后重新运行命令。 |
| 6 | 某个不可撤销的命令在未传入 --yes 且无人响应的情况下运行,未发送任何请求。 | 阅读消息中的操作说明,然后加上 --yes 重新运行命令。 |
| 130 | 您在提示时按下了 Ctrl+C,未发送任何请求。 | — |
来自 Adapty 的消息
| 消息 | 处理方法 |
|---|---|
The sum of the weights must equal 100, but has N. | 调整权重,使其总和等于 100。 |
Flow(<id>) must be published before adding to AB test. | 先发布该流程,然后重新运行命令。 |
Paywalls cannot be changed in non-draft ab tests. 或 Placement cannot be changed in non-draft ab tests. | 按 get 返回的原样传入 arms 和版位,或使用 replace。 |
AB Test from default audience can not be stopped. | 面向全部用户的 A/B 测试停止后需要指定一个付费墙或流程:请使用 --winner 或 --other。 |
AB Test to stop must be live. | 只有正在运行的 A/B 测试才能被停止或替换。 |
Live Ab Test can not be deleted. | 请先停止 A/B 测试,再将其归档。 |
命令参考
每条命令都需要 --app 参数,即 adapty apps list 返回的应用 UUID。除 list 外,每条命令都需要将测试 ID 作为其参数。
ab-tests list
| 标志 | 是否必填 | 描述 |
|---|---|---|
--type | 否 | flow(默认)或 paywall。 |
--state | 否 | live、draft、completed、inactive 或 archived。 |
--placement | 否 | 仅显示该版位(ID)的测试。可重复使用该标志以指定多个版位。 |
--segment | 否 | 仅显示针对该市场细分(ID)运行的测试。可重复使用该标志以指定多个市场细分。 |
--search | 否 | 仅显示标题包含该文本的测试。 |
--page | 否 | 页码。默认值:1。 |
--page-size | 否 | 每页显示的测试数量,最多 100 条。默认值:20。 |
ab-tests get
返回该测试及其实验变体。不接受其他标志。
ab-tests create
| 参数 | 是否必填 | 说明 |
|---|---|---|
--title | 是 | 测试标题。 |
--paywalls | 二选一 | 付费墙测试的实验组,JSON 格式:[{"paywall_id":"<id>","weight":50,"title":"A"}, …]。title 为可选字段。 |
--flows | 二选一 | 流程测试的实验组,JSON 格式,使用 flow_id 代替 paywall_id。 |
--goal | 否 | 测试目标说明。 |
--placement | 是 | 计划运行测试的版位(ID)。付费墙测试需要付费墙版位,流程测试需要流程版位。 |
--segment | 否 | 针对某个市场细分运行测试(ID)。不可与 --all-users 同时使用。 |
--all-users | 否 | 针对所有用户运行测试。 |
ab-tests update
与 create 使用相同的参数,且 --placement 为必填项。省略某个参数时,该参数会被清除。对于正在运行的测试,只能修改 --title 和 --goal。请同时传入相同的版位和目标受众。
ab-tests start
| 参数 | 是否必填 | 描述 |
|---|---|---|
--placement | 是 | 运行测试的版位(ID)。 |
--segment | 二选一 | 为某个市场细分运行测试(ID)。 |
--all-users | 二选一 | 为所有用户运行测试。 |
--yes, -y | 否 | 无需确认直接启动。使用 --json 或管道时必填。 |
ab-tests stop
| 参数 | 是否必填 | 说明 |
|---|---|---|
--winner | 三选一 | 向全部目标受众展示该实验组的付费墙或流程(ID)。 |
--other | 三选一 | 展示一个不在本次测试中的付费墙或流程(ID)。 |
--no-content | 三选一 | 从版位中移除该目标受众。对”所有用户”测试不可用。 |
--yes, -y | 否 | 跳过确认直接停止。使用 --json 或在管道中运行时必填。 |
ab-tests replace
| 标志 | 是否必填 | 描述 |
|---|---|---|
--title | 是 | 新测试的标题。 |
--placement | 是 | 新测试的版位(ID)。使用不同的版位会将目标受众移至该版位。 |
--paywalls 或 --flows | 是 | 新测试的实验变体,用法与 create 相同。 |
--goal | 否 | 新测试的目标说明。 |
--yes, -y | 否 | 不询问直接替换。与 --json 一起使用或在管道中使用时必填。 |
新测试会继承被替换测试的目标受众,因此 replace 不接受目标受众标志。
ab-tests archive
| 标志 | 是否必填 | 描述 |
|---|---|---|
--yes, -y | 否 | 无需确认直接归档。在使用 --json 或管道时必须指定。 |
ab-tests metrics total
显示测试整个生命周期内每个实验变体的数据。请参阅读取结果。
| 参数 | 是否必填 | 说明 |
|---|---|---|
--type | 是 | paywall 或 flow,与 ab-tests get 显示的一致。 |
ab-tests metrics list
显示多个同类测试的全生命周期数据图表:每个测试一行 Total 汇总,以及每个分组各一行。对于付费墙测试的分组,CLI 仅显示区间均值,不显示上下界。该命令不接受测试 ID 参数。
| 参数 | 是否必填 | 说明 |
|---|---|---|
--type | 是 | paywall 或 flow。 |
--ids | 是 | 测试 ID。用逗号分隔,或重复使用该参数。 |
--csv | 否 | 输出 CSV 格式而非表格。不能与 --json 同时使用。 |
ab-tests metrics get
显示某个测试在指定时段内的数据指标,包含各实验分组及其下的访问等级,与看板结果页面一致。付费墙测试需要提供 --date-from、--date-to 和 --date-type。流程测试若不传日期,则返回全生命周期数据。
付费墙测试中某时段的 P2BB 是从该时段起始日起的累计值,因此在无浏览量的日期其数值保持不变。对于流程测试,P2BB 则为该时段的当期值。
| 参数 | 是否必填 | 说明 |
|---|---|---|
--type | 是 | paywall 或 flow。 |
--date-from | 付费墙测试必填 | 时间段的第一天(含当天),格式为 YYYY-MM-DD。 |
--date-to | 付费墙测试必填 | 时间段的最后一天(含当天),格式为 YYYY-MM-DD。 |
--date-type | 付费墙测试必填 | 时间段所对应的日期类型:purchase_date 或 profile_install_date。浏览量按浏览日期统计,因此两者结果相同。 |
--granularity | 否 | 将时间段拆分为数据点:day、week、month、quarter 或 year。 |
--group-by | 否 | 按 country 或 store 拆分各实验组。若不指定,则默认按产品拆分。 |
--filter | 否 | 仅保留指定过滤键对应值的数据,格式为 key=value,可重复使用。键和值来自 ab-tests metrics values,用法与 flows metrics get 相同。 |
--timezone | 否 | 时间段数据点所使用的 IANA 时区,例如 Europe/Berlin。若不指定,Adapty 将使用应用时区。 |
--depth | 否 | 打印树的层级数,默认值为 1。--json 和 --csv 始终输出完整树结构。 |
--csv | 否 | 以 CSV 格式输出,而非表格格式。不可与 --json 同时使用。 |
ab-tests metrics values
列出 ab-tests metrics get --filter 接受的筛选键和值。输出格式与 flows metrics values 相同。
| 参数 | 是否必填 | 描述 |
|---|---|---|
--type | 是 | paywall 或 flow。 |
下一步
- A/B 测试的智能体技能 — 让你的智能体规划、启动和停止测试,每个不可撤销的步骤都需要你的确认。
- 创建、运行和停止 A/B 测试 — 在看板中执行相同的步骤。
- A/B 测试结果与数据图表 — 如何解读结果并选出胜出的实验变体。