Datapoints ophalen

De browser hoeft niet te weten welke payload sendClientTelemetry(externalIds?) verstuurt. Roep de functie aan, lees het geretourneerde sessietoken, en laat uw backend dat sessietoken uitwisselen met https://api.cside.com/token/v2/verify om fingerprint-, bot-, browser-, apparaat-, IP- en omgevingsdatapoints op te halen.

End-to-end flow

1. De browser roept sendClientTelemetry(externalIds?) aan.
2. sendClientTelemetry verzendt telemetry naar https://edge.csidefd.com/client. Sta die host toe in de connect-src van uw CSP.
3. /client retourneert JSON in de vorm { "token": "..." }, waarbij token het fingerprint-sessietoken is.
4. Uw backend stuurt dat sessietoken naar https://api.cside.com/token/v2/verify met een server-side Device Intelligence API-sleutel.

sendClientTelemetry gebruiken

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

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

const { token: sessionToken } = result;

if (!sessionToken) {
  throw new Error("Geen fingerprint-sessietoken ontvangen.");
}

Nadat u sessionToken hebt uitgehaald, stuurt u het naar uw backend. Uw backend voert de tokenuitwisseling met cside uit.

U kunt sendClientTelemetry() ook zonder argumenten aanroepen. Gebruik externalIds alleen wanneer u eigen identifiers, zoals userId, orderId of email, aan de fingerprint wilt koppelen.

Het voorbeeld hierboven gebruikt de sendClientTelemetry die client.js op window beschikbaar maakt. Als u het NPM-pakket hebt geïnstalleerd, haal dezelfde functie dan uit initDeviceIntelligence en krijg er types bij:

let token = null;

try {
  const { initDeviceIntelligence } = await import("@cside.dev/device-intelligence");
  const { sendClientTelemetry } = await initDeviceIntelligence({
    teamID: "[your-team-id]",
  });
  const result = await sendClientTelemetry({ userId: "1234567890" });
  token = result.token;
  if (result.errors) console.warn(result.errors);
} catch (error) {
  console.warn("Device Intelligence unavailable", error);
}

Met dynamisch importeren kan de bundler de verzamelcode in een apart bestand plaatsen. Start de import en initialisatie zo vroeg mogelijk: wachten op een betaling of aanmelding vertraagt de verzameling en kan eerdere signalen missen. Vang import- en initialisatiefouten af en laat de pagina zonder token blijven werken.

Alles hieronder geldt in beide gevallen. De functie, de argumenten en het sessietoken dat wordt teruggegeven zijn hetzelfde.

Kies uw externe identifiers

externalIds accepteert willekeurige stringsleutels, maar twee ervan sturen ingebouwde detecties aan:

De Identity graph koppelt een apparaat aan een account via userId, teamId of customerId; zonder een van die sleutels heeft een sessie geen account om aan te koppelen.

Een veelvoorkomende checkout-fraudecase is het detecteren van een apparaat dat met veel verschillende kaarten probeert te betalen. Koppel paymentCardId op het moment van betalen:

const result = await sendClientTelemetry({
  userId: "1234567890",
  orderId: "order-456",
  // Nooit het kaartnummer: een eenrichtingshash ervan, plus hoogstens de laatste 4 cijfers.
  paymentCardId: "a3f5c8d19b02e74f_4242",
});

Dezelfde kaart moet altijd dezelfde paymentCardId opleveren, dus gebruik een deterministische hash of het kaarttoken van uw betaalprovider, nooit een ID per poging. Stuur geen volledig kaartnummer, CVC, vervaldatum of andere ruwe betaalkaartgegevens via externalIds.

Ophaalopties

Genereer een backend-API-sleutel

Genereer een Device Intelligence API-sleutel onder Team Settings > Device Intelligence in het cside-dashboard voordat u het geauthenticeerde endpoint aanroept. De sleutel begint met cside_tgatv1_, wordt maar één keer getoond en moet in de secretmanager van uw backend worden opgeslagen.

De API-sleutel is een teamgebonden backendcredential. Stuur deze niet naar de browser, exposeer deze niet in frontendbundles en schrijf deze niet vanuit een Worker naar HTML.

API ophalen met het sessietoken

Het sessietoken zelf bevat niet de volledige fingerprintdata. Gebruik het als lookup-token vanuit uw backend met het geauthenticeerde cside-endpoint.

Gebruik /token/v2/verify wanneer u de volledige JSON-payload nodig heeft vanuit een server-to-serverintegratie.

curl https://api.cside.com/token/v2/verify \
  --request POST \
  --header "Authorization: Bearer $CSIDE_FINGERPRINT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"token":"'"$CSIDE_FINGERPRINT_SESSION_TOKEN"'"}'

Het endpoint retourneert 202 Accepted met { "status": "pending" } zolang de evaluatie nog wordt verwerkt. Het retourneert 200 OK zodra de evaluatie klaar is, met "status": "completed" en de payload, of "status": "failed" en een error_message.

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: sessionToken }),
});

const datapoints = await csideResponse.json();

if (!csideResponse.ok) {
  throw new Error(datapoints.error || "Fingerprintlookup is mislukt.");
}

if (datapoints.status === "failed") {
  throw new Error(datapoints.error_message || "Fingerprintevaluatie is mislukt.");
}

De voltooide response bevat status, created_at, updated_at en beschikbare verrijkingsvelden: fingerprint, network_client_metrics, geo_data, ip_enrichment, vpn_evaluation, bot, fingerprint_enrichment, rule_evaluations_v2 en het verouderde rule_evaluations. Zie de /token/v2/verify-responsreferentie voor elk veld.

Fouten en rate limits

Foutresponses bevatten een JSON-body { "error": "<bericht>", "code": <HTTP-status> }, geen error_message:

De standaard rate limit is 1.000 requests per minuut per team, met korte bursts toegestaan. Wacht de retry-after-periode af voordat u opnieuw probeert.

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.

Eerdere evaluaties voor hetzelfde apparaat ophalen

Gebruik /token/v2/device/entries wanneer u voltooide evaluaties nodig heeft die bij dezelfde device-ID horen als het sessietoken. Dit is nuttig voor accountrisicoscores, fraudereviewwachtrijen, onderzoek naar misbruik en het koppelen van een nieuwe sessie aan recente activiteit van dezelfde browserfingerprint.

Het endpoint gebruikt dezelfde backend-only Device Intelligence API-sleutel als /token/v2/verify. Het retourneert resultaten van nieuw naar oud en ondersteunt paginering met limit en offset.

curl https://api.cside.com/token/v2/device/entries \
  --request POST \
  --header "Authorization: Bearer $CSIDE_FINGERPRINT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "token": "'"$CSIDE_FINGERPRINT_SESSION_TOKEN"'",
    "limit": 100,
    "offset": 0
  }'

Requestbody

Responsebody

De response bevat de opgeloste device_id, een entries-array en pagineringsmetadata. Elke entry gebruikt dezelfde vlakke payloadvorm als /token/v2/verify.

{
  "device_id": "a1b2c3d4e5f6...",
  "entries": [
    {
      "status": "completed",
      "created_at": 1779441600000,
      "updated_at": 1779441600000,
      "fingerprint": {},
      "network_client_metrics": {}
    }
  ],
  "limit": 100,
  "offset": 0,
  "next_offset": 100,
  "has_more": true
}

Backendvoorbeeld

Gebruik next_offset uit de response in plaats van offsets zelf te berekenen. Stop wanneer has_more false is.

async function fetchDeviceEntries(sessionToken) {
  const entries = [];
  let offset = 0;
  const limit = 100;

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

    const page = await response.json();

    if (!response.ok) {
      throw new Error(page.error || "Lookup van device entries is mislukt.");
    }

    entries.push(...page.entries);
    offset = page.has_more ? page.next_offset : null;
  }

  return entries;
}

Als u alleen de eerste pagina nodig heeft, laat u limit en offset weg. De API retourneert standaard maximaal 500 voltooide evaluaties.

Publieke token-endpoints

/token/v1/client en /token/v1/clientId blijven beschikbaar voor integraties die specifiek de niet-geauthenticeerde publieke lookupflow nodig hebben.

Gebruik /token/v1/client wanneer u de publieke JSON-payload zonder API-sleutelauthenticatie nodig heeft.

curl https://api.cside.com/token/v1/client \
  --request POST \
  --header "Content-Type: text/plain" \
  --data "$CSIDE_FINGERPRINT_SESSION_TOKEN"

Gebruik /token/v1/clientId wanneer u alleen de stabiele fingerprint-ID nodig heeft.

curl https://api.cside.com/token/v1/clientId \
  --request POST \
  --header "Content-Type: text/plain" \
  --data "$CSIDE_FINGERPRINT_SESSION_TOKEN"

Voor /token/v1/* stuurt u het ruwe sessietoken als text/plain-body en verpakt u het niet in JSON. Alleen de /token/v2/*-endpoints accepteren { "token": "..." }. Beide v1-endpoints retourneren 202 Accepted met { "status": "pending" } zolang de evaluatie wordt verwerkt. /token/v1/clientId retourneert daarna JSON:

{ "status": "completed", "device_id": "a1b2c3d4e5f6..." }

Als er geen fingerprint-ID voor het sessietoken bestaat, retourneert het 404 met { "error": "fingerprint id not found", "code": 404 }. De v1-endpoints delen dezelfde foutvorm en rate limit als /token/v2/verify, op basis van het team in het token.

S3-export

cside kan fingerprintrecords exporteren naar S3 wanneer fingerprint S3-export is geconfigureerd voor een domein. Gebruik dit voor batchworkflows waar je geen beslissing tijdens een request nodig hebt.

Elk geëxporteerd record is de volledige evaluatie, geen samenvatting: de identiteitsvelden, de volledige apparaatvingerafdruk en de netwerk-, IP-, geo-, VPN-, bot-, regel- en gedragssignalen die cside voor dat bezoek heeft berekend. Zie de handleiding voor de S3-export voor de stappen om het in te stellen en de volledige recordstructuur.

Webhooks en WebSocket-streams

Geen van beide is beschikbaar. S3 is de enige exportbestemming voor Device Intelligence-gegevens, en er is geen instelling op accountniveau die webhook- of WebSocketlevering inschakelt.

Heb je gegevens nodig buiten een batchvenster om, roep dan de API aan tijdens het request.