# Yandex Metrika Assistant

> OpenClaw + Яндекс.Метрика API — stat/Logs/management, OAuth, presets, UTM, цели, CSV, квоты; плагин yandex-metrika-assistant.

- **Type:** Skill
- **Install:** `agentstack add skill-horosheff-yandex-metrika-assistant-yandex-metrika-assistant`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Horosheff](https://agentstack.voostack.com/s/horosheff)
- **Installs:** 0
- **Category:** [Data & Analytics](https://agentstack.voostack.com/c/data-and-analytics)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Horosheff](https://github.com/Horosheff)
- **Source:** https://github.com/Horosheff/yandex-metrika-assistant

## Install

```sh
agentstack add skill-horosheff-yandex-metrika-assistant-yandex-metrika-assistant
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Яндекс.Метрика API — заточка под **OpenClaw**

Плагин: **`yandex-metrika-assistant`** (`openclaw.plugin.json` в этой папке).  
Цель: ноль сюрпризов — сначала **конфиг и секреты**, потом **правильный endpoint**, без выдуманных метрик и без утечки токена.

---

## Онбординг человека (порядок ответов агента)

**Если токена ещё нет** (пользователь только ставит навык или не настроил ключ):

1. **Сначала** дай ссылку и краткое резюме установки: **`{baseDir}/docs/INSTALL-FOR-HUMANS-RU.md`** (шаги OpenClaw + OAuth + куда вставить ключ).
2. **Обязательно** перечисли, какие **галочки в приложении Яндекс OAuth** нужны для Метрики (таблица из того же файла / шаг 2): статистика и чтение, создание/изменение счётчиков, при необходимости расходы, параметры пользователей, офлайн-данные.
3. Укажи **канал поддержки:** [**https://t.me/maya_pro**](https://t.me/maya_pro) — вопросы по установке и сценариям; **не** проси кидать токен в Telegram публично.
4. Затем — получение токена: **`{baseDir}/docs/INSTRUCTION-GET-TOKEN-RU.md`** (или ссылка `authorize` с `oauthClientId` из конфига).
5. Напомни: ключ хранить в **`oauthToken`** плагина или в **`YANDEX_METRIKA_OAUTH_TOKEN`**, не в чате.

**После того как ключ добавлен** (пользователь сообщил, что сохранил токен в конфиг, или токен уже есть в конфиге/окружении):

- Не проси продиктовать токен.
- Заверши ответ блоком **«С чего начать»** — предложи **3–5 коротких вариантов** (нумерованный список), например:
  1. Показать список счётчиков Метрики.  
  2. Визиты по дням за последние 7 дней.  
  3. Сводка по источникам трафика.  
  4. Топ страниц по просмотрам.  
  5. Конверсии по цели (если есть цели).  

Полный список идей — **`{baseDir}/docs/INSTALL-FOR-HUMANS-RU.md`** (раздел «После добавления ключа») и **`{baseDir}/docs/10-user-intents-matrix.md`**.

---

**Типовые формулировки пользователей** («откуда трафик», «цели», «UTM», «география», «сравни периоды», «выгрузи CSV», «сырые логи») — смотри матрицу: **`{baseDir}/docs/10-user-intents-matrix.md`** (разбивка по разделам A–J + ссылки на официальные примеры и пресеты).

---

## OpenCLaw: порядок работы (строго)

1. **Токен** брать только из:
   - настроек плагина **`oauthToken`** (см. `configSchema` в `openclaw.plugin.json`), **или**
   - переменной окружения **`YANDEX_METRIKA_OAUTH_TOKEN`** (если хост OpenClaw так настроен), **или**
   - пользователь явно передал токен **один раз** для текущей сессии — тогда использовать, но **не** повторять токен обратно в ответе и **не** вставлять в файлы репозитория.
2. Если токена **нет** — **не** вызывать API и **не** придумывать ответ Метрики. Следуй разделу **«Онбординг человека»** выше: сначала **`{baseDir}/docs/INSTALL-FOR-HUMANS-RU.md`**, галочки OAuth, [**@maya_pro**](https://t.me/maya_pro), затем **`{baseDir}/docs/INSTRUCTION-GET-TOKEN-RU.md`**; при наличии **`oauthClientId`** — ссылка `authorize?response_type=token&client_id=...`.
3. **`defaultCounterId`** из конфига: если пользователь не назвал счётчик — используй это значение и **одной строкой** напиши: «использую счётчик по умолчанию из конфига OpenClaw».
4. Любые `curl`/команды в чат — только с плейсхолдером **`$env:YANDEX_METRIKA_OAUTH_TOKEN`** или «подставь токен из секрета OpenClaw», **не** вставляй токен целиком.
5. **Windows / PowerShell:** если `curl -H "Authorization: OAuth …"` даёт ошибки из‑за кавычек — используй **`Invoke-RestMethod`** с `-Headers @{ Authorization = 'OAuth ' + $env:YANDEX_METRIKA_OAUTH_TOKEN }`** или заголовок через **конкатенацию** в скобках: `-H ('Authorization: OAuth ' + $env:YANDEX_METRIKA_OAUTH_TOKEN)`. Подробно: **`{baseDir}/docs/OPENCLAW-AGENT.md`**, **`{baseDir}/docs/EXAMPLES.md`**.

---

## Быстрые рецепты (копипаста для пользователя, Windows PowerShell)

Подстановка токена из env (удобно рядом с OpenClaw):

```powershell
$env:YANDEX_METRIKA_OAUTH_TOKEN = ""
$cid = ""
# Надёжнее без вложенных кавычек вокруг токена:
curl.exe -s -H ('Authorization: OAuth ' + $env:YANDEX_METRIKA_OAUTH_TOKEN) `
  "https://api-metrika.yandex.net/management/v1/counters?per_page=20"
```

Отчёт «визиты за последние 7 дней» (проверь `ids` и метрики по задаче):

```powershell
curl.exe -s -G "https://api-metrika.yandex.net/stat/v1/data" `
  --data-urlencode "ids=$cid" `
  --data-urlencode "metrics=ym:s:visits" `
  --data-urlencode "date1=7daysAgo" `
  --data-urlencode "date2=yesterday" `
  -H ('Authorization: OAuth ' + $env:YANDEX_METRIKA_OAUTH_TOKEN)
```

---

## Сценарий: «пришли ежедневную статистику по сайту maya»

Так OpenClaw **должен** отработать запрос (и что увидит человек в ответе).

### Внутренние шаги агента

1. **Токен** — из `oauthToken` / `YANDEX_METRIKA_OAUTH_TOKEN`. Нет токена → стоп, ссылка на `{baseDir}/docs/INSTRUCTION-GET-TOKEN-RU.md`.
2. **Счётчик** — если в конфиге есть **`defaultCounterId`** и пользователь не просил другой сайт, можно спросить: «использовать счётчик по умолчанию?» или сразу использовать, если контекст однозначен.
3. Иначе: **`GET /management/v1/counters`** с **`search_string=maya`** (или фрагмент домена: `mayai`, `blog.mayai`). Если **несколько** счётчиков — перечислить `id`, `name`, `site` и **попросить выбрать** один `id`.
4. **Период** — если не сказан, предложить по умолчанию, например **вчера − 29 дней … вчера** (без «сегодня» для стабильности данных) или уточнить у пользователя.
5. **Ежедневная разбивка** — API отчётов:
   - вариант А: `GET .../stat/v1/data` с группировкой по дню визита **`dimensions=ym:s:date`**, **`metrics`** по задаче (часто `ym:s:visits`, при необходимости `ym:s:pageviews`, `ym:s:users` — имена проверять в [справочнике](https://yandex.ru/dev/metrika/ru/stat/));
   - вариант Б: `GET .../stat/v1/data/bytime` — если удобнее именно «по времени» (см. openapi в доке stat).
6. Вызвать API (или дать пользователю **одну** готовую команду с плейсхолдерами), распарсить JSON.
7. Если в ответе **`contains_sensitive_data": true`** — кратко предупредить про ограничение раскрытия данных.

### Как выглядит ответ человеку (шаблон)

Агент пишет **короткое резюме**, затем **таблицу или список по дням** (дата → визиты / просмотры / и т.д.), без сырого JSON на экран целиком, если пользователь не просил сырой вывод.

Пример формулировки:

- «Счётчик: **LAYMI** (`id` …), сайт **blog.mayai.ru**, период **…**. Ниже визиты по дням. Данные из API Метрики, токен из конфига OpenClaw.»
- Далее строки вида: `2025-03-01 — визиты: 120`, …
- Примечание при 429: «Сработала квота отчётов; повтори через несколько минут» (`{baseDir}/docs/04-quotas.md`).

### Пример цепочки запросов (PowerShell, без секрета в логах чата)

```powershell
# 1) Найти счётчик по подстроке (maya / mayai)
curl.exe -s -G "https://api-metrika.yandex.net/management/v1/counters" `
  --data-urlencode "search_string=maya" `
  --data-urlencode "per_page=50" `
  -H ('Authorization: OAuth ' + $env:YANDEX_METRIKA_OAUTH_TOKEN)

# 2) Ежедневные визиты (подставь $cid из шага 1)
curl.exe -s -G "https://api-metrika.yandex.net/stat/v1/data" `
  --data-urlencode "ids=$cid" `
  --data-urlencode "dimensions=ym:s:date" `
  --data-urlencode "metrics=ym:s:visits" `
  --data-urlencode "date1=30daysAgo" `
  --data-urlencode "date2=yesterday" `
  --data-urlencode "sort=ym:s:date" `
  -H ('Authorization: OAuth ' + $env:YANDEX_METRIKA_OAUTH_TOKEN)
```

Точные **`metrics`/`dimensions`** при спорных отчётах — только из официальной доки, не по памяти модели.

---

## Сценарий: «на какую страницу больше трафика?»

Запрос про **страницы** — это снова **API отчётов** `GET .../stat/v1/data`, после того же **разрешения счётчика** (id / `defaultCounterId` / `search_string`), что и в сценарии выше.

### Смысл «трафика»

- Чаще всего пользователь имеет в виду **просмотры страниц** (хиты): группировка по URL страницы + метрика просмотров. Тогда в одном запросе используется **только префикс `ym:pv:`** (визиты и хиты в основном наборе не смешивать).
- Если нужны **входы / визиты с первой страницы** (лендинги), это другой отчёт: группировки уровня **визита** (`ym:s:...`), другие метрики — уточнить у пользователя или дать оба коротко («по просмотрам лидирует …, по визитам на входе …»), опираясь на [справочник группировок](https://yandex.ru/dev/metrika/ru/stat/).

### Типовой запрос (топ URL по просмотрам)

Параметры (имена перепроверять в доке при смене версии API):

- `dimensions` — URL страницы на уровне хита, например **`ym:pv:URL`**.
- `metrics` — **`ym:pv:pageviews`** (и при необходимости ещё метрики из того же множества `ym:pv:`).
- `sort` — по убыванию просмотров, в доке Метрики для сортировки по убыванию часто используется **`-`** перед метрикой (см. `{baseDir}/docs/05-reports-api-stat.md`).
- `limit` — топ **10–20** URL, чтобы ответ был читаемым.
- `date1` / `date2` — как в других сценариях (если не заданы — default или вопрос пользователю).

### Как выглядит ответ человеку

Коротко: период, счётчик, что считали (**просмотры по URL**). Затем список: **URL → число просмотров** (топ N). Длинные URL можно обрезать визуально с «…», полный URL — по наведению или второй строкой при необходимости.

### Пример `curl` (PowerShell)

```powershell
curl.exe -s -G "https://api-metrika.yandex.net/stat/v1/data" `
  --data-urlencode "ids=$cid" `
  --data-urlencode "dimensions=ym:pv:URL" `
  --data-urlencode "metrics=ym:pv:pageviews" `
  --data-urlencode "sort=-ym:pv:pageviews" `
  --data-urlencode "limit=15" `
  --data-urlencode "date1=30daysAgo" `
  --data-urlencode "date2=yesterday" `
  -H ('Authorization: OAuth ' + $env:YANDEX_METRIKA_OAUTH_TOKEN)
```

Если API вернёт ошибку совместимости группировки и метрики — не «угадывать» замену, а свериться с актуальным openapi для `/stat/v1/data` на сайте Метрики.

---

## Маршрутизация: что дергать

| Запрос пользователя | Куда | Файл |
|---------------------|------|------|
| Отчёт, метрики, период, сегменты | `GET .../stat/v1/data` (и др. из stat) | `{baseDir}/docs/05-reports-api-stat.md` |
| Топ страниц, «куда больше трафика» | `stat/v1/data`, группировка URL (`ym:pv:`) | сценарий ниже, `{baseDir}/docs/05-reports-api-stat.md` |
| Сырые логи, выгрузка | `management/v1/counter/{id}/logrequests...` | `{baseDir}/docs/06-logs-api.md` |
| Список счётчиков, цели, настройки | `management/v1/...` | `{baseDir}/docs/08-management-quickstart.md` |
| Загрузка расходов, CRM, офлайн | data-import | `{baseDir}/docs/07-data-import.md` |
| 401/403, scope | OAuth | `{baseDir}/docs/03-auth-oauth.md`, `{baseDir}/docs/INSTRUCTION-GET-TOKEN-RU.md` |
| 429 | Квоты | `{baseDir}/docs/04-quotas.md` |
| «Что ещё спрашивают / не знаю какой отчёт» | Матрица намерений | `{baseDir}/docs/10-user-intents-matrix.md` |

Смешанная задача: **сначала** `counters` или `defaultCounterId`, **потом** stat/logs.

---

## Железные правила API

- Заголовок: **`Authorization: OAuth `** (слово `OAuth` и пробел обязательны).
- Хост: **`https://api-metrika.yandex.net`**
- В одном запросе **stat** не смешивать **`ym:s:`** и **`ym:pv:`** в основных `metrics`/`dimensions` (детали в `{baseDir}/docs/05-reports-api-stat.md`).
- Лимиты: до **20** метрик, **10** группировок в `/stat/v1/data`; **200 запросов / 5 мин** на этот endpoint на пользователя; Logs с IP — **10**/с.
- Имена метрик/группировок **не выдумывать** — только из официального справочника (ссылки в `{baseDir}/docs/01-links-and-hub.md`).
- После скачивания Logs — **`clean`**, квота хранилища **10 ГБ** на счётчик (`{baseDir}/docs/06-logs-api.md`).

---

## Формат ответа агента OpenClaw

1. Что сделано / что предлагается (1 фраза).  
2. Откуда взяты токен и счётчик (конфиг / env / спросил у пользователя).  
3. Команда или URL-шаблон **без секрета**.  
4. Как проверить успех (HTTP 200, поля JSON).  
5. Риски: квоты, `contains_sensitive_data`, 429.

---

## Карта файлов

| Файл | Назначение |
|------|------------|
| `openclaw.plugin.json` | Контракт OpenClaw: `oauthToken`, `defaultCounterId`, `oauthClientId` |
| `{baseDir}/docs/INSTALL-FOR-HUMANS-RU.md` | Установка: OpenClaw, OAuth-галочки, TG, после ключа — с чего начать |
| `{baseDir}/docs/INSTRUCTION-GET-TOKEN-RU.md` | Токен для людей |
| `{baseDir}/docs/OPENCLAW-AGENT.md` | Установка: нет HOOK.md; PowerShell без ловушек кавычек |
| `{baseDir}/scripts/exchange-yandex-oauth-code.ps1` | Обмен `code` → token |
| `{baseDir}/docs/01`–`09` | Справка по разделам API |
| `{baseDir}/docs/10-user-intents-matrix.md` | **Матрица вопросов пользователей → API** (ресёрч по примерам и пресетам) |

Официальный хаб: https://yandex.ru/dev/metrika

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Horosheff](https://github.com/Horosheff)
- **Source:** [Horosheff/yandex-metrika-assistant](https://github.com/Horosheff/yandex-metrika-assistant)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-horosheff-yandex-metrika-assistant-yandex-metrika-assistant
- Seller: https://agentstack.voostack.com/s/horosheff
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.