Events API | cside docs

Ce guide vous accompagne dans l’intégration de l’Events API de cside fingerprinting de bout en bout : chargement du script client, génération d’un token d’identification, envoi au backend et interprétation de la réponse.

Flux d’intégration

Ajoutez le script à votre page

Incluez le script cside fingerprinting dans le <head> de votre page. Il doit être chargé avant d’appeler toute fonction de fingerprinting.

<script
  src="https://<YOUR_SUBDOMAIN>.csidetm.com/script.js"
  referrerpolicy="origin"
  data-src="6">
</script>

Générez un token d’identification

Une fois le script chargé, une fonction globale devient disponible. Appelez-la avec un identifiant client (par exemple un clientId ou userId) pour générer un token.

const result = await submitFingerprint("your-client-id");

Paramètres

Paramètre	Type	Description
`clientId`	`string`	Un identifiant unique pour l’utilisateur ou la session, tel qu’un `clientId` ou `userId`.

Valeur de retour

La fonction renvoie un objet token :

{
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

Envoyez le token à votre backend

Transmettez le token renvoyé à votre backend pour une vérification côté serveur. L’URL de votre endpoint backend sera fournie après le déploiement.

URL provisoire

Remplacez l’URL ci-dessous par votre endpoint backend réel une fois qu’il aura été provisionné.

POST https://<YOUR_BACKEND_HOST>/<PLACEHOLDER_PATH>

Exemple de requête

const response = await fetch("https://<YOUR_BACKEND_HOST>/<PLACEHOLDER_PATH>", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ token: result.token }),
});

const data = await response.json();

Corps de la requête

Champ	Type	Description
`token`	`string`	Le token renvoyé par l’appel `submitFingerprint` côté client.

Interprétez la réponse du backend

Votre backend renvoie une réponse JSON contenant le résultat d’identification et les signaux associés. Consultez la référence complète de la réponse ci-dessous.

Référence de la réponse

La réponse du backend comprend l’identification du visiteur, les détails du navigateur, l’intelligence IP et un ensemble de signaux de détection de fraude.

Champs de niveau supérieur

Champ	Type	Description
`linked_id`	`string`	Un identifiant que vous avez associé à ce visiteur.
`tags`	`object`	Métadonnées personnalisées attachées à l’événement.
`timestamp`	`number`	Horodatage Unix (millisecondes) de l’événement.
`event_id`	`string`	Identifiant unique pour cet événement de fingerprinting.
`url`	`string`	L’URL de la page où le fingerprint a été collecté.
`ip_address`	`string`	L’adresse IP du visiteur.
`user_agent`	`string`	La chaîne User-Agent brute du navigateur du visiteur.
`client_referrer`	`string`	L’URL de référence de la page.

`browser_details`

Détails sur le navigateur et le système d’exploitation du visiteur.

Champ	Type	Description
`browser_name`	`string`	Nom du navigateur (par exemple `"Chrome"`).
`browser_major_version`	`string`	Numéro de version majeure.
`browser_full_version`	`string`	Chaîne de version complète.
`os`	`string`	Nom du système d’exploitation.
`os_version`	`string`	Version du système d’exploitation.
`device`	`string`	Type d’appareil (par exemple `"Other"`, `"Mobile"`).

`identification`

Le résultat d’identification principal du visiteur.

Champ	Type	Description
`visitor_id`	`string`	Un identifiant unique et stable pour ce visiteur.
`confidence.score`	`number`	Score de confiance entre `0` et `1`.
`confidence.version`	`string`	Version du modèle de confiance utilisé.
`visitor_found`	`boolean`	Si ce visiteur a déjà été vu.
`first_seen_at`	`number`	Horodatage Unix (ms) de la première identification du visiteur.
`last_seen_at`	`number`	Horodatage Unix (ms) de l’identification la plus récente du visiteur.

`supplementary_id_high_recall`

Une identification secondaire optimisée pour un meilleur rappel (moins de faux négatifs) au prix d’une précision légèrement inférieure.

Champ	Type	Description
`visitor_id`	`string`	Identifiant du visiteur sous le modèle à haut rappel.
`visitor_found`	`boolean`	Si le visiteur a été trouvé.
`confidence.score`	`number`	Score de confiance entre `0` et `1`.
`confidence.version`	`string`	Version du modèle de confiance utilisé.
`first_seen_at`	`number`	Horodatage Unix (ms) de la première identification.
`last_seen_at`	`number`	Horodatage Unix (ms) de l’identification la plus récente.

`proximity`

Données de proximité géographique du visiteur.

Champ	Type	Description
`id`	`string`	Identifiant de localisation de proximité.
`precision_radius`	`number`	Rayon de précision en kilomètres.
`confidence`	`number`	Score de confiance pour l’estimation de proximité.

`ip_info`

Informations sur l’adresse IP du visiteur.

Champ	Type	Description
`v4.address`	`string`	Adresse IPv4.
`v6.address`	`string`	Adresse IPv6.

`ip_blocklist`

Si l’IP du visiteur apparaît sur des listes de blocage connues.

Champ	Type	Description
`email_spam`	`boolean`	L’IP est associée à du spam par e-mail.
`attack_source`	`boolean`	L’IP est une source d’attaque connue.
`tor_node`	`boolean`	L’IP est un nœud de sortie Tor.

Signaux de fraude et d’environnement

Signaux booléens et chaînes indiquant des attributs suspects ou notables du visiteur.

Champ	Type	Description
`bot`	`string`	Résultat de détection de bot. `"not_detected"` lorsqu’aucun bot n’est trouvé.
`root_apps`	`boolean`	L’appareil a des applications root/superutilisateur installées.
`emulator`	`boolean`	L’appareil est un émulateur.
`proxy`	`boolean`	Le visiteur utilise un proxy.
`proxy_confidence`	`string`	Niveau de confiance : `"low"`, `"medium"` ou `"high"`.
`vpn`	`boolean`	Le visiteur utilise un VPN.
`vpn_confidence`	`string`	Niveau de confiance : `"low"`, `"medium"` ou `"high"`.
`incognito`	`boolean`	Le navigateur est en mode incognito/privé.
`tampering`	`boolean`	Les attributs du navigateur ont été falsifiés.
`jailbroken`	`boolean`	L’appareil est jailbreaké.
`frida`	`boolean`	Toolkit d’instrumentation Frida détecté.
`virtual_machine`	`boolean`	Le visiteur s’exécute dans une machine virtuelle.
`developer_tools`	`boolean`	Les outils de développement du navigateur sont ouverts.
`mitm_attack`	`boolean`	Attaque man-in-the-middle détectée.
`replayed`	`boolean`	La requête est une répétition d’une requête précédente.
`high_activity_device`	`boolean`	Nombre inhabituellement élevé d’identifications depuis cet appareil.

`raw_device_attributes`

Composants de bas niveau du fingerprint du navigateur.

Champ	Type	Description
`math`	`string`	Hash de la sortie du moteur mathématique.
`vendor`	`string`	Chaîne du fournisseur GPU/graphique.

Exemple complet de réponse

{
  "linked_id": "somelinkedId",
  "tags": {},
  "timestamp": 1708102555327,
  "event_id": "1708102555327.NLOjmg",
  "url": "http://www.example.com/login",
  "ip_address": "61.127.217.15",
  "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) ...",
  "client_referrer": "https://example.com/blog/my-article",
  "browser_details": {
    "browser_name": "Chrome",
    "browser_major_version": "74",
    "browser_full_version": "74.0.3729",
    "os": "Windows",
    "os_version": "7",
    "device": "Other"
  },
  "identification": {
    "visitor_id": "Ibk1527CUFmcnjLwIs4A9",
    "confidence": { "score": 0.97, "version": "1.1" },
    "visitor_found": false,
    "first_seen_at": 1708102555327,
    "last_seen_at": 1708102555327
  },
  "supplementary_id_high_recall": {
    "visitor_id": "3HNey93AkBW6CRbxV6xP",
    "visitor_found": true,
    "confidence": { "score": 0.97, "version": "1.1" },
    "first_seen_at": 1708102555327,
    "last_seen_at": 1708102555327
  },
  "proximity": {
    "id": "w1aTfd4MCvl",
    "precision_radius": 10,
    "confidence": 0.95
  },
  "bot": "not_detected",
  "root_apps": false,
  "emulator": false,
  "ip_info": {
    "v4": { "address": "94.142.239.124" },
    "v6": { "address": "2001:db8:3333:4444:5555:6666:7777:8888" }
  },
  "ip_blocklist": {
    "email_spam": false,
    "attack_source": false,
    "tor_node": false
  },
  "proxy": true,
  "proxy_confidence": "low",
  "vpn": false,
  "vpn_confidence": "high",
  "incognito": false,
  "tampering": false,
  "jailbroken": false,
  "frida": false,
  "virtual_machine": false,
  "developer_tools": false,
  "mitm_attack": false,
  "replayed": false,
  "high_activity_device": false,
  "raw_device_attributes": {
    "math": "5f030fa7d2e5f9f757bfaf81642eb1a6",
    "vendor": "Google Inc."
  }
}