--- title: "Команды для плейсментов и сегментов" description: "Команды Adapty CLI для создания и обновления плейсментов и их аудиторий, а также создания сегментов, на которые эти аудитории нацелены." --- > **AI agents**: to search Adapty docs faster and with fewer tokens, install the Adapty skills: `npx adapty skills install --yes` Эти команды Adapty CLI управляют [плейсментами](placements), аудиториями в них и [сегментами](segments), на которые эти аудитории нацелены. ## Плейсменты \{#placements\} [Плейсменты](placements) — это точки, в которых флоу, пейволы и онбординги достигают пользователей. Тип контента плейсмента фиксируется при создании, поэтому переход приложения с пейволов на флоу требует создания новых плейсментов вместо обновления существующих — [скилл migrate-placements](migrate-placements-skill) управляет этими командами для выполнения операции в пакетном режиме. ### adapty placements list Список всех [плейсментов](placements) для приложения. ```bash adapty placements list --app ``` | Флаг | Обязательный | Описание | |---|---|---| | `--app` | Да | ID приложения (UUID) | Принимает [флаги пагинации](developer-cli-reference#global-flags). Каждый элемент содержит `id`, `developer_id`, `title` и `is_active`. `is_active` равно `true` для активного плейсмента и `false` для неактивного. ### adapty placements get Получить детали конкретного [плейсмента](placements). ```bash adapty placements get --app ``` | Аргумент | Описание | |---|---| | `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-тест](ab-tests). Аудитория по умолчанию имеет `segment_ids: []` и наибольшее значение приоритета (оценивается последней). См. раздел [Структура аудиторий](#audiences-shape). ### adapty placements create Создать новый [плейсмент](placements). ```bash adapty placements create --app --title "Main" --developer-id "main" --audiences '[{"content_type":"paywall","segment_ids":[],"paywall_id":"","priority":0}]' ``` | Флаг | Обязательный | Описание | |---|---|---| | `--app` | Да | ID приложения (UUID) | | `--title` | Да | Название плейсмента | | `--developer-id` | Да | Строковый идентификатор, используемый в коде приложения для запроса этого [плейсмента](placements) | | `--audiences` | Один из двух | JSON-массив записей аудиторий, каждая с явно указанным `content_type`. См. [Структура audiences](#audiences-shape) | | `--paywall-id` | Один из двух | **Устарело.** ID [пейвола](paywalls) (UUID). На стороне клиента оборачивается в единую аудиторию по умолчанию | Передайте ровно один из параметров: `--audiences` или `--paywall-id`. Передача обоих или ни одного из них приведёт к ошибке. :::warning `--paywall-id` устарел и будет удалён. При передаче этого флага CLI выводит предупреждение в stderr и конвертирует значение в аудиторию по умолчанию. Используйте `--audiences` в новых скриптах автоматизации. ::: ### adapty placements update Заменяет все поля существующего [плейсмента](placements). ```bash adapty placements update --app --title "Main" --developer-id "main" --audiences '[{"content_type":"paywall","segment_ids":[],"paywall_id":"","priority":0}]' ``` Эта команда полностью заменяет все поля плейсмента, включая полный список аудиторий. | Аргумент | Описание | |---|---| | `placement-id` | ID плейсмента (UUID) | | Флаг | Обязательный | Описание | |---|---|---| | `--app` | Да | ID приложения (UUID) | | `--title` | Да | Название плейсмента | | `--developer-id` | Да | Строковый идентификатор, используемый в коде приложения для запроса этого [плейсмента](placements) | | `--audiences` | Один из двух | JSON-массив записей аудиторий, каждая с явным `content_type`. См. [Форма audiences](#audiences-shape) | | `--paywall-id` | Один из двух | **Устарело.** ID [пейвола](paywalls) (UUID). Заменяет все аудитории одной аудиторией по умолчанию | :::warning Передача `--paywall-id` перезаписывает все аудитории в плейсменте. Аудитории, привязанные к конкретным сегментам, удаляются. Чтобы сохранить их, используйте `--audiences` и включите все записи, которые хотите оставить. ::: #### Структура аудиторий \{#audiences-shape\} Флаг `--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 [сегментов](segments), на которые нацелена эта аудитория. Длина 0 или 1. Пустой массив означает **аудиторию по умолчанию** — резервный вариант для пользователей, не попавших ни в один другой сегмент | | `paywall_id` | `string` | ID [пейвола](paywalls) (UUID), который показывается пользователям в этой аудитории. Обязательно, когда `content_type` равен `"paywall"` | | `flow_id` | `string` | ID [флоу](adapty-flow-builder) (UUID), который показывается пользователям в этой аудитории. Обязательно, когда `content_type` равен `"flow"` | | `ab_test_id` | `string` | ID [A/B-теста](ab-tests), запускаемого для пользователей в этой аудитории. Обязательно для всех четырёх типов контента 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` нельзя переключить плейсмент с пейвола на флоу или обратно. Создайте для флоу отдельный плейсмент — см. [Создание нового плейсмента для вашего флоу](migrate-to-flows#create-a-new-placement-for-your-flow). 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`](developer-cli-flows#adapty-flows-publish) или [Flow & Paywall Builder](builder-save-publish), затем дождитесь, пока его статус не станет `published`. Пример с одной целевой аудиторией и одной аудиторией по умолчанию: ```bash adapty placements update --app --title "Main" --developer-id "main" \ --audiences '[{"content_type":"paywall","segment_ids":[""],"paywall_id":"","priority":0},{"content_type":"paywall","segment_ids":[],"paywall_id":"","priority":1}]' ``` Пример плейсмента, который показывает опубликованный флоу всем пользователям: ```bash adapty placements create --app --title "Onboarding" --developer-id "onboarding" \ --audiences '[{"content_type":"flow","segment_ids":[],"flow_id":"","priority":0}]' ``` Чтобы заменить пейвол в нескольких плейсментах без потери роутинга по сегментам: 1. Найдите затронутые плейсменты: ```bash adapty paywalls placements --app ``` 2. Для каждого из них прочитайте полный массив `audiences`: ```bash adapty placements get --app --json ``` 3. Замените соответствующие значения `paywall_id` на стороне клиента. Все остальные записи оставьте без изменений, включая записи A/B-тестов. 4. Запишите изменённый payload обратно: ```bash adapty placements update --app --title "" --developer-id "<developer-id>" --audiences '<modified-payload>' ``` ## Сегменты \{#segments\} [Сегменты](segments) группируют пользователей по атрибутам их профилей. Используйте эти команды для создания сегментов и поиска их ID при составлении [аудиторий плейсментов](#audiences-shape). Чтобы создать сегмент на основе кампаний, групп объявлений или ключевых слов Apple Ads, используйте [`adapty asa segments create`](developer-cli-ads-manager-reference#segments): эта команда самостоятельно найдёт Apple ID и назовёт сегмент так, как это принято в Ads Manager. ### adapty segments list Выводит все [сегменты](segments) приложения. ```bash adapty segments list --app <app-id> ``` | Flag | Required | Description | |---|---|---| | `--app` | Yes | App ID (UUID) | Принимает [флаги пагинации](developer-cli-reference#global-flags). ### adapty segments get Получить детали конкретного [сегмента](segments). ```bash 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 Создайте [сегмент](segments) на основе одного или нескольких фильтров. ```bash 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` | Да | Правило фильтра. Можно указывать несколько раз. См. [Синтаксис фильтров](#filter-syntax) | | `--description` | Нет | Описание сегмента | Пользователь попадает в сегмент только при соответствии всем фильтрам. Ответ содержит те же поля, что и `segments get`. `profile_count` начинается с `0`, и Adapty пересчитывает его после создания сегмента. ### adapty segments update Замените название, описание и фильтры существующего [сегмента](segments). ```bash 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` | Да | Правило фильтра. Можно указывать несколько раз. См. [Синтаксис фильтров](#filter-syntax) | | `--description` | Нет | Описание сегмента | :::warning `segments update` полностью заменяет сегмент. Передавайте все фильтры, которые хотите сохранить, а не только тот, который меняете. Чтобы прочитать текущие фильтры, выполните `adapty segments get --app <app-id> <segment-id> --json`. ::: #### Синтаксис фильтров \{#filter-syntax\} Каждый `--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-объект: ```bash 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` для сегмента, созданного в дашборде. ## Что дальше \{#whats-next\} - [Справочник команд](developer-cli-reference) — все темы CLI, глобальные флаги и флаги пагинации.