Soumission d'événements SDK - Capture côté client

Une grande partie des événements importants pour la fraude se produisent sur l’appareil : la connexion, la session, la manche de jeu, la télémétrie temporelle qui distingue une personne d’un script. Le canal de l’appareil les envoie sans placer de clé API dans un navigateur. Votre backend crée un identifiant de surveillance à courte durée de vie, limité à un seul utilisateur ; l’application les envoie ensuite avec celui-ci.

Déroulement

Créer un identifiant de surveillance

Votre backend appelle POST /v3/events/sdk-token/ avec votre clé API et le vendor_data de l’utilisateur.

Envoyer depuis l'appareil

L’application envoie à POST /v1/events/ (ou POST /v1/events/batch/) avec l’en-tête X-Monitoring-Token.

Les règles s'appliquent normalement

L’événement est enrichi, agrégé et évalué par exactement les mêmes règles que pour un événement envoyé depuis le serveur.

Création d’un identifiant

La création requiert que l’ingestion d’événements soit activée pour l’application. Tant qu’elle est désactivée, cet endpoint répond 403 avec {"code": "event_monitoring_disabled"}, plutôt que de délivrer un identifiant qui ne pourrait jamais permettre d’écrire des événements.

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

Champ	Par défaut	Remarques
`vendor_data`	requis	Le sujet auquel appartiennent tous les événements envoyés avec cet identifiant.
`entity_type`	`individual`	`individual` ou `company`.
`allowed_event_categories`	toutes	Restreint ce qu’un identifiant divulgué peut écrire.
`ttl_seconds`	900	60 - 86400.
`max_uses`	1000	Une utilisation par événement, et non par requête.
`bind_to_origin`	aucun	Si défini, l’`Origin` du navigateur doit correspondre exactement.

Envoi

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

Remarquez ce que le payload ne contient pas : ni clé API, ni sujet. Les deux sont appliqués côté serveur.

Ce que le serveur applique

Liaison au sujet. L’identifiant est limité à un seul vendor_data au moment de sa création. Un bloc subject dans le corps de la requête est écrasé : un client modifié ne peut donc pas écrire dans la chronologie d’un autre utilisateur.
Contexte réseau. L’adresse IP, l’user agent, l’accept-language et l’origine sont déterminés à partir de la requête, et ces valeurs dérivées du serveur priment sur toute indication du client pour l’évaluation des règles. Les preuves de règle enregistrent la différence sous forme de source du champ.
Périmètre des catégories. Un identifiant limité à session ne peut pas envoyer un événement payment ; il est rejeté avec 400.
Budget d’utilisations. Un lot consomme une utilisation par événement : un lot de 500 événements ne peut donc pas passer pour une seule utilisation face à un identifiant limité à 10 utilisations.
Liaison à l’origine. Si bind_to_origin est défini, une requête dont l’Origin ne correspond pas est refusée, y compris une requête sans aucun Origin.

Envoi groupé

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

Jusqu’à 500 événements par envoi groupé, avec les mêmes résultats par élément que le endpoint de traitement par lots côté serveur. Un envoi par défaut convenable : 25 événements, 5 secondes, ou le passage de la page ou de l’application en arrière-plan.

Ce qu’il faut écarter en cas de saturation

Si vous devez abandonner des événements, abandonnez les moins coûteux. Ceux-ci peuvent être écartés sans risque : session.page_view · session.sdk_heartbeat · session.sdk_loaded · session.device_seen · session.bot_signal_observed · bonus.promotion_viewed · affiliate.referral_clicked Ceux-ci ne le peuvent pas, et doivent être envoyés en priorité : tous les événements security, payment, dispute et responsible_gambling, ainsi que gameplay.bet_placed, gameplay.bet_settled et gameplay.p2p_settlement. Les endpoints de liste renvoient la même classification par événement sous la forme is_droppable, afin qu’un client puisse s’appuyer dessus plutôt qu’une copie codée en dur.

Compatibilité des en-têtes

L’en-tête de référence est X-Monitoring-Token. X-Transaction-Token est accepté comme alias temporaire, afin qu’une application qui dispose déjà d’un parcours utilisant un identifiant de transaction puisse migrer progressivement.

L’alias est transitoire et sera supprimé avant la disponibilité générale de l’API des événements. Envoyez X-Monitoring-Token dans le nouveau code.

Choisir un canal

	Canal appareil	Canal serveur
Endpoint	`POST /v1/events/`	`POST /v3/events/`
Authentification	`X-Monitoring-Token`	`x-api-key`
Sujet	Lié à l’identifiant	Dans le payload
Idéal pour	Connexions, sessions, jeu, télémétrie	Paiements, litiges, événements issus du grand livre, rattrapages

Les deux canaux produisent des enregistrements d’événements identiques et exécutent les mêmes règles. Utilisez le canal serveur chaque fois qu’aucun utilisateur final n’est présent.

Prise en main

Fonctionnalités

Référence

Console

Soumission d'événements SDK - Capture côté client

Déroulement

Création d’un identifiant

Envoi

Ce que le serveur applique

Envoi groupé

Ce qu’il faut écarter en cas de saturation

Compatibilité des en-têtes

Choisir un canal

Pour aller plus loin

Ingestion d'événements

Règles sur les événements

​Déroulement

​Création d’un identifiant

​Envoi

​Ce que le serveur applique

​Envoi groupé

​Ce qu’il faut écarter en cas de saturation

​Compatibilité des en-têtes

​Choisir un canal

​Pour aller plus loin

Ingestion d'événements

Règles sur les événements

Déroulement

Création d’un identifiant

Envoi

Ce que le serveur applique

Envoi groupé

Ce qu’il faut écarter en cas de saturation

Compatibilité des en-têtes

Choisir un canal

Pour aller plus loin