English 中文TürkçeРусскийFrançaisTiếng ViệtEspañol日本語

Управление Ads Manager из CLI

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

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

CLI не может ничего удалять. Кампании, объявления и правила автоматизации можно создавать, обновлять и приостанавливать из терминала, но удалять их можно только в дашборде.

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

Команды 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.

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

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

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

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

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

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

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

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. Полный список см. в разделе Метрики.

Метрики когорт работают иначе, чем остальные. Метрики 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 секунд. Задавайте точный вопрос один раз вместо повторных опросов. Период отчётности также ограничен степенью детализации группировки — 90 дней по дням, 180 по неделям, 365 по месяцам, — поэтому расширяйте отчёт, укрупняя --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

Когда вы передаёте файл в automations update, сначала удалите поле internal_id — при его наличии обновление будет отклонено.

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

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 — это позволяет поймать отредактированный скрипт, который по ошибке повторно использует ключ.

Что дальше