Yandex Direct

Яндекс Директ

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

Задача → нужные данные → расчёт и объяснение → действие → проверка результата.

Все пути ниже относятся к каталогу этого файла. Запуск: uv run scripts/…. Также подходит python3 scripts/… с Python 3.11 и новее; сторонних библиотек нет. Параметры конкретной команды доступны через --help.

1. Определи задачу и объекты

Выясни из запроса и предыдущих ответов, что нужно получить: сведения, оценку, предложения, новые материалы или изменения. Найди рекламодателя и нужные кампании, группы, объявления либо фразы. Для анализа задай период, для сравнения — два сопоставимых периода. Спрашивай только то, без чего нельзя правильно продолжить; разумное допущение о периоде или отборе явно назови.

uv run scripts/accounts.py --search "название или домен"
uv run scripts/accounts.py --use "логин"
uv run scripts/campaigns.py --account "логин"

Если подходят несколько объектов, покажи названия и ID и попроси выбрать. В командах указывай --account: это сохраняет выбранного рекламодателя при параллельной работе. Уже выбранный кабинет повторно не уточняй.

При проблемах с доступом запусти uv run scripts/whoami.py --account "логин". Без --account эта команда проверяет кабинет из конфигурации. Команды сами читают config/.env; не открывай и не выводи токен в диалог. Подключение нового кабинета: config/README.md.

2. Определи, что считать результатом

Для оценки конверсий сначала получи доступные цели:

uv run scripts/report.py --account "логин" --campaign 123 --list-goals

Покажи названия и ID и спроси, какие действия ценны для бизнеса. Можно выбрать одну или несколько целей. Дождись выбора перед расчётом конверсий, CPA и выводов об эффективности. Цель стратегии, первая цель в списке и показатель «все конверсии» не заменяют решение пользователя.

Передавай выбранные цели явно через --goals ID,ID. Если пользователь уже выбрал их для этой задачи, используй ответ без повторного вопроса. Не переноси цели другого кабинета и не заменяй недоступную цель другой молча. До выбора можно собрать показы, клики и расход с --traffic-only.

Для экономических рекомендаций используй известные бизнес-ограничения: допустимую стоимость результата, бюджет, маржу, регион, сроки и предложение. Если нужного ограничения нет, обозначь вывод как предварительный или уточни его. Для простого чтения настроек или правки текста выбирать конверсионные цели не нужно.

Для добавления целей в кампанию или изменения целей оптимизации читай цели кампаний. Цели отчёта не меняют настройки кампании. В campaign_write.py strategy обычные --goal заменяют весь список; для сохранения прежних целей используй --add-goals. Проверь также тип стратегии и её GoalId: один список целей ещё не задаёт способ оптимизации. В доступных целях часто много мусора: автособытия, промежуточные клики и дубли. Не выбирай все цели для оптимизации по умолчанию; согласуй действия, ценные для бизнеса, и проверь состав даже у режима «все ключевые цели».

3. Собери данные нужного уровня

Выбирай детализацию по вопросу. Кампания показывает общий результат; группы и объявления помогают сравнить предложения; условия показа и поисковые запросы — спрос и соответствие рекламе; площадки, устройства и периоды — различия условий.

Отчёты, поля и команды: references/REPORTS.md. Настройки, статусы, стратегии и причины проблем: references/PLAYBOOK.md. При анализе показов, создании или перестройке групп прочитай разбор «Мало показов». Сам выявляй редкие показы и риск раздробить спрос по слишком узким группам; объясняй их пользователю, даже если он не спрашивал о статусах.

По умолчанию используй автоматическую атрибуцию AUTO: команда report.py выбирает её, если --attribution не задан. Если в кампании или стратегии стоит другая модель, например LC, объясни расхождение и предложи выбрать: отчёт по AUTO, по модели кампании или сравнение обеих. Уже известный выбор пользователя используй без повторного вопроса; называй модель в ответе.

Если пользователь предпочитает AUTO, а кампания работает по LC, можно отдельно предложить сменить настройку кампании. Выбор модели отчёта сам по себе не меняет кампанию и не означает поручения её изменить. Подготовь «было → станет» и действуй по обычному порядку изменений; подробности — в практиках по атрибуции.

Для сравнения сохраняй одинаковые цели, атрибуцию, валюту, учёт НДС и отбор. Отделяй поиск от сетей и полный период от ещё не завершённого. Учитывай задержку конверсий, изменение спроса и недостаток наблюдений. Объекты без текущей статистики не теряй при сопоставлении с историей.

Команды используют локальный кеш. Если задача требует актуальных данных, добавь --no-cache там, где он поддерживается. Перед записью команды всегда читают свежие значения.

4. Рассчитай и объясни показатели

Для каждой выбранной цели используй её собственное число конверсий. Под «конверсиями» понимай показатель Директа для этой цели и модели атрибуции, а не число уникальных покупателей и не сумму всех действий посетителей.

Например, 1000 показов, 50 кликов, расход 1500 ₽ и 5 конверсий выбранной цели дают CTR 5%, CPC 30 ₽, CR 10%, CPA 300 ₽. Рост CR с 5% до 10% — это +5 п.п. или +100% относительно прежнего значения.

При нулевом знаменателе показатель не определён: покажи «нет данных для расчёта», а не ноль. Значения -- и пустые ячейки не превращай в нули. Для итогов суммируй исходные количества и расход и заново вычисляй отношение; не усредняй CPA, CPC или CTR строк обычным средним. Средние позиции запрашивай в нужной группировке: для их пересчёта может не хватать данных о показах, которые учитывает API.

Один визит может достичь нескольких целей. Показывай цели отдельно: сумма конверсий не равна уникальным заявкам, сумма доходов может содержать пересечения. ROAS не учитывает себестоимость и прочие расходы и сам по себе не доказывает прибыль. Указывай валюту и учёт НДС; денежные поля JSON/TSV переводятся из миллионных долей валюты, то есть 125000000 = 125 единиц. Не суммируй разные валюты.

5. Отдели наблюдение от решения

Объясняй ход вывода: что видно в данных → возможная причина → чем её проверить → какое действие поможет → по какому показателю оценить эффект. Сила вывода зависит от числа наблюдений и сопоставимости условий. Одна конверсия или короткий провал не доказывают закономерность.

Например, хорошие конверсии при слабых позициях дают повод проверить ставки, бюджет, стратегию и ограничения. Повышение ставки уместно при приемлемой экономике, если именно ставка ограничивает показы. При автоматической стратегии важнее могут оказаться целевая CPA и бюджет. Рост ставки не гарантирует определённое место.

Для позиций различай среднюю позицию, объём трафика и долю показов в блоке. Доля спецразмещения = показы PREMIUMBLOCK / все показы на поиске × 100%. Это доля фактических показов, а не всех доступных аукционов. Slot доступен по условию показа, но не по отдельному Query: не приписывай долю условия каждому запросу. История запросов ограничена последними 180 днями; называй реальное покрытие периода. Пример такого анализа есть в REPORTS.md.

Предложения по улучшению должны соответствовать задаче пользователя. Рекомендация сама по себе не означает разрешения изменить кампанию.

6. Подготовь действие и проверь результат

Для создания собери нужные данные и покажи содержание и настройки нового объекта. Для изменения прочитай актуальное состояние и подготовь только запрошенные правки. Покажи «объект — поле — было — станет». У создания значение «было» отсутствует. Цена в тексте, цена товара, ставка, бюджет и сроки показов — разные параметры; если новое значение или его смысл неизвестны, уточни их до записи.

При работе с бюджетами и перед созданием или запуском новых кампаний читай управление бюджетами. Предлагай проверить недельный лимит всего кабинета и установить его, если ограничения нет: это защита от аномального расхода. Существующий лимит оцени с учётом новой рекламы; известный отказ или согласованное исключение используй без повторного вопроса. У новой кампании также должен быть согласованный бюджет её стратегии. Предлагай небольшую сумму для проверки трафика и увеличение по результатам; уже согласованный бюджет используй без самовольных изменений. Брендовая реклама — повод обсудить исключение, а не автоматически снять лимит. Суммы, команды, бюджеты пакета и на период — в том же справочнике.

Перед созданием кампании или изменением её мест показа читай выбор мест показа. Покажи конкретный список: товарное объявление само по себе не ограничивает показы галереей. Для задачи «только галерея» явно выключай остальные доступные места и сетевую часть; непроверяемые через API переключатели назови и проверь в интерфейсе до запуска.

При создании поисковой рекламы, настройке автотаргетинга, нецелевых запросах или нехватке трафика читай категории автотаргетинга. Для новой поисковой группы по умолчанию предлагай только узкие запросы: Narrow=YES, остальные четыре категории — NO, если пользователь не выбрал другой состав. Объясняй этот выбор сам; работающие настройки не заменяй автоматически. Расширение охвата, бренды, РСЯ и товарная галерея — в справочнике.

Обычный запуск пишущей команды показывает план без изменений в кабинете. --apply выполняет правку и перечитывает объект. Если пользователь уже поручил конкретное действие, повторное подтверждение не требуется. Если просит только проверить или предложить — представь готовые изменения для согласования.

Сохраняй неназванные поля и элементы. При обновлении списка заголовков, текстов или изображений передавай весь итоговый список, включая сохраняемые элементы. Проверяй связанные места, где могла остаться устаревшая информация. Механика и примеры команд: references/CHANGES.md.

После выполнения покажи «было — стало» по фактическому чтению, с полными изменёнными текстами. Отдели проверенный успех, отказ и неизвестный исход. При частичном успехе продолжай с установленным остатком; при обрыве связи сначала перечитай объект, чтобы повтор не создал дубликат. Настройки могут быть записаны, но ещё не допущены к показам: учитывай состояние и модерацию.

Команда ads_write.py ad create/update записывает комбинаторные ResponsiveAd через API v501. Для фидов, товарных объявлений и отбора товаров сначала читай фиды и товарные объявления: feeds.py управляет библиотекой фидов, shopping.py — объявлениями ShoppingAd и их фильтрами. Проверь тип объявления и все кампании, использующие фид, перед изменением общего источника. Смена FeedId требует нового объявления; снятие фильтров расширяет отбор до всего фида. Чтение включает ResponsiveAdFieldNames, иначе API может показать комплект как TEXT_AD. Основные тексты старого TextAd готовые команды не меняют: назови такой остаток и предложи правку в интерфейсе. Его быстрые ссылки и уточнения можно менять через extensions.py bind. Создание вместо него нового комбинаторного объявления обсуждай как отдельное изменение. В комплекте должна осмысленно читаться любая пара «заголовок × текст».