artwist-polyakov/polyakov-claude-skills/yandex-metrika

yandex-metrika

Работа с API Яндекс Метрики: детализация трафика по источникам и UTM-меткам, отчёты по конверсиям и поисковым системам, API-сегменты и прямые доступы к счётчикам.

Config

Требуется YANDEX_METRIKA_TOKEN в config/.env. Для чтения нужен доступ metrika:read, для создания сегментов и управления доступами — metrika:write. Инструкция: config/README.md.

Philosophy

1. Cache-first — конфигурационные данные (счётчики, цели, инфо) кешируются надолго. Отчёты кешируются по ключу counter+dates+params. Перед API-запросом всегда проверяем кеш.
2. Context window hygiene — stdout ограничен 30 строками. Полные данные в CSV/файл. Кеш доступен через grep/rg для поиска без загрузки в контекст.
3. Точные данные — accuracy=1 (без сэмплирования), фильтр isRobot по умолчанию.
4. Атрибуция — дефолт lastsign (последний значимый источник). Спрашиваем пользователя при первом запуске.

Workflow

STOP! Перед любым анализом:

1. Получи список счётчиков:

``bash bash scripts/counters.sh ``

1. Спроси пользователя (если счётчик не очевиден из контекста):

`` "О каком счётчике/сайте идёт речь? Укажите ID, название или домен." ` Если пользователь назвал сайт/домен — ищи через --search: `bash bash scripts/counters.sh --search "metallik" `` Это grep по TSV (id + name + site), поэтому находит и по домену.

1. Получи инфо о счётчике и его цели:

``bash bash scripts/counter_info.sh --counter <ID> bash scripts/goals.sh --counter <ID> ``

1. Спроси про конверсионные цели:

`` "Какие из этих целей являются конверсионными для вашего бизнеса? [список целей из goals.sh] Сохраню выбранные для будущих отчётов." ``

1. Сохрани конфигурацию в cache/counter_<id>/config.json:

``json { "attribution": "lastsign", "conversion_goals": [ {"id": 12345, "name": "Заказ оформлен"}, {"id": 67890, "name": "Заявка отправлена"} ] } ``

1. Запускай отчёты по задаче пользователя.

Сегменты и доступы

Для API-сегмента сначала зафиксируй понятное название и выражение filters. Создание и удаление без --apply показывают план и ничего не меняют. Перед записью сценарий читает свежую роль на счётчике; сервер API остаётся окончательным источником прав.

bash scripts/segments.sh --counter <ID> --action create \
  --name "Посетители карточек" \
  --expression "EXISTS(ym:pv:URL=@'/catalog/')"
# после проверки плана повторить с --apply

Получи точный логин от вызывающей задачи, затем проверь прямой доступ к счётчику и при необходимости подготовь минимальную роль:

bash scripts/grants.sh --counter <ID> --action get --login <LOGIN>
bash scripts/grants.sh --counter <ID> --action add \
  --login <LOGIN> --permission view
# после проверки плана повторить с --apply

Для использования сегмента обычно достаточно view. Не выдавай edit, если задача не требует менять счётчик. Если пользователь выбрал analyst или edit, передай эту роль через --permission; существующую роль меняй через update. Список /grants содержит прямые разрешения; владелец выводится отдельно, а представители аккаунта в этот список не входят. После записи верни вызывающей задаче номер счётчика, ID сегмента, логин и подтверждённую роль. Подробности: API-сегменты и прямые доступы к счётчику.

Scripts

Общий паттерн вызова:

bash scripts/<script>.sh --counter <ID> --date1 YYYY-MM-DD [--date2 ...] [--group month] [--csv path]

Не все скрипты поддерживают все общие параметры — см. Special params. Сценариям управления segments.sh и grants.sh для надёжного разбора JSON нужен Python 3.10+ либо uv; обычные отчёты по-прежнему работают без них.

Отчёт по целям

conversions.sh автоматически запрашивает цели частями по шесть и объединяет их в один CSV. Это работает для --all-goals, --goals и целей из config.json. При --all-goals список целей сначала обновляется через Management API. Объединение выполняется обычным awk; для запуска отчётов Python и uv не нужны. На каждую цель сохраняются три метрики: визиты с достижением, достижения и конверсия. Порядок целей в колонках соответствует выбранному списку.

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

--limit ограничивает число источников: без --group допустимо 1–100000 (по умолчанию 100); с --group — 1–30 (по умолчанию 30, параметр API top_keys). Даты при этом не сокращаются. Отчёт попадает в кеш и --csv только после успешного получения и объединения всех частей.

Общие параметры отчётных скриптов

Кеш-стратегия

Кеш хранится в cache/:

• counters.json + counters.tsv — все счётчики
• counter_<id>/info.json — метаданные (permanent)
• counter_<id>/goals.json + goals.tsv — цели
• counter_<id>/config.json — атрибуция, конверсионные цели
• counter_<id>/direct_clients.json — логины Директа
• counter_<id>/reports/*.csv — результаты отчётов

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

Для поиска по кешу: grep "text" cache/counters.tsv или rg "text" cache/.

Расширенные сценарии

• Популярные поисковые запросы
• Произвольные отчёты и JSON-запросы (drilldown, metrika_get и др.)
• Справочник dimensions/metrics
• Сравнение периодов год-к-году
• Расходы Директа и PnL
• API-сегменты для подбора аудитории в Директе
• Проверка и выдача доступа рекламным кабинетам
• Ограничения API (bytime, scope mixing, drilldown CSV)

Лимиты API

• Reporting API: ~200 запросов / 5 минут (при превышении — ждите ~5 минут)
• Скрипты автоматически обрабатывают 429 (Retry-After ≤ 60s → retry, иначе fail с сообщением)