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 de session, 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>.csidefd.com/client.js"
  referrerpolicy="origin"
  data-src="6">
</script>

Envoyez la télémétrie et recevez un token de session

Une fois le script chargé, la fonction globale sendClientTelemetry devient disponible. Charger le script ne crée pas de fingerprint de session tout seul. Appelez sendClientTelemetry(externalIds?) pour envoyer la télémétrie vers /client et recevoir un token de session. Passez un objet externalIds facultatif si vous voulez attacher vos propres identifiants.

const result = await sendClientTelemetry({
  email: "user@example.com",
  accountId: "1234567890",
});

// Ou appelez-la sans arguments
// const result = await sendClientTelemetry();

if (result.errors) {
  console.error(result.errors);
  throw new Error("La requête de télémétrie a échoué.");
}

const token = result.token;

Paramètres

Paramètre	Type	Obligatoire	Description
`externalIds`	`Record<string, string>`	Non	Identifiants facultatifs que vous souhaitez attacher au fingerprint, comme `accountId`, `orderId` ou `email`.

Pour recevoir le signal throwawayEmail, transmettez l’adresse e-mail dans cet objet avec la clé email.

Valeur de retour

La fonction renvoie un objet JSON (déjà analysé, vous n’avez donc pas besoin d’appeler .json() dessus) :

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

Le champ token contient le token de session de fingerprint. Si la collecte de la télémétrie rencontre des problèmes, l’objet inclut également un tableau facultatif errors que vous pouvez journaliser. Extrayez result.token et envoyez uniquement cette chaîne de token de session à votre backend.

Récupérez les données de fingerprint depuis votre backend

Générez une clé API de fingerprint réservée au backend dans le dashboard cside, stockez-la comme secret côté serveur, puis utilisez-la pour échanger le token de session avec cside. La clé API est affichée une seule fois et ne doit pas être exposée dans le code navigateur.

if (!token) {
  throw new Error("Le token de session de fingerprint n'a pas été renvoyé.");
}

const response = await fetch("https://api.cside.com/token/v2/verify", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CSIDE_FINGERPRINT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ token }),
});

const data = await response.json();

Corps de la requête

Envoyez du JSON au format { "token": "<token de session>" }, où la valeur est result.token de l’étape précédente.

Options de lookup du token

Utilisez l’endpoint authentifié pour les échanges server-to-server de production. Les endpoints publics restent disponibles lorsqu’une intégration a spécifiquement besoin du flux de lookup non authentifié.

Endpoint	Réponse	À utiliser lorsque
`/token/v2/verify`	JSON	Vous avez besoin d’une récupération backend authentifiée avec une clé API de fingerprint.
`/token/v2/device/entries`	JSON	Vous avez besoin des évaluations terminées pour le même ID d’appareil qu’un token de session.
`/token/v1/client`	JSON	Vous avez besoin du payload public de réponse de fingerprinting.
`/token/v1/clientId`	Texte brut	Vous avez seulement besoin de l’ID stable de fingerprint depuis le flux de lookup public.

/token/v2/verify renvoie 202 Accepted avec { "status": "pending" } pendant le traitement, puis 200 OK avec le payload terminé. /token/v2/device/entries accepte { "token": "...", "limit": 100, "offset": 0 } et renvoie { "device_id": "...", "entries": [...], "next_offset": 100, "has_more": true }, où chaque entrée utilise la forme de réponse de /token/v2/verify. limit est facultatif, vaut 500 par défaut et est limité à 500. L’endpoint clientId renvoie uniquement l’identifiant unique du fingerprint en texte brut. Si aucun identifiant unique du fingerprint n’existe pour le token de session, il renvoie 404.

Exemple de requête backend

const csideResponse = await fetch("https://api.cside.com/token/v2/verify", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CSIDE_FINGERPRINT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ token }),
});

const data = await csideResponse.json();

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

Cette référence de réponse s’applique à /token/v1/client. L’endpoint authentifié /token/v2/verify renvoie un payload JSON plat avec status, created_at, updated_at et les champs d’enrichissement disponibles, comme vpn_evaluation, fingerprint, geo_data, ip_enrichment, bot, network_client_metrics et fingerprint_enrichment. L’endpoint authentifié /token/v2/device/entries renvoie un device_id, un tableau entries contenant ces mêmes payloads plats pour les évaluations terminées associées à cet ID d’appareil, ainsi que des champs de pagination comme limit, offset, next_offset et has_more.

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 indiquant des attributs suspects ou notables du visiteur.

Champ	Type	Description
`bot.result`	`string`	Statut de détection de bot. Utilisez `"detected"` ou `"not_detected"`.
`bot.score`	`number`	Score bot numérique.
`bot.signal`	`string[]`	Signaux qui ont contribué à la détection du bot.
`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.
`throwawayEmail`	`boolean`	`true` lorsque l’identifiant `email` envoyé est une adresse e-mail jetable ou temporaire.

`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": {
    "result": "not_detected",
    "score": 0,
    "signal": []
  },
  "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,
  "throwawayEmail": false,
  "raw_device_attributes": {
    "math": "5f030fa7d2e5f9f757bfaf81642eb1a6",
    "vendor": "Google Inc."
  }
}