Events API

Ce guide vous accompagne dans l’intégration de l’Events API de cside Device Intelligence 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

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;

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

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();

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();

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

browser_details

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

identification

Le résultat d’identification principal 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.

proximity

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

ip_info

Informations sur l’adresse IP du visiteur.

ip_blocklist

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

Signaux de fraude et d’environnement

Signaux indiquant des attributs suspects ou notables du visiteur.

vpn_methods

vpn_methods contient les signaux propres à chaque méthode de détection liés aux VPN et au trafic anonymisé. Utilisez le champ de niveau supérieur vpn comme verdict global. Une méthode peut valoir true lorsque vpn vaut false, par exemple lorsque cside détecte un trafic de proxy ou de relais que le modèle VPN ne classe pas comme un VPN.

raw_device_attributes

Composants de bas niveau du fingerprint du navigateur.

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",
  "vpn_origin_timezone": "Europe/Amsterdam",
  "vpn_origin_country": "NL",
  "vpn_methods": {
    "timezone_mismatch": false,
    "public_vpn": false,
    "auxiliary_mobile": false,
    "os_mismatch": false,
    "relay": true
  },
  "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."
  }
}