Events API | cside docs

Deze handleiding begeleidt u bij het integreren van de cside fingerprinting 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

Voeg het script toe aan uw pagina

Neem het cside fingerprinting-script op in de <head> van uw pagina. Het moet worden geladen voordat u fingerprintingfuncties aanroept.

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

Verzend telemetry en ontvang een sessietoken

Zodra het script is geladen, wordt de globale functie sendClientTelemetry beschikbaar. Het laden van het script maakt niet zelf een sessiefingerprint. Roep sendClientTelemetry(externalIds?) aan om telemetry naar /client te verzenden en een sessietoken te ontvangen. Geef optioneel een externalIds-object mee als u eigen identifiers wilt koppelen.

const result = await sendClientTelemetry({
  email: "user@example.com",
  accountId: "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;

Parameters

Parameter	Type	Vereist	Beschrijving
`externalIds`	`Record<string, string>`	Nee	Optionele identifiers die u aan de fingerprint wilt koppelen, zoals `accountId`, `orderId` of `email`.

Geef het e-mailadres in dit object mee met de sleutel email om het throwawayEmail-signaal te ontvangen.

Retourwaarde

De functie retourneert een JSON-object (al geparseerd, dus u hoeft er geen .json() op aan te roepen):

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

Het veld token bevat het fingerprint-sessietoken. Als het verzamelen van telemetry op problemen stuit, bevat het object ook een optionele errors-array die u kunt loggen. Haal result.token eruit en stuur alleen die sessietokenstring naar uw backend.

Haal fingerprintdata op vanuit uw backend

Genereer een backend-only fingerprint-API-sleutel in het cside-dashboard, sla deze op als server-side secret en gebruik deze om het sessietoken met cside uit te wisselen. De API-sleutel wordt maar één keer getoond en mag niet in browsercode worden blootgesteld.

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

Verzoekbody

Stuur JSON in de vorm { "token": "<sessietoken>" }, waarbij de waarde result.token uit de vorige stap is.

Token lookup-opties

Gebruik het geauthenticeerde endpoint voor server-to-serveruitwisselingen in productie. De publieke endpoints blijven beschikbaar wanneer een integratie specifiek de niet-geauthenticeerde lookupflow nodig heeft.

Endpoint	Response	Gebruik wanneer
`/token/v2/verify`	JSON	U geauthenticeerde backendopvraging met een fingerprint-API-sleutel nodig hebt.
`/token/v2/device/entries`	JSON	U voltooide evaluaties nodig hebt voor dezelfde device-ID als een sessietoken.
`/token/v1/client`	JSON	U de publieke fingerprinting response payload nodig hebt.
`/token/v1/clientId`	Platte tekst	U alleen de stabiele fingerprint-ID uit de publieke lookupflow nodig hebt.

/token/v2/verify retourneert 202 Accepted met { "status": "pending" } tijdens verwerking, daarna 200 OK met de voltooide payload. /token/v2/device/entries accepteert { "token": "...", "limit": 100, "offset": 0 } en retourneert { "device_id": "...", "entries": [...], "next_offset": 100, "has_more": true }, waarbij elke entry dezelfde responsevorm gebruikt als /token/v2/verify. limit is optioneel, is standaard 500 en heeft een maximum van 500. Het clientId-endpoint retourneert alleen de unieke fingerprint-ID als platte tekst. Als er geen unieke fingerprint-ID voor het sessietoken bestaat, retourneert het 404.

Voorbeeld van een backendrequest

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

Interpreteer de backendrespons

Uw backend retourneert een JSON-respons met het identificatieresultaat en bijbehorende signalen. Zie de volledige responsreferentie hieronder.

Responsreferentie

Deze responsreferentie geldt voor /token/v1/client. Het geauthenticeerde /token/v2/verify-endpoint retourneert een vlakke JSON-payload met status, created_at, updated_at en beschikbare verrijkingsvelden, zoals vpn_evaluation, fingerprint, geo_data, ip_enrichment, bot, network_client_metrics en fingerprint_enrichment. Het geauthenticeerde /token/v2/device/entries-endpoint retourneert een device_id, een entries-array met dezelfde vlakke payloads voor voltooide evaluaties die bij die device-ID horen en pagineringsvelden zoals limit, offset, next_offset en has_more.

De backendrespons bevat bezoekersidentificatie, browsergegevens, IP-intelligentie en een reeks fraudedetectiesignalen.

Velden op het hoogste niveau

Veld	Type	Beschrijving
`linked_id`	`string`	Een identificatie die u aan deze bezoeker hebt gekoppeld.
`tags`	`object`	Aangepaste metadata gekoppeld aan het evenement.
`timestamp`	`number`	Unix-tijdstempel (milliseconden) van het evenement.
`event_id`	`string`	Unieke identificatie voor dit fingerprinting-evenement.
`url`	`string`	De pagina-URL waar de fingerprint is verzameld.
`ip_address`	`string`	Het IP-adres van de bezoeker.
`user_agent`	`string`	De onbewerkte User-Agent-string van de browser van de bezoeker.
`client_referrer`	`string`	De verwijzings-URL van de pagina.

`browser_details`

Details over de browser en het besturingssysteem van de bezoeker.

Veld	Type	Beschrijving
`browser_name`	`string`	Browsernaam (bijv. `"Chrome"`).
`browser_major_version`	`string`	Hoofdversienummer.
`browser_full_version`	`string`	Volledige versiereeks.
`os`	`string`	Naam van het besturingssysteem.
`os_version`	`string`	Versie van het besturingssysteem.
`device`	`string`	Apparaattype (bijv. `"Other"`, `"Mobile"`).

`identification`

Het primaire identificatieresultaat van de bezoeker.

Veld	Type	Beschrijving
`visitor_id`	`string`	Een stabiele, unieke identificatie voor deze bezoeker.
`confidence.score`	`number`	Betrouwbaarheidsscore tussen `0` en `1`.
`confidence.version`	`string`	Versie van het gebruikte betrouwbaarheidsmodel.
`visitor_found`	`boolean`	Of deze bezoeker eerder is gezien.
`first_seen_at`	`number`	Unix-tijdstempel (ms) van de eerste identificatie van de bezoeker.
`last_seen_at`	`number`	Unix-tijdstempel (ms) van de meest recente identificatie van de bezoeker.

`supplementary_id_high_recall`

Een secundaire identificatie geoptimaliseerd voor hogere recall (minder vals-negatieven) ten koste van iets lagere precisie.

Veld	Type	Beschrijving
`visitor_id`	`string`	Bezoekersidentificatie onder het high-recall-model.
`visitor_found`	`boolean`	Of de bezoeker is gevonden.
`confidence.score`	`number`	Betrouwbaarheidsscore tussen `0` en `1`.
`confidence.version`	`string`	Versie van het gebruikte betrouwbaarheidsmodel.
`first_seen_at`	`number`	Unix-tijdstempel (ms) van de eerste identificatie.
`last_seen_at`	`number`	Unix-tijdstempel (ms) van de meest recente identificatie.

`proximity`

Geografische nabijheidsgegevens van de bezoeker.

Veld	Type	Beschrijving
`id`	`string`	Nabijheidslocatie-identificatie.
`precision_radius`	`number`	Precisieradius in kilometers.
`confidence`	`number`	Betrouwbaarheidsscore voor de nabijheidsschatting.

`ip_info`

IP-adresinformatie van de bezoeker.

Veld	Type	Beschrijving
`v4.address`	`string`	IPv4-adres.
`v6.address`	`string`	IPv6-adres.

`ip_blocklist`

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

Veld	Type	Beschrijving
`email_spam`	`boolean`	IP is geassocieerd met e-mailspam.
`attack_source`	`boolean`	IP is een bekende aanvalsbron.
`tor_node`	`boolean`	IP is een Tor-exitnode.

Fraude- en omgevingssignalen

Signalen die verdachte of opvallende bezoekerskenmerken aangeven.

Veld	Type	Beschrijving
`bot.result`	`string`	Botdetectiestatus. Gebruik `"detected"` of `"not_detected"`.
`bot.score`	`number`	Numerieke botscore.
`bot.signal`	`string[]`	Signalen die hebben bijgedragen aan de botdetectie.
`root_apps`	`boolean`	Apparaat heeft root-/supergebruikersapps geïnstalleerd.
`emulator`	`boolean`	Apparaat is een emulator.
`proxy`	`boolean`	Bezoeker gebruikt een proxy.
`proxy_confidence`	`string`	Betrouwbaarheidsniveau: `"low"`, `"medium"` of `"high"`.
`vpn`	`boolean`	Bezoeker gebruikt een VPN.
`vpn_confidence`	`string`	Betrouwbaarheidsniveau: `"low"`, `"medium"` of `"high"`.
`incognito`	`boolean`	Browser is in incognito-/privémodus.
`tampering`	`boolean`	Browserkenmerken zijn gemanipuleerd.
`jailbroken`	`boolean`	Apparaat is gejailbreakt.
`frida`	`boolean`	Frida-instrumentatietoolkit gedetecteerd.
`virtual_machine`	`boolean`	Bezoeker draait in een virtuele machine.
`developer_tools`	`boolean`	Browser-ontwikkelaarstools zijn geopend.
`mitm_attack`	`boolean`	Man-in-the-middle-aanval gedetecteerd.
`replayed`	`boolean`	Het verzoek is een herhaling van een eerder verzoek.
`high_activity_device`	`boolean`	Ongebruikelijk hoog aantal identificaties van dit apparaat.
`throwawayEmail`	`boolean`	`true` wanneer de meegestuurde `email`-identifier een wegwerp- of tijdelijk e-mailadres is.

`raw_device_attributes`

Laag-niveau browserfingerprint-componenten.

Veld	Type	Beschrijving
`math`	`string`	Hash van de wiskundige engine-uitvoer.
`vendor`	`string`	GPU-/grafische leveranciersreeks.

Volledig responsvoorbeeld

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