Команды для плейсментов и сегментов
Эти команды CLI Adapty управляют плейсментами, аудиториями на них и сегментами, на которые нацелены эти аудитории.
Плейсменты
Плейсменты — это точки, в которых флоу, пейволы и онбординги достигают пользователей. Тип контента плейсмента фиксируется при создании, поэтому переход приложения с пейволов на флоу требует создания новых плейсментов вместо обновления существующих — скилл migrate-placements управляет этими командами для выполнения операции в пакетном режиме.
adapty placements list
Список всех плейсментов приложения.
adapty placements list --app <app-id>
| Flag | Required | Description |
|---|---|---|
--app | Yes | App ID (UUID) |
--type | No | List only placements of this type: paywall, flow, or 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 и идентификатор контента: paywall_id для paywall, flow_id для flow, либо ab_test_id и ab_test_title для аудитории, в которой запущен A/B-тест. Аудитория по умолчанию имеет segment_ids: [] и наибольшее значение priority (вычисляется последней). См. раздел Структура audiences.
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. См. Структура audiences |
--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. См. Форма audiences |
--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 | ID A/B-теста, запускаемого для пользователей в этой аудитории. Обязательно для всех четырёх типов контента A/B-теста |
ab_test_title | string | Название A/B-теста. Только для чтения: API игнорирует это поле при записи |
priority | number | Нумерация с нуля, уникальна в рамках плейсмента. Аудитории оцениваются в порядке возрастания; аудитория по умолчанию должна иметь наибольшее значение |
Плейсмент должен иметь ровно одну аудиторию по умолчанию.
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, завершает выполнение с кодом 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-тестов. -
Запишите изменённый payload обратно:
adapty placements update --app <app-id> <placement-id> --title "<title>" --developer-id "<developer-id>" --audiences '<modified-payload>'
список метрик плейсментов Adapty
Показывает общие метрики нескольких флоу-плейсментов или нескольких пейвол-плейсментов — по одной строке на каждый плейсмент. Это данные из таблицы плейсментов в дашборде.
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>
| Flag | Required | Description |
|---|---|---|
--app | Yes | 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 | Да | 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, глобальные флаги и флаги пагинации.