Как работать с Яндекс Директом в MaxPosty

Какой доступ получает MaxPosty

Подключение открывает официальную страницу Яндекс ID. Пароль остаётся у Яндекса, а MaxPosty получает OAuth-токен с правом direct:api для действий, доступных самому представителю рекламного кабинета.

Сервис читает сведения кабинета, кампании, их состав, статусы и статистику. Создание и изменение кампании, объявлений, ключевых фраз, предела цены клика и состояния показов выполняется только после действия пользователя либо отдельного точного согласия на автозапуск.

• токен хранится только на сервере в зашифрованном виде;
• права участников дополнительно ограничиваются ролями рабочего пространства;
• MaxPosty не получает пароль Яндекс ID и не пополняет рекламный баланс;
• в интерфейсе явно показан тестовый или боевой режим кабинета.

Подготовьте кампанию и ключевые фразы

1. 1

   Подключите кабинет в разделе «Реклама».

2. 2

   Создайте локальный черновик: укажите ссылку, регионы, объявления, фразы, бюджет и период.

3. 3

   При необходимости откройте Wordstat: запрос выполняется только по вашей команде и использует регионы кампании.

4. 4

   Выберите подсказки, добавьте их в редактор и ещё раз проверьте формулировки.

5. 5

   Сохраните черновик до отправки данных в Яндекс Директ.

Отправка и проверка состава

Команда отправки создаёт Единую перфоманс-кампанию, одну группу, одно адаптивное объявление и выбранные ключевые фразы. Поиск и Карты выключены, показы настроены для РСЯ. После каждой операции MaxPosty повторно читает объекты и фиксирует проверенный снимок с хешем и номером редакции.

1. 1

   Проверьте итоговый бюджет, период, объявление, регионы и ключевые фразы.

2. 2

   Подтвердите отправку на модерацию.

3. 3

   Дождитесь статуса Яндекс Директа.

4. 4

   Перед ручным запуском обновите данные и подтвердите точный кабинет, кампанию, бюджет, период и проверенную редакцию.

Схема вызовов и ограничения API

После OAuth MaxPosty вызывает Clients.get, чтобы проверить доступный рекламный кабинет, валюту, поддерживаемый тип кампании и право записи. Работа с локальным черновиком не обращается к API Директа. По команде отправки сервис получает регионы через Dictionaries.getGeoRegions, ищет маркер операции через Campaigns.get и, если объектов ещё нет, последовательно вызывает Campaigns.add, AdGroups.add, Ads.add и Keywords.add. Между стадиями объекты перечитываются соответствующими get. Полный состав сверяется через Campaigns.get, BidModifiers.get, AudienceTargets.get, AdGroups.get, Ads.get и Keywords.get перед вызовом Ads.moderate и ещё раз перед Campaigns.resume. Изменения используют соответствующие update, add или delete, после чего полный состав снова читается и сверяется.

Фоновый обработчик запускает последовательный цикл через 15 секунд после завершения предыдущего, ограничивает цикл 45 секундами и берёт не более четырёх кампаний из каждой очереди. При создании курсора каждой кампании Changes.checkDictionaries один раз получает время сервера, затем Changes.check проверяет одну кампанию с перекрытием курсора в 1 минуту. Проверка выполняется раз в 5 минут во время модерации, раз в 15 минут для черновой, принятой или переходной кампании, раз в 30 минут для активной, раз в час для остановленной и раз в 6 часов для отклонённой. Полный граф читается только при изменении кампании, группы или объявления; изменение только статистики продвигает курсор без такого чтения. Записывающие методы выполняются лишь по явной команде пользователя или по сохранённому точному согласию на автозапуск.

Отчёт Reports запрашивается только пользователем: одна кампания, период не более 366 дней и не более 400 дневных строк. Запросы отчётов для рекламодателя выполняются последовательно и начинаются не чаще одного раза в секунду — это не более половины ограничения Яндекса в 20 запросов за 10 секунд. Ответ 201 или 202 опрашивается тем же запросом через указанный Яндексом интервал, либо через 5 секунд, с общим тайм-аутом 2 минуты. Отчёт в MaxPosty не сохраняется. Для предела цены клика сервис читает Campaigns.get и валютные ограничения Dictionaries.get, после отдельного подтверждения меняет BiddingStrategy через Campaigns.update и перечитывает кампанию. Bids.set не используется.

Wordstat вызывается отдельно и только по команде пользователя через Yandex Cloud Search API; Dictionaries.getGeoRegions сопоставляет регионы кампании. Результат кэшируется на 10 минут. Логические лимиты MaxPosty: не более 3 запросов Wordstat в секунду и 33 в час на ключ поставщика, 2 в секунду и 20 в час на рабочее пространство, 1 в секунду и 10 в час на пользователя. Каждый логический запрос может сделать до трёх HTTP-попыток только для 429 и 5xx с задержкой не более 2 секунд, поэтому физический предел на ключ поставщика — 9 попыток в секунду и 99 в час при ограничении Яндекса 10 и 100.

• одновременно выполняется не более четырёх обычных запросов API Директа на рекламодателя при ограничении Яндекса в пять; отдельного фиксированного RPS для этих сервисов нет, нагрузку дополнительно ограничивают последовательность операций и баллы;
• MaxPosty учитывает заголовки Units и Units-Used-Login, а также RequestId каждого ответа; Retry-After задаёт паузу для 429 и 503, ошибка 152 блокирует новые запросы на минуту, ошибка 506 — на 2 секунды;
• безопасные get, check, checkCampaigns и checkDictionaries повторяются максимум два раза после первой попытки для HTTP 429, 500, 502, 503, 504 или кода 506, с задержками 200 и 400 мс либо с указанным Retry-After не более 2 секунд; записывающие запросы вслепую не повторяются;
• после неоднозначного результата записи сервис читает текущее состояние и сопоставляет его с маркером операции; Campaigns.resume может быть повторён один раз через 2 минуты только после подтверждённого состояния OFF, а состояние ON считается успехом без новой записи;
• расхождение состава, SHA-256 отпечатка, редакции или согласия блокирует продолжение; аренда операции составляет 10 минут при тайм-ауте процесса 8 минут, поэтому устаревший обработчик не может продолжить запись;
• на одну кампанию действует предел 10 000 ₽ в неделю, а на рабочее пространство — 30 000 ₽ в неделю; несовместимый тип кампании, валюта, режим только чтения или исчерпанные ограничения приводят к отказу до записи.

Статистика и предел цены клика

В карточке созданной кампании доступны дневной отчёт по показам, кликам, расходу и конверсиям, а также настройки автоматической стратегии «Максимум кликов». Отчёт запрашивается у Яндекс Директа за выбранный период и отдельно в MaxPosty не сохраняется.

• предел цены клика проверяется по актуальным ограничениям валюты из Яндекс Директа;
• изменение требует точной фразы подтверждения и свежей проверенной редакции;
• слишком низкий предел может уменьшить трафик и помешать обучению стратегии;
• суммы в интерфейсе показаны в рублях, а обмен с API выполняется в точных целых денежных единицах Яндекса.

Как прекратить доступ

Отключение кабинета отзывает доступ MaxPosty и удаляет возможность новых запросов от имени пользователя. Уже запущенная реклама при этом не останавливается автоматически.

1. 1

   Сначала остановите расходующие кампании в Яндекс Директе.

2. 2

   Проверьте их фактическое состояние в рекламном кабинете.

3. 3

   Затем нажмите «Отключить» в MaxPosty и подтвердите предупреждение.

4. 4

   При необходимости дополнительно отзовите разрешение приложения в настройках Яндекс ID.