/yandex-metrika

name: yandex-metrika
description: |
  Яндекс Метрика: детализация трафика по источникам и UTM-меткам,
  отчёты по конверсиям и поисковым системам, API-сегменты и доступы к счётчикам.
  Cache-first подход для гигиены контекстного окна.
  Triggers: яндекс метрика, yandex metrika, metrika analytics,
  метрика трафик, метрика конверсии, метрика отчёт, создать сегмент,
  доступ к счётчику, выдать доступ рекламному кабинету.

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 scripts/counters.sh

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

   "О каком счётчике/сайте идёт речь?
   Укажите ID, название или домен."

Если пользователь назвал сайт/домен — ищи через `--search`:

   bash scripts/counters.sh --search "metallik"

Это grep по TSV (id + name + site), поэтому находит и по домену.

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

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

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

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

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

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

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

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

Для 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-сегменты](references/SEGMENTS.md) и [прямые доступы к счётчику](references/ACCESS.md).

Scripts

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

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

| Script | Description | Special params | |--------|-------------|----------------| | `counters.sh` | Список счётчиков | `--search "query"` | | `goals.sh` | Цели счётчика | — | | `counter_info.sh` | Метаданные счётчика | — | | `traffic_summary.sh` | Трафик по источникам | — | | `conversions.sh` | Достижение целей | `--goals "ID,ID"` / `--all-goals`; по умолчанию из `config.json` | | `utm_report.sh` | UTM-разбивка | — | | `search_engines.sh` | Поисковые системы (organic) | — | | `ecommerce.sh` | Покупки, выручка, средний чек | `--currency RUB\|USD\|EUR`; авто из counter_info | | `direct_clients.sh` | Логины Директа | — | | `direct_costs.sh` | Расходы Директа (`ym:ad:*`) | `--direct-client-logins "login"`; нет `--group`/`--device`/`--source` | | `comparison.sh` | Сравнение двух периодов | `--date1a/--date2a/--date1b/--date2b`; `--dimension`, `--metrics` | | `segments.sh` | Список, просмотр, создание и удаление API-сегментов | `--action`; запись только с `--apply` | | `grants.sh` | Владелец и прямые доступы по логинам; роли `view`, `analyst`, `edit` | `--action`; запись только с `--apply` |

Не все скрипты поддерживают все общие параметры — см. **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 служебных метрик нет, но источники без конвер