Invio eventi SDK - Cattura eventi lato client

La maggior parte degli eventi 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

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.

Invia dal dispositivo

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

Le regole vengono eseguite come di consueto

L’evento viene arricchito, aggregato e valutato dalle stesse regole di un evento inviato dal server.

Generazione di una credenziale

Per generare una credenziale è necessario che l’ingestione degli eventi 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.

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

{
  "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

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

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

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.

Primi passi

Funzionalità

Riferimento

Console

Invio eventi SDK - Cattura eventi lato client

Flusso

Generazione di una credenziale

Invio

Cosa applica il server

Batch

Cosa eliminare in caso di pressione sul sistema

Compatibilità delle intestazioni

Scegliere il canale

Prossimi passi

Ingestione degli eventi

Regole sugli eventi

​Flusso

​Generazione di una credenziale

​Invio

​Cosa applica il server

​Batch

​Cosa eliminare in caso di pressione sul sistema

​Compatibilità delle intestazioni

​Scegliere il canale

​Prossimi passi

Ingestione degli eventi

Regole sugli eventi

Flusso

Generazione di una credenziale

Invio

Cosa applica il server

Batch

Cosa eliminare in caso di pressione sul sistema

Compatibilità delle intestazioni

Scegliere il canale

Prossimi passi