# 🧭 Атрибуция в отчётах

Эта статья описывает логику атрибуции в двух случаях:

- A/B‑тесты внутри кампаний
- Отчёт по рекомендательным стратегиям

Здесь вы найдёте ключевые определения, правила расчёта и наглядные диаграммы.

Если вы хотите воспроизвести эти расчёты из CSV-выгрузки сырых данных в BI, используйте отдельную инструкцию: [Как воспроизвести отчеты из raw data](../../data_import/reproduce_reports_from_raw_data.md).

---

## 📘 Термины и определения

- **Триггер атрибуции**: событие, от которого начинается отсчёт окна атрибуции. Для A/B‑тестов — это `Variation Impression` или `Event is triggered` (по настройке версии теста). Для рекомендаций — «взаимодействие с виджетом» (видимый показ и/или клик, см. ниже).
- **Окно атрибуции**: период времени, в течение которого целевое событие/метрика засчитывается как результат взаимодействия. Может быть «по сессии» или фиксированным количеством дней.
- **Клейкость вариации**: способ удержания вариации у пользователя — по сессии (на каждую сессию) или по пользователю (закрепляется до конца текущей версии теста).
- **Дедупликация покупок**: способ учета, при котором один заказ засчитывается один раз. Технически выполняется по `uniqueTransactionId`.
 - **Целевая метрика/событие**: метрика, по которой оценивается версия теста. Это может быть событие покупки (`purchase-v1`), выручка, клик, кастомное событие и т.д. Атрибуция применяется к соответствующим событиям в окне.
  - Для непокупочных метрик (например, клики, просмотры) дедупликация не применяется.
 - **Событие покупки (`purchase-v1`)**: все события, обозначающие покупки (например, `Purchase`, `Offline purchase`), нормализуются в единый поток с типом `purchase-v1`. Все расчёты выручки и количества покупок выполняются именно по событиям `purchase-v1`.

### Легенда событий (поток)
- `Variation Impression` — показ вариации A/B (type=2)
- `Product Click` — клик по товару (type=6)
- `Visible Impression` — видимый показ (type=7)
- `purchase-v1` — событие покупки (нормализованный поток, type=1)

---

## 🎯 Атрибуция в A/B‑тестах

Настраивается в интерфейсе при создании/редактировании версии A/B‑теста: триггер (показ, событие), клейкость вариации и окно атрибуции.

### Триггеры
- `Variation Impression` — атрибуция начинается с момента показа вариации
- `Event is triggered` — атрибуция начинается с указанного события

### Клейкость вариации
- **По сессии** — при каждой новой `sessionId` пользователь может получить новую вариацию. Атрибуция применима только внутри той же сессии, что и триггер.
- **По пользователю** — вариация закрепляется за `uid` **на весь период жизни текущей версии теста** (до её смены), а не на окно атрибуции.

### Расчёт метрик
1) Находим показы вариации или срабатывания триггера в рамках выбранной версии теста.
2) Отбираем целевые события пользователей (по тому же `uid`), произошедшие после триггера и попадающие в окно атрибуции.
3) Для метрик, основанных на покупках/выручке, заказы дедуплицируются по `uniqueTransactionId`.
4) Для непокупочных целей (например, клики) считаем соответствующие события целевой метрики в этом же окне.

#### Диаграмма: клейкость «по пользователю»

```mermaid
sequenceDiagram
  participant E as Event Stream
  participant A as Attribution (A/B Version)
  participant C as Report (Счетчики)
  Note over E: uid (совпадает), sessionId (совпадает для session окна), moscowTime
  rect rgba(200, 245, 200, 0.25)
    Note over A: Окно атрибуции: Session или N дней с момента показа Variation Impression (Считается в отчёте)
    E->>A: Variation Impression (момент показа)
    Note over A: Вариация закреплена на uid до конца версии
    E-->>A: purchase-v1 (покупка внутри окна)
    A-->>C: +1 Purchases (дедупликация по uniqueTransactionId)
    A-->>C: +Revenue (value)
    E-->>A: purchase-v1 (покупка внутри окна)
    A-->>C: +1 Purchases (дедупликация по uniqueTransactionId)
    A-->>C: +Revenue (value)
  end
  E-->>A: purchase-v1 (покупка вне окна)
  Note over C: Вне окна — не считается (счетчик без изменений)
```

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

---

## 🔎 Атрибуция в отчётах по рекомендациям

Этот раздел относится к отчёту «Отчёт по рекомендательным стратегиям». Логика атрибуции влияет на метрики `Direct Revenue`, `Direct Purchases`, `Assisted Revenue` и др.

### Окно атрибуции
- Настраивается прямо в отчёте
- Варианты: `Session`, 1 день, 7 дней, 14 дней, 30 дней
- По умолчанию: 30 дней

### Direct атрибуция (прямая)
Покупка считается прямой, если выполняются все условия:
1) Был **клик по товару** в виджете (`Product Click`)
2) Зафиксировано событие **purchase-v1** по **кликнутому SKU** в пределах окна атрибуции
3) Все события относятся к одному и тому же пользователю — совпадает `uid`
4) Для окна `Session` также совпадает `sessionId`

`Visible Impression` используется в метриках видимости, `CTR` и `Direct Revenue per 1000`, но direct-покупка для точного SKU считается от клика по товару к покупке.

```mermaid
sequenceDiagram
  participant E as Event Stream
  participant R as Attribution (Recs)
  participant C as Report (Счетчики)
  Note over E: uid (совпадает), sessionId, sku, group_id, moscowTime
  rect rgba(200, 245, 200, 0.25)
    Note over R: Окно атрибуции: Session или N дней с момента Product Click (Считается в отчёте)
    E->>R: type=6 Product Click sku=A
    E->>R: type=1 purchase-v1 sku=A (внутри окна)
    R-->>C: +1 Direct Purchases (дедупликация по uniqueTransactionId);
  end
  E->>R: type=1 purchase-v1 (вне окна)
  Note over C: Вне окна — не считается (счетчик без изменений)
```

> Для метрики **Direct Revenue (All Variants)** вместо точного совпадения SKU
> засчитывается также покупка другого SKU из той же группы (`group_id`).

> Если вы считаете отчет из raw CSV, точный `All Variants` не воспроизводится: в текущем raw export нет `groupId` и `eventCartGroupId`.

### Дедупликация в отчётах по рекомендациям
- В сводном блоке по всем стратегиям — **дедупликация есть**: один заказ учитывается один раз (по `Transaction ID`).
- В таблице «по стратегиям» — **дедупликации нет**: один и тот же заказ может быть засчитан нескольким стратегиям, если пользователь взаимодействовал с ними.

## 🏬 Атрибуция офлайн‑покупок

Атрибуция офлайн‑покупок полностью совпадает по логике с онлайном — никакой особой обработки нет. Должны выполняться те же критерии:

- Триггер начала окна атрибуции (для A/B — `Variation Impression`/`Event is triggered`; для стратегий — `Product Click`).
- Событие офлайн‑покупки (`purchase-v1`) попадает в окно атрибуции (Session или N дней).
- Идентификаторы пользователя совпадают: тот же `uid` (или `user_id`, если у вас так настроено сопоставление).

Как передавать офлайн‑покупку:

- Отправьте событие `purchase-v1` с:
  - тем же идентификатором пользователя, что и на сайте;
  - корректным временем события (`moscowTime`) = фактическая дата/время покупки (для проверки попадания в окно);
  - `uniqueTransactionId` для дедупликации заказа;

Рекомендация по данным:
- Создайте отдельный источник в [Data → Sources](/Integration/data/data.md#подключение-источников-и-потребителей-данных) для офлайн‑потока, чтобы в отчётах можно было фильтровать и сравнивать источники (онлайн/офлайн).