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

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

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

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

Warning

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

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

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

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

Что дальше