Запуск 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-тест

Новый тест — это черновик. Черновик не виден пользователям, поэтому создавать и изменять его можно в любое время.

  1. Найдите ID контента для теста с помощью adapty paywalls list или adapty flows list.

  2. Создайте черновик с двумя или более вариантами. Каждый вариант — это один пейвол или флоу с весом. Вес — это процент пользователей, которые видят данный вариант; сумма весов должна равняться 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".

  3. Проверьте черновик с помощью ab-tests get.

Плейсмент черновика только планируется. create также может принять плановую аудиторию с помощью --segment или --all-users. Плановые значения не влияют на пользователей. Когда вы запускаете тест, передайте плейсмент и аудиторию в start снова.

Запустить тест

Warning

Запуск нельзя отменить. С момента старта тест пользователи указанной аудитории больше не видят прежний пейвол или флоу.

Чтобы запустить черновик, укажите плейсмент и одну аудиторию: --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 и ничего не отправит.
С флагом --yesCLI отправляет запрос без подтверждения.
С флагом --json, в пайпе или без терминалаCLI ничего не отправляет и завершается с кодом 6. Сообщение об ошибке описывает выполняемое действие.

Таким образом, скрипт или агент может сначала ознакомиться с результатом команды: запустить её без --yes, прочитать сообщение и повторно запустить с --yes только после того, как кто-то одобрит этот результат.

Ошибки

Код выходаПричинаЧто делать
1Вы ответили что-то отличное от y на запрос. Ничего не отправлено.Запустите команду снова, если хотели продолжить.
2CLI отклонил входные данные до отправки: неверный UUID, варианты не в формате JSON-массива, вариант без ID или с нецелым весом, указаны оба флага или ни одного из --paywalls и --flows, либо два варианта остановки.Исправьте флаг, указанный в сообщении.
3Вы не вошли в систему, или у вашего пользователя Adapty нет доступа к приложению.Войдите с помощью adapty auth login и найдите ID приложения в adapty apps list.
4Adapty отклонил запрос. Причина указана в сообщении.См. Сообщения от Adapty.
5CLI не смог связаться с 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

FlagRequiredDescription
--typeNoflow (по умолчанию) или paywall.
--stateNolive, draft, completed, inactive или archived.
--placementNoТолько тесты для указанного плейсмента (ID). Повторите флаг для нескольких плейсментов.
--segmentNoТолько тесты, которые выполняются именно для этого сегмента (ID). Повторите флаг для нескольких сегментов.
--searchNoТолько тесты, в названии которых содержится указанный текст.
--pageNoНомер страницы. По умолчанию: 1.
--page-sizeNoТестов на странице, не более 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

FlagRequiredDescription
--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.

Что дальше