Events API

Deze handleiding begeleidt u bij het integreren van de cside Device Intelligence Events API van begin tot eind: het laden van het clientscript, het genereren van een sessietoken, het verzenden naar uw backend en het interpreteren van de respons.

Integratieflow

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

// Of roep de functie zonder argumenten aan
// const result = await sendClientTelemetry();

if (result.errors) {
  console.error(result.errors);
  throw new Error("Telemetry-aanvraag is mislukt.");
}

const token = result.token;

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

if (!token) {
  throw new Error("Fingerprint-sessietoken is niet geretourneerd.");
}

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

/token/v2/verify-response

Het geauthenticeerde endpoint retourneert een vlakke JSON-payload. Elke entry in /token/v2/device/entries gebruikt dezelfde vorm.

De geneste objecten komen overeen met de recordstructuur van de S3-export, waar elk veld in detail is gedocumenteerd.

rule_evaluations_v2

De tabel hierboven vat dit veld samen. Het bevat de uitkomst van elke regel die voor het domein is gedraaid, drie niveaus diep genest onder rule_evaluations_v2.values[].evaluation, en de waarden zijn integers in plaats van strings, dus die zijn het waard om uit te schrijven. Het maakt geen deel uit van de /token/v1/client-payload die hieronder is gedocumenteerd.

outcome en evaluated_as zijn onbewerkte integers, geen strings:

Elke geëvalueerde, gepubliceerde regel rapporteert bij elk event een entry, met welke uitkomst dan ook. rule_evaluations_v2 is een registratie van wat is geëvalueerd, geen notificatiestream, dus outcome: 2 (false) en outcome: 3 (ontbrekend) worden niet onderdrukt: ze rijden net zo betrouwbaar mee in de array als outcome: 1. transition vertelt u of die uitkomst is veranderd sinds de vorige evaluatie.

Een afwezige entry voor een gegeven rule_slug betekent dat de regel helemaal niet is geëvalueerd: hij is niet geactiveerd voor het domein, het is een meet-only regel die niet publiceert, of er liep geen evaluatie voor dat event. Het betekent niet “geëvalueerd als false”, dat geval is outcome: 2, net als al het andere aanwezig in de array. Zie Accountdeling detecteren voor een uitgewerkt voorbeeld dat dit veld end-to-end uitleest.

/token/v1/client-responsreferentie

Deze referentie geldt voor het publieke /token/v1/client-endpoint. Het is een oudere, vlakkere weergave van dezelfde evaluatie. Veel van de velden zijn vaste placeholders die voor achterwaartse compatibiliteit zijn behouden; de callout hieronder somt ze op. Gebruik voor nieuwe integraties bij voorkeur /token/v2/verify.

Uitleg bij regels

Gepubliceerde regels met een waar resultaat kunnen rule_evaluations_v2.values[].evaluation.explanation.nodes bevatten. Elke bezochte node kan node_id, outcome, de getypeerde waarde observed, subject en compared_to beschrijven. Uitleg is optioneel; onware, wachtende en ontbrekende resultaten bevatten deze niet. Ontbrekende uitleg verandert het vastgelegde resultaat niet.

Behandel subject en compared_to als weergavetekst, niet als een formaat om te ontleden. Gebruik node_id, getypeerde observed-waarden en outcome in uw code. Lees deze velden uit rule_evaluations_v2, niet uit het oude object rule_evaluations. Zie de Events API voor resultaatwaarden en het verschil met het oude formaat.

Velden op het hoogste niveau

De response bevat ook de objecten network_client_metrics, vpn_evaluation, proxy_details, tampering_details, tampering_anomaly_score, velocity en sdk. De tellingen in velocity zijn alleen afgeleid van het huidige evenement (het venster events.24_hours is de enige historische waarde); sdk rapporteert platform: "js" met version: "unknown". Ze staan in het volledige voorbeeld, maar maken geen deel uit van het stabiele contract.

browser_details

Details over de browser en het besturingssysteem van de bezoeker.

identification

Het primaire identificatieresultaat van de bezoeker.

supplementary_id_high_recall

Een secundaire identifier afgeleid van uw externalIds (met voorkeur voor userId, daarna accountId), zodat één account over meerdere apparaten kan worden gekoppeld. Valt terug op de device-ID wanneer er geen externe ID is gekoppeld.

proximity

Wordt niet gevuld. Altijd { "id": "unknown", "precision_radius": 0, "confidence": 0.0 }. Gebruik geo_data en ip_enrichment op /token/v2/verify voor locatie.

ip_info

IP-adresinformatie van de bezoeker.

ip_blocklist

Of het IP-adres van de bezoeker op bekende blokkeerlijsten staat.

Fraude- en omgevingssignalen

Signalen die verdachte of opvallende bezoekerskenmerken aangeven.

Het wegwerp-e-mailsignaal maakt geen deel uit van deze response. Lees in plaats daarvan fingerprint_enrichment.throwaway_email_detected uit /token/v2/verify.

vpn_methods

vpn_methods bevat signalen per detectiemethode die verband houden met VPN- en geanonimiseerd verkeer. Gebruik het veld vpn op hoofdniveau als eindoordeel. Een methode kan true zijn terwijl vpn false is, bijvoorbeeld bij proxy- of relayverkeer dat niet als VPN is geclassificeerd.

raw_device_attributes

Laag-niveau browserfingerprint-componenten.

Volledig responsvoorbeeld

Een voltooide /token/v1/client-response. Geneste objecten die geen deel uitmaken van het stabiele contract (network_client_metrics, vpn_evaluation, velocity) zijn verkort.

{
  "linked_id": "b3f1c9e2-4d7a-4b0e-9f1a-2c8d7e6f5a41",
  "tags": {
    "domain_id": "7371466449724252160",
    "team_id": "7196353823991660544",
    "request_id": "01J9ZK3Q8W",
    "session_id": "b3f1c9e2-4d7a-4b0e-9f1a-2c8d7e6f5a41",
    "fingerprint_match": "7371466449724252160",
    "external_id:userId": "1234567890",
    "incognito_support": "supported",
    "developer_tools_support": "supported",
    "virtual_machine_support": "heuristic",
    "tor_support": "ipinfo_privacy",
    "visit_summary_source": "recent_fingerprint.available"
  },
  "timestamp": 1708102555327,
  "event_id": "289076244130249728",
  "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": "unknown",
  "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.0, "version": "unknown" },
    "visitor_found": false,
    "first_seen_at": 1708102555327,
    "last_seen_at": 1708102555327
  },
  "supplementary_id_high_recall": {
    "visitor_id": "3HNey93AkBW6CRbxV6xP",
    "visitor_found": true,
    "confidence": { "score": 0.0, "version": "unknown" },
    "first_seen_at": 1708102555327,
    "last_seen_at": 1708102555327
  },
  "proximity": {
    "id": "unknown",
    "precision_radius": 0,
    "confidence": 0.0
  },
  "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",
  "proxy_details": {
    "proxy_type": "datacenter",
    "last_seen_at": 1708102555327,
    "provider": "Example Hosting"
  },
  "vpn": false,
  "vpn_confidence": "high",
  "vpn_origin_timezone": "Europe/Amsterdam",
  "vpn_origin_country": "NL",
  "vpn_methods": {
    "timezone_mismatch": false,
    "public_vpn": true,
    "auxiliary_mobile": false,
    "os_mismatch": false,
    "relay": true
  },
  "vpn_evaluation": { "is_vpn": false, "vpn_probability": 0.04, "vpn_confidence": 0.91 },
  "incognito": false,
  "tampering": false,
  "tampering_anomaly_score": 0.0,
  "tampering_anti_detect_browser": false,
  "tampering_details": { "anomaly_score": 0.0, "anti_detect_browser": false },
  "cloned_app": false,
  "factory_reset_timestamp": 0,
  "jailbroken": false,
  "frida": false,
  "privacy_settings": false,
  "virtual_machine": false,
  "location_spoofing": false,
  "velocity": {
    "distinct_ip": { "5_minutes": 1, "1_hour": 1, "24_hours": 1 },
    "distinct_country": { "5_minutes": 0, "1_hour": 0, "24_hours": 0 },
    "events": { "5_minutes": 1, "1_hour": 1, "24_hours": 3 },
    "ip_events": { "5_minutes": 1, "1_hour": 1, "24_hours": 1 },
    "distinct_ip_by_linked_id": { "5_minutes": 1, "1_hour": 1, "24_hours": 1 },
    "distinct_visitor_id_by_linked_id": { "5_minutes": 1, "1_hour": 1, "24_hours": 1 }
  },
  "developer_tools": false,
  "mitm_attack": false,
  "sdk": { "platform": "js", "version": "unknown", "integrations": [] },
  "replayed": false,
  "high_activity_device": false,
  "raw_device_attributes": {
    "math": "unknown",
    "vendor": "Google Inc."
  },
  "network_client_metrics": { "client_ip": "61.127.217.15", "tls_ja4": "t13d1516h2_8daaf6152771_b186095e22b6" },
  "status": "completed",
  "domain_id": "7371466449724252160",
  "team_id": "7196353823991660544",
  "session_id": "b3f1c9e2-4d7a-4b0e-9f1a-2c8d7e6f5a41",
  "request_id": "01J9ZK3Q8W",
  "created_at": "2024-02-16T17:35:55.327Z"
}