Запуск A/B-тестов из CLI
Adapty CLI запускает обычные A/B-тесты пейволов или флоу прямо из терминала — в рамках топика adapty ab-tests. Вы можете создать тест как черновик, запустить его на плейсменте для одной аудитории, остановить с указанием победителя, заменить активный тест изменённым, архивировать старые тесты и читать результаты каждого варианта.
Используйте это, чтобы дать AI-агенту возможность управлять тестами, написать скрипт для тестирования в нескольких приложениях или запускать и останавливать тест, не открывая дашборд.
Обычный тест распределяет пользователей одной аудитории на одном плейсменте между двумя и более пейволами или между двумя и более флоу. Чтобы запустить тест сразу на нескольких плейсментах, используйте кросс-плейсментный тест в дашборде. Чтобы прочитать результаты, например вероятность быть лучшим вариантом, используйте команды ab-tests metrics. Те же результаты в дашборде описаны в разделе Результаты и метрики A/B-тестов. Чтобы посмотреть аналитику по пользователям конкретного теста, отфильтруйте команды аналитики по измерению A/B tests из adapty analytics catalog.
Перед началом работы
Раздел ab-tests использует тот же процесс установки и авторизации, что и остальные части CLI. Если вы ещё не настроили это, выполните шаги 1 и 2 из руководства по быстрому старту. Для работы с разделом требуется CLI версии 0.14.0 или выше, а команды ab-tests metrics — версии 0.18.0 или выше. Чтобы узнать вашу версию, выполните adapty --version.
Каждая команда принимает UUID приложения в параметре --app. Чтобы найти его, выполните:
adapty apps list
Тест использует уже существующий контент:
- Флоу: Флоу участвует в тесте только после публикации. Черновик флоу или флоу с неопубликованными изменениями не будет принят. Чтобы опубликовать флоу, выполните
adapty flows publish. - Пейволы: Чтобы создать пейвол из продуктов, которые уже есть в Adapty, выполните
adapty paywalls create. Чтобы задать пейволу новый дизайн, используйте Paywall Builder. - Плейсменты: Тест пейвола запускается на плейсменте для пейволов, тест флоу — на плейсменте для флоу. Чтобы создать плейсмент, выполните
adapty placements create. Приложение ничего не покажет из нового плейсмента, пока в коде не будет реализовано его получение. - Сегменты: Чтобы запустить тест только для части пользователей, сначала создайте сегмент с помощью
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 у варианта остаётся пустым, если вы его не задали.
Создайте A/B-тест
Новый тест — это черновик. Черновик не виден пользователям, поэтому создавать и изменять его можно в любое время.
-
Найдите 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 с идентификатором сегмента:
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 перенесёт аудиторию в этот плейсмент. Тест типа All users переместить нельзя.
Читаем результаты
Узнайте, как каждый вариант теста себя показывает, с помощью команд ab-tests metrics. Каждая из них принимает параметр --type: тип, который возвращает ab-tests get, — paywall или flow. Если тип не совпадает с тестом, команда вернёт ошибку.
Чтобы увидеть, какой вариант лидирует, посмотрите статистику за всё время теста:
adapty ab-tests metrics total <test-id> --app <app-id> --type flow
Каждый вариант показывает свой вес, доход, покупки, просмотры, вероятность быть лучшим (P2BB %) и диапазон дохода на 1 000 уникальных зрителей. Флоу-тест ровно с двумя вариантами также отображает p-значение. Ознакомьтесь с лидером, прежде чем остановить тест.
- P2BB — это вероятность (в процентах), что вариант является лучшим по выручке на одного просмотра. Если P2BB равен
0у всех вариантов — значит, он не вычислен. Если P2BB равен0у одного варианта, а у другого выше0— это реальный0. Если у всех вариантов одинаковый P2BB и ни по одному нет покупок — значит, он тоже не вычислен. Если ни по одному варианту нет просмотров — результата нет. - Диапазон — это 99%-й диапазон выручки на 1 000 уникальных просмотров: нижняя граница, среднее и верхняя граница. Если платящих пользователей на варианте меньше 50 — диапазон принимает значения
0, среднее и два среднего. Если платящих нет —0,0и0. - P-value рассчитывается только для теста флоу ровно с двумя вариантами. В остальных случаях поле пустое или равно
nullв--json.
Чтобы сравнить несколько тестов одного типа, используйте ab-tests metrics list. Чтобы посмотреть варианты за период, используйте ab-tests metrics get. P2BB периода в get никогда не совпадает с P2BB варианта, поэтому не выбирайте победителя на его основе.
Остановить тест
stop завершает тест. Вы выбираете, что будут видеть пользователи его аудитории после остановки. Передайте ровно один из этих флагов:
| Флаг | После остановки |
|---|---|
--winner <id> | Вся аудитория видит один вариант теста. Передайте ID пейвола или ID флоу этого варианта. |
--other <id> | Вся аудитория видит пейвол или флоу, которого не было в тесте, того же типа, что и тест. |
--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, варианты не в формате JSON-массива, вариант без ID или с нецелым весом, указаны оба флага или ни одного из --paywalls и --flows, либо два варианта остановки. | Исправьте флаг, указанный в сообщении. |
| 3 | Вы не вошли в систему, или у вашего пользователя Adapty нет доступа к приложению. | Войдите с помощью adapty auth login и найдите ID приложения в adapty apps list. |
| 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, или используйте replace. |
AB Test from default audience can not be stopped. | Для остановки A/B-теста на аудитории «Все пользователи» нужно указать пейвол или флоу: используйте --winner или --other. |
AB Test to stop must be live. | Остановить или заменить можно только активный тест. |
Live Ab Test can not be deleted. | Сначала остановите тест, затем архивируйте его. |
Справочник команд
Каждая команда принимает --app — UUID приложения из adapty apps list. Каждая команда, кроме list, принимает ID теста в качестве аргумента.
ab-tests list
| Flag | Required | Description |
|---|---|---|
--type | No | flow (по умолчанию) или paywall. |
--state | No | live, draft, completed, inactive или archived. |
--placement | No | Только тесты для указанного плейсмента (ID). Повторите флаг для нескольких плейсментов. |
--segment | No | Только тесты, которые выполняются именно для этого сегмента (ID). Повторите флаг для нескольких сегментов. |
--search | No | Только тесты, в названии которых содержится указанный текст. |
--page | No | Номер страницы. По умолчанию: 1. |
--page-size | No | Тестов на странице, не более 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). Пейвол-тест требует плейсмент типа paywall, флоу-тест — плейсмент типа flow. |
--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
| Flag | Required | Description |
|---|---|---|
--yes, -y | Нет | Архивировать без подтверждения. Обязательно при использовании --json или в пайпе. |
ab-tests metrics total
Показывает каждый вариант за всё время существования теста. См. Чтение результатов.
| Флаг | Обязательный | Описание |
|---|---|---|
--type | Да | paywall или flow, как показывает ab-tests get. |
ab-tests metrics list
Показывает lifetime-метрики нескольких тестов одного типа: строку Total для каждого теста и строку для каждого варианта. Для варианта в тесте пейволов CLI показывает только среднее значение диапазона, без нижней и верхней границ. Не принимает аргумент с ID теста.
| Флаг | Обязателен | Описание |
|---|---|---|
--type | Да | paywall или flow. |
--ids | Да | ID тестов. Разделяйте запятыми или передавайте флаг несколько раз. |
--csv | Нет | Вывести CSV вместо таблицы. Нельзя использовать вместе с --json. |
ab-tests metrics get
Показывает метрики одного теста за период — с вариантами и уровнями доступа под ними, как на странице результатов дашборда. Для теста пейволов требуются --date-from, --date-to и --date-type. Тест флоу без указания дат возвращает данные за всё время.
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-теста — как читать результаты и выбирать победителя.