Команды для плейсментов и сегментов

Эти команды Adapty CLI управляют плейсментами, аудиториями в них и сегментами, на которые эти аудитории нацелены.

Плейсменты

Плейсменты — это точки, в которых флоу, пейволы и онбординги достигают пользователей. Тип контента плейсмента фиксируется при создании, поэтому переход приложения с пейволов на флоу требует создания новых плейсментов вместо обновления существующих — скилл migrate-placements управляет этими командами для выполнения операции в пакетном режиме.

adapty placements list

Список всех плейсментов для приложения.

adapty placements list --app <app-id>

Флаг	Обязательный	Описание
`--app`	Да	ID приложения (UUID)

Принимает флаги пагинации.

Каждый элемент содержит id, developer_id, title и is_active. is_active равно true для активного плейсмента и false для неактивного.

adapty placements get

Получить детали конкретного плейсмента.

adapty placements get --app <app-id> <placement-id>

Аргумент	Описание
`placement-id`	ID плейсмента (UUID)

Флаг	Обязателен	Описание
`--app`	Да	ID приложения (UUID)

Ответ содержит поля id, developer_id, title, is_active и массив 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: [] и наибольшее значение приоритета (оценивается последней). См. раздел Структура аудиторий.

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. Передача обоих или ни одного из них приведёт к ошибке.

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`. См. Форма audiences
`--paywall-id`	Один из двух	Устарело. ID пейвола (UUID). Заменяет все аудитории одной аудиторией по умолчанию

Warning

Передача --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`	Нумерация с нуля, уникальна в рамках плейсмента. Аудитории оцениваются в порядке возрастания; аудитория по умолчанию должна иметь наибольшее значение

Плейсмент должен иметь ровно одну аудиторию по умолчанию.

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, завершает выполнение с кодом 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>'

Сегменты

Сегменты группируют пользователей по атрибутам их профилей. Используйте эти команды для создания сегментов и поиска их 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`	Нет	Описание сегмента

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, глобальные флаги и флаги пагинации.