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

# Отправка событий через SDK - захват событий на клиенте

> Didit: захват входов, игровых действий и сессий с устройства по токену с ограниченными правами. Привязка субъекта и сеть проверяются на сервере.

Большинство [событий](https://docs.didit.me/ru/transaction-monitoring/events.md), важных для борьбы с мошенничеством, происходит на устройстве: вход, сессия, игровой раунд, телеметрия временных характеристик, которая отличает человека от скрипта. Канал устройства отправляет их без API-ключа в браузере.

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

## Порядок работы

**1. Выпустите учётные данные мониторинга**

Ваш бэкенд вызывает `POST /v3/events/sdk-token/` с вашим API-ключом и `vendor_data` пользователя.

**2. Отправьте событие с устройства**

Приложение отправляет запрос на `POST /v1/events/` (или `POST /v1/events/batch/`) с заголовком `X-Monitoring-Token`.

**3. Правила работают как обычно**

Событие обогащается, агрегируется и проверяется по тем же [правилам](https://docs.didit.me/ru/transaction-monitoring/event-rules.md), по которым проверяется событие, отправленное с сервера.

## Выпуск учётных данных

> [!NOTE]
>
> Для выпуска требуется, чтобы [приём событий](https://docs.didit.me/ru/transaction-monitoring/events.md) был включён для приложения. Пока он выключен, этот endpoint отвечает `403` с `{"code": "event_monitoring_disabled"}`, а не выдаёт учётные данные, которые не смогут ничего записать.

```bash theme={null}
curl -X POST https://verification.didit.me/v3/events/sdk-token/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user_391",
    "allowed_event_categories": ["auth", "session", "gameplay"],
    "ttl_seconds": 900,
    "max_uses": 1000,
    "bind_to_origin": "https://operator.example"
  }'
```

```json theme={null}
{
  "monitoring_token": "…",
  "expires_at": "2026-08-31T21:00:00Z",
  "allowed_event_categories": ["auth", "session", "gameplay"],
  "max_uses": 1000,
  "bind_to_origin": "https://operator.example"
}
```

| Поле | По умолчанию | Примечания |
| - | - | - |
| `vendor_data` | обязательно | Субъект, которому принадлежат все события, отправленные с этими учётными данными. |
| `entity_type` | `individual` | `individual` или `company`. |
| `allowed_event_categories` | все | Ограничивает категории событий, которые могут записать утёкшие учётные данные. |
| `ttl_seconds` | 900 | 60 - 86400. |
| `max_uses` | 1000 | Одно использование на **событие**, а не на запрос. |
| `bind_to_origin` | нет | Если задано, `Origin` браузера должен совпадать точно. |

## Отправка

```bash theme={null}
curl -X POST https://verification.didit.me/v1/events/ \
  -H "X-Monitoring-Token: THE_MINTED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "session-abc-login-1",
    "event_category": "auth",
    "action_type": "login",
    "occurred_at": "2026-08-31T20:40:31.123Z",
    "session": { "session_id": "web-session-abc", "sequence": 1 },
    "device_context": { "fingerprint": "didit-fp-v2:a8c1" },
    "payload": { "method": "password" }
  }'
```

Обратите внимание, что тело запроса **не** содержит: ни API-ключа, ни субъекта. Оба обеспечиваются на стороне сервера.

## Что проверяет сервер

* **Привязка к субъекту.** Учётные данные привязаны к одному `vendor_data` в момент выпуска. Блок `subject` в теле запроса перезаписывается, поэтому подменённый клиент не может писать в хронологию другого пользователя.
* **Сетевой контекст.** Адрес, user agent, accept-language и origin берутся из запроса, и эти значения, вычисленные сервером, важнее любых подсказок клиента при оценке правил. В данных правила это различие фиксируется как [источник поля](https://docs.didit.me/ru/transaction-monitoring/event-rules.md#доказательства).
* **Ограничение категорий.** Учётные данные, ограниченные категорией `session`, не могут отправить событие `payment`: сервер отклоняет его с `400`.
* **Бюджет использований.** Пакет расходует одно использование на каждое событие, поэтому пакет из 500 событий не может пройти через учётные данные на 10 использований как одно использование.
* **Привязка к origin.** Если задано `bind_to_origin`, запрос, `Origin` которого не совпадает, отклоняется, в том числе запрос без `Origin` вообще.

## Пакетная отправка

```bash theme={null}
curl -X POST https://verification.didit.me/v1/events/batch/ \
  -H "X-Monitoring-Token: THE_MINTED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "events": [ { "…": "…" }, { "…": "…" } ] }'
```

До 500 событий за одну отправку, с теми же результатами по каждому элементу, что и у [пакетного endpoint сервера](https://docs.didit.me/ru/transaction-monitoring/events.md#пакетная-отправка). Разумные значения по умолчанию: отправка при 25 событиях, через 5 секунд или при переходе страницы или приложения в фон.

### Что отбрасывать при перегрузке

Если нужно отбрасывать события, отбрасывайте дешёвые. Их можно безопасно отбросить:

`session.page_view` · `session.sdk_heartbeat` · `session.sdk_loaded` · `session.device_seen` · `session.bot_signal_observed` · `bonus.promotion_viewed` · `affiliate.referral_clicked`

Эти отбрасывать нельзя - сначала отправьте их:

каждое событие `security`, `payment`, `dispute` и `responsible_gambling`, а также `gameplay.bet_placed`, `gameplay.bet_settled` и `gameplay.p2p_settlement`.

Эндпоинты списков возвращают ту же классификацию для каждого события в поле `is_droppable`, поэтому клиент может опираться на него, а не на жёстко заданную копию списка.

## Совместимость заголовков

Основной заголовок - `X-Monitoring-Token`. `X-Transaction-Token` принимается как временный псевдоним, чтобы приложение, которое уже использует путь с учётными данными транзакций, могло перейти постепенно.

> [!WARNING]
>
> Псевдоним временный: он будет удалён до выхода API событий в общедоступный релиз. В новом коде отправляйте `X-Monitoring-Token`.

## Выбор канала

| | Канал устройства | Серверный канал |
| - | - | - |
| Endpoint | `POST /v1/events/` | `POST /v3/events/` |
| Аутентификация | `X-Monitoring-Token` | `x-api-key` |
| Субъект | Привязан к учётным данным | В теле запроса |
| Лучше всего подходит для | Входы, сессии, игровые раунды, телеметрия | Платежи, споры, события из реестра, догрузка исторических данных |

Оба канала создают одинаковые записи событий, и к ним применяются одинаковые правила. Используйте серверный канал, когда конечного пользователя нет.

## Дальше

> [card] [Приём событий](https://docs.didit.me/ru/transaction-monitoring/events.md)
>
> Формат конверта, категории, хранение и идемпотентность.

> [card] [Правила для событий](https://docs.didit.me/ru/transaction-monitoring/event-rules.md)
>
> Правила скорости, соотношений, последовательностей и корреляции.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.