> ## 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.

# Invio eventi SDK - Cattura eventi lato client

> Didit cattura login, gameplay e sessioni dal dispositivo con credenziale delimitata; soggetto e contesto di rete verificati lato server.

La maggior parte degli [eventi](https://docs.didit.me/it/transaction-monitoring/events.md) rilevanti per le frodi avviene sul dispositivo: il login, la sessione, il round di gioco e la telemetria dei tempi che distingue una persona da uno script. Il canale del dispositivo li invia senza inserire una chiave API in un browser.

Il tuo backend genera una credenziale di breve durata limitata a un solo utente; l'app invia gli eventi con questa credenziale.

## Flusso

**1. Genera una credenziale di monitoraggio**

Il tuo backend chiama `POST /v3/events/sdk-token/` con la tua chiave API e il `vendor_data` dell'utente.

**2. Invia dal dispositivo**

L'app invia richieste a `POST /v1/events/` (oppure su `POST /v1/events/batch/`) con l'intestazione `X-Monitoring-Token`.

**3. Le regole vengono eseguite come di consueto**

L'evento viene arricchito, aggregato e valutato dalle stesse [regole](https://docs.didit.me/it/transaction-monitoring/event-rules.md) di un evento inviato dal server.

## Generazione di una credenziale

> [!NOTE]
>
> Per generare una credenziale è necessario che l'[ingestione degli eventi](https://docs.didit.me/it/transaction-monitoring/events.md) sia attiva per l'applicazione. Quando è disattivata, questo endpoint risponde con `403` e `{"code": "event_monitoring_disabled"}`, invece di rilasciare una credenziale che non potrebbe mai scrivere.

```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"
}
```

| Campo | Predefinito | Note |
| - | - | - |
| `vendor_data` | obbligatorio | Il soggetto a cui appartengono tutti gli eventi inviati con questa credenziale. |
| `entity_type` | `individual` | `individual` o `company`. |
| `allowed_event_categories` | tutte | Restringe ciò che una credenziale compromessa potrebbe scrivere. |
| `ttl_seconds` | 900 | 60 - 86400. |
| `max_uses` | 1000 | Un utilizzo per **evento**, non per richiesta. |
| `bind_to_origin` | nessuno | Se impostato, l'`Origin` del browser deve corrispondere esattamente. |

## Invio

```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" }
  }'
```

Nota che il payload **non** contiene né la chiave API né il soggetto. Entrambi vengono applicati lato server.

## Cosa applica il server

* **Vincolo al soggetto.** La credenziale è associata a un solo `vendor_data` al momento della generazione. Un blocco `subject` nel corpo della richiesta viene sovrascritto, quindi un client manomesso non può scrivere nella cronologia di un altro utente.
* **Contesto di rete.** Indirizzo, user agent, accept-language e origin vengono ricavati dalla richiesta, e questi valori derivati dal server prevalgono su qualsiasi suggerimento del client per la valutazione delle regole. L'evidenza della regola registra la differenza come [fonte del campo](https://docs.didit.me/it/transaction-monitoring/event-rules.md#evidenze).
* **Ambito delle categorie.** Una credenziale limitata a `session` non può inviare un evento `payment`; viene rifiutata con `400`.
* **Budget di utilizzi.** Un batch consuma un utilizzo per evento, quindi un batch da 500 eventi non può eludere una credenziale da 10 utilizzi contando come un solo utilizzo.
* **Vincolo all'origin.** Quando è impostato `bind_to_origin`, una richiesta il cui `Origin` non corrisponde viene respinta, compresa quella senza alcun `Origin`.

## Batch

```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": [ { "…": "…" }, { "…": "…" } ] }'
```

Fino a 500 eventi per invio, con gli stessi esiti per singolo elemento dell'[endpoint batch lato server](https://docs.didit.me/it/transaction-monitoring/events.md#batch). Un buon valore predefinito per l'invio è ogni 25 eventi, dopo 5 secondi o quando la pagina o l'app passa in background.

### Cosa eliminare in caso di pressione sul sistema

Se devi scartare eventi, scarta quelli meno costosi. Questi possono essere eliminati senza problemi:

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

Questi no: inviali per primi:

ogni evento `security`, `payment`, `dispute` e `responsible_gambling`, oltre a `gameplay.bet_placed`, `gameplay.bet_settled` e `gameplay.p2p_settlement`.

Gli endpoint di elenco restituiscono, per ogni evento, la classificazione indicata da `is_droppable`, così un client può basarsi su quel valore invece che su una copia fissa nel codice.

## Compatibilità delle intestazioni

L'intestazione canonica è `X-Monitoring-Token`. `X-Transaction-Token` è accettato come alias temporaneo, così un'app che già utilizza un percorso per le credenziali di transazione può migrare gradualmente.

> [!WARNING]
>
> L'alias è transitorio e verrà rimosso prima che l'API degli eventi raggiunga la disponibilità generale. Nel nuovo codice invia `X-Monitoring-Token`.

## Scegliere il canale

| | Canale del dispositivo | Canale del server |
| - | - | - |
| Endpoint | `POST /v1/events/` | `POST /v3/events/` |
| Autenticazione | `X-Monitoring-Token` | `x-api-key` |
| Soggetto | Vincolato alla credenziale | Nel payload |
| Ideale per | Login, sessioni, gioco, telemetria | Pagamenti, contestazioni, eventi derivati dal registro contabile, inserimenti retroattivi |

Entrambi producono record di evento identici ed eseguono le stesse regole. Usa il canale del server ogni volta che non è presente un utente finale.

## Prossimi passi

> [card] [Ingestione degli eventi](https://docs.didit.me/it/transaction-monitoring/events.md)
>
> La busta, le categorie, la conservazione e l'idempotenza.

> [card] [Regole sugli eventi](https://docs.didit.me/it/transaction-monitoring/event-rules.md)
>
> Regole di frequenza, rapporto, sequenza e correlazione.


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