> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bedolagam.ru/llms.txt
> Use this file to discover all available pages before exploring further.

# Настройка аналитики

> Подключение Яндекс Метрики и Google Ads в Cabinet

## Обзор

Cabinet поддерживает два счетчика аналитики:

| Сервис             | Что отслеживает                                             |
| ------------------ | ----------------------------------------------------------- |
| **Яндекс Метрика** | Посещения, поведение пользователей, карта кликов, конверсии |
| **Google Ads**     | Конверсии из рекламных кампаний Google                      |

Счетчики настраиваются через **админ-панель Cabinet** (не через `.env`). Скрипты аналитики динамически подключаются на все страницы Cabinet.

<Warning>
  Требуется работающий Cabinet с доступом к админ-панели.
</Warning>

## Яндекс Метрика

### Шаг 1: Создание счетчика

1. Откройте [Яндекс Метрика](https://metrika.yandex.ru/)
2. Войдите в аккаунт Яндекс
3. Нажмите **Добавить счетчик**
4. Заполните:
   * **Имя счетчика**: название вашего сервиса
   * **Адрес сайта**: URL вашего Cabinet (например, `cabinet.example.com`)
5. Включите опции:
   * **Вебвизор** — запись действий пользователей
   * **Карта кликов** — тепловая карта кликов
   * **Карта скроллинга** — глубина просмотра страниц
6. Нажмите **Создать счетчик**
7. Скопируйте **номер счетчика** (числовой ID, например `98765432`)

<Note>
  Код счетчика для вставки на сайт копировать не нужно — Cabinet подключает скрипт автоматически. Нужен только числовой ID.
</Note>

### Шаг 2: Ввод ID в Cabinet

1. Откройте Cabinet → **Админ-панель** → **Настройки** → вкладка **Аналитика**
2. В поле **Яндекс Метрика ID** введите числовой ID счетчика
3. Нажмите **Сохранить**

После сохранения Cabinet автоматически подключит скрипт `mc.yandex.ru/metrika/tag.js` с параметрами:

* `clickmap: true` — карта кликов
* `trackLinks: true` — отслеживание переходов
* `accurateTrackBounce: true` — точный учет отказов

### Шаг 3: Проверка

1. Откройте Cabinet в браузере
2. Перейдите в [Яндекс Метрика](https://metrika.yandex.ru/) → ваш счетчик
3. В разделе **Сводка** должны появиться визиты (данные обновляются с задержкой до 5 минут)
4. Проверьте через DevTools браузера (F12 → Network): должен загружаться `tag.js` от `mc.yandex.ru`

## Google Ads

Google Ads отслеживает конверсии из рекламных кампаний — покупки, регистрации и другие целевые действия.

### Шаг 1: Создание действия-конверсии

1. Откройте [Google Ads](https://ads.google.com/)
2. Перейдите в **Цели** → **Конверсии** → **Сводка**
3. Нажмите **Новое действие-конверсия**
4. Выберите **Веб-сайт**
5. Укажите URL вашего Cabinet
6. Настройте конверсию:
   * **Категория**: выберите подходящую (например, "Покупка" или "Регистрация")
   * **Название конверсии**: описательное название
   * **Ценность**: укажите при необходимости
7. Нажмите **Создать и продолжить**

### Шаг 2: Получение тега и ID

1. На шаге настройки тега выберите **Установить тег вручную**
2. Из кода тега найдите:
   * **Conversion ID** — формат `AW-1234567890` (идентификатор после `id=` в URL скрипта gtag)
   * **Conversion Label** — строка вида `AbCdEfGhIjKl` (значение `send_to` после `/`)
3. Скопируйте оба значения

Пример из кода тега Google:

```
gtag('config', 'AW-1234567890');
gtag('event', 'conversion', {'send_to': 'AW-1234567890/AbCdEfGhIjKl'});
```

Здесь:

* `AW-1234567890` — это **Google Ads ID**
* `AbCdEfGhIjKl` — это **Google Ads Label**

### Шаг 3: Ввод в Cabinet

1. Откройте Cabinet → **Админ-панель** → **Настройки** → вкладка **Аналитика**
2. Заполните:
   * **Google Ads ID**: `AW-1234567890`
   * **Google Ads Label**: `AbCdEfGhIjKl`
3. Нажмите **Сохранить**

После сохранения Cabinet подключит `googletagmanager.com/gtag/js` и настроит отслеживание конверсий.

### Шаг 4: Проверка

1. Откройте Cabinet в браузере
2. В Google Ads перейдите в **Цели** → **Конверсии** → **Сводка**
3. Статус конверсии должен измениться на "Запись конверсий" (может занять до 24 часов)
4. Через DevTools (F12 → Network): должен загружаться `gtag/js` от `googletagmanager.com`

## Админ-панель: вкладка Аналитика

На вкладке **Аналитика** в настройках Cabinet отображаются:

| Поле              | Формат        | Пример          |
| ----------------- | ------------- | --------------- |
| Яндекс Метрика ID | Только цифры  | `98765432`      |
| Google Ads ID     | `AW-` + цифры | `AW-1234567890` |
| Google Ads Label  | Строка        | `AbCdEfGhIjKl`  |

Рядом с каждым счетчиком отображается статус:

* **Активен** — ID заполнен, скрипт подключается
* **Не настроен** — поле пустое, скрипт не подключается

Для отключения счетчика очистите соответствующее поле и сохраните.

## Оффлайн-конверсии Яндекс Метрики

Помимо клиентской аналитики (JavaScript-счётчик), бот поддерживает отправку **оффлайн-конверсий** в Яндекс Метрику через Measurement Protocol. Это позволяет отслеживать конверсии от пользователей, которые пришли через рекламу в Яндексе и совершили покупку в Telegram-боте или Cabinet.

### Как работает

1. **Захват CID**: Яндекс Метрика присваивает каждому посетителю уникальный Client ID (CID). Бот захватывает CID из нескольких источников:
   * Параметр `/start` в Telegram-боте (ссылка вида `https://t.me/bot?start=utm_ya_XXXXXXXXXX`)
   * Авторизация в Cabinet
   * Переходы на лендинги
2. **Сохранение CID**: CID привязывается к пользователю в базе данных
3. **Отправка конверсий**: При покупке подписки бот отправляет POST-запрос на `https://mc.yandex.ru/collect` с данными конверсии (CID, цена, валюта)

### Настройка

#### Шаг 1: Получение Measurement Secret

1. Откройте [Яндекс Метрика](https://metrika.yandex.ru/) → ваш счётчик
2. Перейдите в **Настройка** → **Оффлайн-конверсии**
3. Скопируйте **Measurement Secret** (или создайте новый)

#### Шаг 2: Переменные окружения

```env theme={null}
YANDEX_OFFLINE_CONV_ENABLED=true
YANDEX_OFFLINE_CONV_COUNTER_ID=98765432
YANDEX_OFFLINE_CONV_MEASUREMENT_SECRET=your_measurement_secret
YANDEX_OFFLINE_CONV_START_PREFIX=utm_ya_
YANDEX_OFFLINE_CONV_CURRENCY=RUB
```

| Переменная                               | Описание                               | По умолчанию |
| ---------------------------------------- | -------------------------------------- | ------------ |
| `YANDEX_OFFLINE_CONV_ENABLED`            | Включить отправку оффлайн-конверсий    | `false`      |
| `YANDEX_OFFLINE_CONV_COUNTER_ID`         | ID счётчика Яндекс Метрики             | —            |
| `YANDEX_OFFLINE_CONV_MEASUREMENT_SECRET` | Секрет для Measurement Protocol        | —            |
| `YANDEX_OFFLINE_CONV_START_PREFIX`       | Префикс для захвата CID из `/start`    | `utm_ya_`    |
| `YANDEX_OFFLINE_CONV_DL`                 | URL страницы (параметр `dl` в запросе) | —            |
| `YANDEX_OFFLINE_CONV_DT`                 | Заголовок страницы (параметр `dt`)     | —            |
| `YANDEX_OFFLINE_CONV_CURRENCY`           | Валюта конверсий                       | `RUB`        |

#### Шаг 3: Настройка UTM-ссылки

Для захвата CID через Telegram создайте ссылку вида:

```
https://t.me/your_bot?start=utm_ya_{ClientID}
```

Где `{ClientID}` подставляется Яндексом при клике на рекламу. В рекламных кампаниях Яндекс Директ используйте параметр `{YCLID}` или настройте передачу CID через лендинг.

### Проверка

1. Убедитесь что в логах бота появляются записи о захвате CID:
   ```bash theme={null}
   docker logs <bot_container> 2>&1 | grep -i "yandex.*cid"
   ```
2. После покупки проверьте в Яндекс Метрике раздел **Отчёты** → **Оффлайн-конверсии** (данные появляются с задержкой до нескольких часов)

## S2S Postback

S2S (Server-to-Server) постбэки позволяют отправлять HTTP-запросы на внешние URL при ключевых событиях: регистрация пользователя, активация триала и покупка подписки. Используется для интеграции с рекламными сетями, CPA-сетями и трекерами конверсий.

### Настройка

```env theme={null}
S2S_POSTBACK_ENABLED=true
S2S_POSTBACK_REGISTRATION_URL=https://tracker.example.com/postback?event=reg&uid={user_id}
S2S_POSTBACK_TRIAL_URL=https://tracker.example.com/postback?event=trial&uid={user_id}
S2S_POSTBACK_PURCHASE_URL=https://tracker.example.com/postback?event=purchase&uid={user_id}&amount={amount}
```

| Переменная                      | Описание                          | По умолчанию |
| ------------------------------- | --------------------------------- | ------------ |
| `S2S_POSTBACK_ENABLED`          | Включить S2S постбэки             | `false`      |
| `S2S_POSTBACK_REGISTRATION_URL` | URL постбэка при регистрации      | —            |
| `S2S_POSTBACK_TRIAL_URL`        | URL постбэка при активации триала | —            |
| `S2S_POSTBACK_PURCHASE_URL`     | URL постбэка при покупке подписки | —            |

<Note>
  Постбэки отправляются асинхронно и не блокируют основную логику. Ошибки отправки логируются, но не влияют на процесс покупки.
</Note>

## Устранение проблем

### Счетчик не появляется на сайте

1. Проверьте что ID сохранен в админ-панели (вкладка Аналитика)
2. Обновите страницу Cabinet (Ctrl+Shift+R для сброса кеша)
3. Проверьте DevTools → Network на наличие запросов к `mc.yandex.ru` или `googletagmanager.com`

### Яндекс Метрика показывает 0 визитов

* Данные появляются с задержкой до 5 минут
* Проверьте что в настройках счетчика указан правильный домен
* Убедитесь что AdBlock или аналогичные расширения не блокируют скрипт

### Google Ads не фиксирует конверсии

* Статус обновляется до 24 часов после установки
* Проверьте правильность Conversion ID (формат `AW-*`) и Label
* Убедитесь что на аккаунте Google Ads есть активные кампании