Adapty CLI позволяет управлять аккаунтом Ads Manager из терминала в рамках раздела adapty asa. Поддерживаются кампании, группы объявлений, ключевые слова, объявления, страницы продукта, правила автоматизации, метрики и исследование конкурентов.

Используйте CLI для задач, с которыми браузер справляется медленно: предоставить AI-агенту живой доступ к данным о производительности рекламы, добавить несколько сотен ключевых слов из файла, применить одинаковые настройки сразу к нескольким кампаниям. Для всего остального дашборд остаётся удобнее.

Перед началом работы

Команды Ads Manager используют те же настройки установки и входа, что и остальная часть CLI. Если вы ещё не настроили это, выполните шаги 1 и 2 из гайда по быстрому старту.

Предварительные требования

К каждой команде adapty asa применяются два дополнительных условия:

• Подключённый аккаунт Apple Ads: подключите его командой adapty asa connect или через дашборд, как описано в разделе Начало работы с Adapty Ads Manager.
• Активная подписка Ads Manager: без неё каждая команда завершается ошибкой 402 ads_manager_subscription_required.

Проверить оба условия можно одной командой:

adapty asa whoami

Отличия от остальных команд CLI

• Флага --app нет: область действия — компания, которой принадлежит ваш токен. --app присутствует лишь в некоторых командах list как фильтр.
• Изменения применяются напрямую в Apple: каждая команда, затрагивающая аккаунт, выводит тело запроса и запрашивает подтверждение перед отправкой. Промежуточного этапа нет.
• Чтение безопасно, запись — нет: команды list и флаг --dry-run можно использовать свободно. Всё остальное считайте необратимым.

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

Найдите нужные идентификаторы

Каждая команда принимает UUID, и каждый UUID берётся из команды list. Двигайтесь по иерархии сверху вниз:

adapty asa orgs list
adapty asa campaigns list --campaign-group <campaign-group-id>
adapty asa ad-groups list --campaign <campaign-id>

Ограничивайте каждый запрос фильтром. Фильтры сужают сам запрос, а не только вывод, поэтому запрос с фильтром обходится дёшево, а без фильтра — перебирает весь аккаунт. adapty asa keywords list без --ad-group — самый широкий запрос в этом разделе.

Эти списки возвращают только метаданные. Числовые показатели доступны через asa metrics.

Получение рекомендаций по ключевым словам

Чтобы сформировать список ключевых слов без предварительного исследования, воспользуйтесь готовым пулом для вашего приложения. Передайте adam_id приложения из adapty asa apps list и тип пула — brand, generic или competitor:

adapty asa keywords recommend --adam-id <adam-id> --type generic --country US

Пул не содержит ставок или типов соответствия. Выберите их самостоятельно, затем добавьте ключевые слова, как описано в разделе Добавление ключевых слов пакетом. Если в выводе отображается status: building, повторите попытку через минуту. Допустимые типы пулов и ограничения см. в командах Ads Manager.

Массовое добавление ключевых слов

Добавление ключевых слов по одному — главная причина не покидать дашборд. Запишите по одному ключевому слову в строку в текстовый файл:

adapty asa keywords add --ad-group <ad-group-id> --from-file keywords.txt --bid 1.20 --match-type EXACT

Ключевые слова применяются пакетом не более 100 за один вызов. Разбивайте большие списки на несколько вызовов.

Возможны два типа ошибок, и они ведут себя по-разному. Невалидный ID прерывает весь пакет до обращения к Apple, поэтому ничего не применяется. Apple также может отклонить отдельные ключевые слова — остальные при этом всё равно добавляются, а каждый отказ сопровождается указанием причины. Ориентируйтесь на итоговую строку, а не только на код завершения.

Начните с нескольких ключевых слов и проверьте результат, прежде чем отправлять полный файл.

Создание кампании Max Conversions

Кампания со стратегией MAX_CONVERSIONS запускается только при наличии автоматизированной группы объявлений, поэтому создайте их вместе:

adapty asa campaigns create --org <campaign-group-id> --name "Max Conv" --adam-id 123456 --country US --daily-budget 50 --bidding-strategy MAX_CONVERSIONS
adapty asa ad-groups create --campaign <campaign-id> --name "Automated Max Conv" --automated

До тех пор, пока этот рекламный группа не создана, в кампании отображается serving_status: NOT_RUNNING с причиной AUTOMATED_KEYWORDS_REQUIRED_AD_GROUP_MISSING в списке serving_state_reasons, а команда campaigns create выводит и причину, и команду, которая устранит проблему.

Именно флаг --automated удовлетворяет это требование — обычная рекламная группа с --automated-keywords не подходит. Apple самостоятельно планирует и управляет автоматической рекламной группой, поэтому она не принимает --start-time, параметр --default-bid необязателен, и группа остаётся включённой: чтобы остановить расходы, следует поставить кампанию на паузу.

В настройках кампании значение --target-cpa должно быть ниже, чем --daily-budget.

Настройка параметров выставления счётов для кредитной линии

Apple требует параметры выставления счётов для каждой кампании в организации, которая использует кредитную линию для оплаты. Команда adapty asa orgs list показывает payment_model каждой организации — значение LOC означает, что применяются пять флагов --invoice-*:

adapty asa campaigns create --org <campaign-group-id> --name "LOC push" --adam-id 123456 --country US --daily-budget 50 --invoice-advertiser "Acme Inc" --invoice-order-number PO-42 --invoice-contact-name "Jane Doe" --invoice-contact-email jane@acme.com --invoice-billing-email billing@acme.com

Pass all five in one call — a partial set is rejected before the request reaches Apple. Without them, the campaign is created but reports serving_status: NOT_RUNNING with MISSING_BO_OR_INVOICING_FIELDS.

Передавайте все пять флагов в одном вызове — неполный набор отклоняется ещё до того, как запрос достигает Apple. Без них кампания создаётся, но возвращает serving_status: NOT_RUNNING с MISSING_BO_OR_INVOICING_FIELDS.

The same five flags on adapty asa campaigns update set the Invoicing Options on a campaign that already exists. They replace the stored set as a whole, so pass all five even to change one of them.

Те же пять флагов в команде adapty asa campaigns update задают параметры выставления счетов для уже существующей кампании. Они полностью заменяют сохранённый набор, поэтому передавайте все пять, даже если нужно изменить только один.

Создание структуры кампании за одну операцию

campaigns bulk-create заменяет скрипт, который последовательно вызывает campaigns create и ad-groups create. Команда отправляет всю структуру кампании — сами кампании с их группами объявлений, ключевыми словами, минус-словами и объявлениями — как одну операцию:

adapty asa campaigns bulk-create --file structure.json

На вход подаётся JSON-описание структуры — см. формат структуры для описания полей. JSON — это естественный формат для AI-агента: он генерирует структуру и передаёт её на вход:

cat structure.json | adapty asa campaigns bulk-create --file -

Нативный шаблон Apple Ads для массовых операций тоже подходит в качестве входных данных — сервер конвертирует Campaign_And_Adgroup_Template.xlsx или .csv с ключевыми словами в структуру. --org-id принимает числовой org_id из adapty asa orgs list. Чтобы проверить результат конвертации перед созданием, добавьте --preview:

adapty asa campaigns bulk-create --from-file Campaign_And_Adgroup_Template.xlsx --org-id 1234567 --preview

Ошибки конвертации выводятся с указанием листа, строки и столбца. Когда выведенная структура выглядит корректно, уберите --preview, чтобы отправить данные.

Вывод --preview — это также самый быстрый способ получить стартовый файл структуры: сохраните его, отредактируйте и отправьте с --file — так же, как automations get предоставляет шаблон правила.

Вся структура проходит валидацию перед созданием, и при отклонении выводится список всех невалидных узлов. После принятия объекты создаются на сервере, а команда отображает прогресс. Итоговый статус — success, partial или failed: результат partial содержит список каждого объекта, который не был создан, с ошибкой от Apple.

Для большой структуры используйте --no-wait, чтобы сразу получить ID операции и проверить прогресс позже:

adapty asa campaigns bulk-status <operation-id>

Запрашивайте метрики из агентов и скриптов

asa metrics формирует отчёт по любому уровню аккаунта за заданный период. Добавьте --json, чтобы результат можно было передать напрямую в AI-агент или скрипт:

adapty asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --metric spend --metric roas --json

--metric обязателен и может использоваться несколько раз — принимает названия метрик, которые отслеживает Ads Manager. Полный список см. в разделе Метрики. Каждая указанная метрика вычисляется по всему уровню сущности до разбивки на страницы, поэтому запрашивайте только те столбцы, которые вам нужны, а не весь каталог.

--app, --campaign и --ad-group сужают область отчёта, и это самый дешёвый способ ускорить запрос, потому что стоимость зависит от количества агрегируемых сущностей, а не от размера страницы. Четыре метрики считают уникальные профили по каждой сущности — subscribers, paid_subscribers, arppu и arpas — и для них на любом уровне сущности необходим фильтр по кампании или группе объявлений:

adapty asa metrics --entity keyword --date-from 2026-07-01 --date-to 2026-07-31 --metric arpas --campaign <campaign-id> --json

Метрики когорт работают иначе, чем остальные. Метрики ltv нет, потому что lifetime value считается в окне продления, а не на конкретную дату. Вместо этого укажите окно:

adapty asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --metric roas --by-days 7 --by-days 90 --order-by-day 90

Результат — кампании, отсортированные по ROAS на 90-й день. В одном запросе помещается до 16 окон.

Каждая строка — одна сущность, уже агрегированная и отсортированная на сервере. Вопрос «топ пять кампаний по тратам» — это один запрос, без перебора каждой страницы:

adapty asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --order-by spend --page-size 5

Метрики и список поисковых запросов используют один бюджет аналитики на компанию: 5 вызовов в минуту и не более 2 за любые 10 секунд. Задавайте узкий вопрос один раз, вместо того чтобы опрашивать повторно.

На отчёт распространяются два ограничения. Отчётный период ограничен степенью детализации группировки: 28 дней при --group-by day, 90 дней без группировки по периоду, 180 при группировке по неделям, 365 при группировке по месяцам. Каждая страница содержит не более 5000 строк разбивки — одна строка на сущность × страну × период. Чтобы расширить диапазон отчёта, укрупняйте группировку через --group-by, а не дробите запрос на несколько вызовов.

Проверьте ключевые слова конкурентов

Одна команда возвращает ключевые слова, на которые делают ставки конкурирующие приложения — до пяти приложений App Store за один раз:

adapty asa competitors summary --app-ids 1668337467,6503873027 --json

Период и страны фиксированы на сервере — последний полный месяц, по всем странам, — поэтому у команды нет флагов помимо идентификаторов приложений. Первый вызов для набора приложений может занять десятки секунд.

Используйте этот метод, чтобы периодически получать данные о ключевых словах конкурентов в отчёт. Чтобы фильтровать результаты, сравнивать страны или сразу добавлять найденные ключевые слова в кампанию, воспользуйтесь Market Intelligence в дашборде.

Запуск правил автоматизации

CLI сохраняет переданный JSON, поэтому самый быстрый способ получить валидный файл правила автоматизации — создать одно правило в дашборде, а затем считать его обратно:

adapty asa automations get <automation-id> --json > rule.json

Отредактируйте этот файл и используйте его как шаблон для новых правил:

adapty asa automations create --file rule.json

Файл правила содержит ровно одно условие и ровно одно действие — именно это API хранит для каждого правила. Перед передачей файла в automations update удалите поле internal_id — при его наличии обновление будет отклонено.

Создайте действие «Добавить как ключевое слово» из флагов

Одно действие является исключением из правила ручного написания JSON. Add as keyword — продвигает поисковый запрос или копирует ключевое слово в другую группу объявлений — принимает целевые группы объявлений, ставку и тип соответствия из флагов:

adapty asa automations create --file rule.json --target-ad-group <ad-group-id> --match-type EXACT --cpt-bid-type search_term_current_cpt --negate ad-group

Те же флаги в automations update исправят правило, уже сохранённое с неправильной формой. CLI считывает правило, пересобирает действие с нуля и записывает его обратно, оставляя только те сохранённые настройки, которые подходят для действия Add as keyword:

adapty asa automations update <automation-id> --target-ad-group <ad-group-id> --match-type EXACT --cpt-bid-type search_term_current_cpt

Если правило нарушалось из-за отсутствующего параметра, его нужно передать через флаг. Полный список флагов — в разделе Команды Ads Manager.

Проверьте правило перед тем, как разрешить ему менять ставки:

adapty asa automations run <automation-id> --dry-run

Пробный запуск проверяет условия и логирует, что правило сделало бы, не затрагивая Apple Ads. Запуски ставятся в очередь, а не выполняются немедленно, поэтому команда выводит ID запуска, а результат появляется в adapty asa automations runs.

Безопасный повторный запуск скриптов

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

В скрипте зафиксируйте ключ вручную, чтобы весь пайплайн можно было запустить повторно:

adapty asa campaigns create --org <campaign-group-id> --name "Winter push" --adam-id 123456 --country US --daily-budget 50 --idempotency-key winter-push-2026 --yes

Повторный запуск той же команды в течение 24 часов возвращает сохранённый результат и выводит Already applied earlier вместо создания второй кампании. Тот же ключ с другим телом завершается ошибкой 422 — это позволяет поймать отредактированный скрипт, который по ошибке повторно использует ключ.

Что дальше

• Управление Apple Ads с помощью AI-инструмента для разработчиков — установите плагин Apple Ads, чтобы Claude Code, Copilot CLI, Codex или Gemini CLI могли выполнять эти команды за вас.
• Команды Ads Manager — все команды с аргументами, флагами и допустимыми значениями.
• Автоматизации — что делает каждый тип правила и какие действия он может выполнять.
• Метрики — названия метрик, принимаемых параметром --metric, и способ расчёта каждой из них.