Enviament d'esdeveniments des del client amb SDK

La majoria dels esdeveniments que importen per al frau passen al dispositiu: l’inici de sessió, la sessió, la partida de joc, la telemetria temporal que distingeix una persona d’un script. La via del dispositiu els envia sense posar una clau d’API en un navegador. El teu backend emet una credencial de vida curta limitada a un sol usuari; l’aplicació envia els esdeveniments amb aquesta credencial.

Flux

Emet una credencial de monitoratge

El teu backend crida POST /v3/events/sdk-token/ amb la teva clau d’API i el vendor_data de l’usuari.

Envia des del dispositiu

L’aplicació envia una sol·licitud a POST /v1/events/ (o POST /v1/events/batch/) amb la capçalera X-Monitoring-Token.

Les regles s'executen com sempre

L’esdeveniment s’enriqueix, s’agrega i s’avalua amb exactament les mateixes regles que un esdeveniment enviat des del servidor.

Emissió d’una credencial

Per emetre una credencial cal tenir activada l’ingesta d’esdeveniments a l’aplicació. Mentre estigui desactivada, aquest endpoint respon amb 403 i {"code": "event_monitoring_disabled"} en lloc de lliurar una credencial que mai no podria escriure.

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

Camp	Valor per defecte	Notes
`vendor_data`	obligatori	El subjecte al qual pertanyen tots els esdeveniments enviats amb aquesta credencial.
`entity_type`	`individual`	`individual` o `company`.
`allowed_event_categories`	totes	Restringeix el que podria escriure una credencial filtrada.
`ttl_seconds`	900	60 - 86400.
`max_uses`	1000	Un ús per esdeveniment, no per sol·licitud.
`bind_to_origin`	cap	Quan s’activa, el `Origin` del navegador ha de coincidir exactament.

Enviament

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

Fixa’t en el que el payload no conté: ni clau d’API, ni subjecte. Tots dos els aplica el servidor.

Què aplica el servidor

Vinculació al subjecte. La credencial queda limitada a un vendor_data concret en el moment de l’emissió. Un bloc subject al cos de la sol·licitud se sobreescriu, de manera que un client manipulat no pot escriure a la línia de temps d’un altre usuari.
Context de xarxa. L’adreça, l’agent d’usuari, l’accept-language i l’origen es deriven de la sol·licitud, i aquests valors derivats pel servidor prevalen sobre qualsevol pista del client per a l’avaluació de regles. L’evidència de la regla registra la diferència com a font del camp.
Abast per categoria. Una credencial limitada a session no pot enviar un esdeveniment payment; es rebutja amb 400.
Pressupost d’usos. Un lot gasta un ús per esdeveniment, de manera que un lot de 500 esdeveniments no pot passar com si fos un sol ús per a una credencial de 10 usos.
Vinculació a l’origen. Quan s’activa bind_to_origin, es rebutja qualsevol sol·licitud el Origin de la qual no coincideixi, inclosa una que no tingui cap Origin.

Enviament per lots

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

Fins a 500 esdeveniments per enviament, amb els mateixos resultats per element que l’endpoint de lots del servidor. Un valor per defecte raonable és enviar cada 25 esdeveniments, cada 5 segons, o quan la pàgina o l’aplicació passa a segon pla.

Què descartar amb contrapressió

Si cal descartar esdeveniments, descarta els més barats. Aquests es poden descartar sense risc: session.page_view · session.sdk_heartbeat · session.sdk_loaded · session.device_seen · session.bot_signal_observed · bonus.promotion_viewed · affiliate.referral_clicked Aquests no, envia’ls primer: tots els esdeveniments de security, payment, dispute i responsible_gambling, i també gameplay.bet_placed, gameplay.bet_settled i gameplay.p2p_settlement. Els endpoints de llistat retornen la mateixa classificació per esdeveniment mitjançant el camp is_droppable, de manera que un client pot basar-se en aquest camp en lloc d’una còpia codificada.

Compatibilitat de capçaleres

La capçalera canònica és X-Monitoring-Token. X-Transaction-Token s’accepta com a àlies temporal perquè una aplicació que ja té una via de credencial de transacció pugui migrar de manera progressiva.

L’àlies és transitori i s’eliminarà abans que l’API d’esdeveniments arribi a disponibilitat general. Envia X-Monitoring-Token en el codi nou.

Triar una via

	Via del dispositiu	Via del servidor
Endpoint	`POST /v1/events/`	`POST /v3/events/`
Autenticació	`X-Monitoring-Token`	`x-api-key`
Subjecte	Vinculat a la credencial	Al payload
Ideal per a	Inicis de sessió, sessions, joc, telemetria	Pagaments, disputes, esdeveniments derivats del registre comptable, càrregues retroactives

Totes dues vies generen registres d’esdeveniments idèntics i executen les mateixes regles. Fes servir la via del servidor sempre que no hi hagi cap usuari final present.

Primers passos

Funcionalitats

Referència

Consola

Enviament d'esdeveniments des del client amb SDK

Flux

Emissió d’una credencial

Enviament

Què aplica el servidor

Enviament per lots

Què descartar amb contrapressió

Compatibilitat de capçaleres

Triar una via

Següents passos

Ingesta d'esdeveniments

Regles sobre esdeveniments

​Flux

​Emissió d’una credencial

​Enviament

​Què aplica el servidor

​Enviament per lots

​Què descartar amb contrapressió

​Compatibilitat de capçaleres

​Triar una via

​Següents passos

Ingesta d'esdeveniments

Regles sobre esdeveniments

Flux

Emissió d’una credencial

Enviament

Què aplica el servidor

Enviament per lots

Què descartar amb contrapressió

Compatibilitat de capçaleres

Triar una via

Següents passos