Device Intelligence instellen

Stel cside Device Intelligence in door het browserscript vroeg te laden, telemetry te verzamelen met sendClientTelemetry en het geretourneerde sessietoken naar uw backend te sturen.

Het script maakt niet zelf een fingerprint

Het laden van https://[your-team-id].csidefd.com/client.js maakt sendClientTelemetry beschikbaar in de browser. Een sessiefingerprint wordt pas gemaakt nadat uw site sendClientTelemetry(externalIds?) aanroept.

Kies een implementatieoptie

Methode	Best voor	Productieadvies
Cloudflare Workers	Sites die al via Cloudflare lopen	Goed voor edge-injectie en uitrol op beperkte routes
Directe scriptinjectie	De meeste productiewebsites	Aanbevolen wanneer u HTML of app shell beheert
Webflow	No-code Webflow-sites	Gebruik Custom code en publiceer voordat u test
NPM-pakket	Apps die met een bundler worden gebouwd	Aanbevolen wanneer uw app zelf `sendClientTelemetry` aanroept
Google Tag Manager	Snelle validatie zonder codewijzigingen	Alleen gebruiken voor testen wanneer scriptvolgorde telt

Advies voor klantdomein

Gebruik de DNS-setup om waar mogelijk uw eigen domein te gebruiken. cside biedt dit aan om privacyzorgen rond domeinen van derden te vermijden, het script first-party te laten lijken voor de browser en te voorkomen dat browser-adblockers of client-side blokkering het script verstoren of de nauwkeurigheid van de detecties beïnvloeden.

Als cside een specifieke script-URL levert, gebruik dan exact die URL in elke installatiemethode. De voorbeelden hieronder gebruiken placeholders. Om uw volledige script-URL te zien, gaat u naar het cside-dashboard.

Fail-open browser-bootstrap

Gebruik de fail-open browser-bootstrap wanneer u Device Intelligence rechtstreeks in een pagina injecteert. Plaats deze bovenaan in de <head>, vóór andere scripts. De bootstrap laadt client.js asynchroon, zet vroege aanroepen in een wachtrij en wijst ze af als cside faalt, telemetry niet initialiseert of langer dan tien seconden laadt. De pagina blijft werken als cside niet beschikbaar is. Gebruik geen kale <script src=".../client.js">-tag.

<script>
(function () {
  const calls = [];
  let error;
  let timeoutID;

  function fallback(externalIds) {
    return error
      ? Promise.reject(error)
      : new Promise((resolve, reject) => {
          calls.push({ externalIds, resolve, reject });
        });
  }

  function rejectAll(nextError) {
    if (error) {
      return;
    }

    error = nextError;
    while (calls.length > 0) {
      calls.shift().reject(nextError);
    }
  }

  function flush(sendClientTelemetry) {
    while (calls.length > 0) {
      const call = calls.shift();
      Promise.resolve()
        .then(() => sendClientTelemetry(call.externalIds))
        .then(call.resolve, call.reject);
    }
  }

  window.sendClientTelemetry = window.sendClientTelemetry || fallback;

  const script = document.createElement("script");
  script.async = true;
  script.src = "https://[your-team-id].csidefd.com/client.js";
  script.referrerPolicy = "origin";
  script.setAttribute("data-src", "6");

  const fail = (nextError) => {
    clearTimeout(timeoutID);
    rejectAll(nextError);
  };

  script.onerror = () =>
    fail(new Error("cside client.js failed to load"));
  script.onload = () => {
    clearTimeout(timeoutID);
    const sendClientTelemetry = window.sendClientTelemetry;
    if (
      typeof sendClientTelemetry !== "function" ||
      sendClientTelemetry === fallback
    ) {
      rejectAll(new Error("cside telemetry unavailable"));
      return;
    }
    flush(sendClientTelemetry);
  };

  timeoutID = setTimeout(
    () => fail(new Error("cside client.js timed out while loading")),
    10000,
  );
  (document.head || document.documentElement).appendChild(script);
})();
</script>

Vervang alleen de script-URL. Uw applicatie moet afgewezen sendClientTelemetry-aanroepen afhandelen en de normale flow voortzetten: dat is het fail-open gedrag.

Het script via uw eigen domein serveren

Met deze optie serveert u het Device Intelligence-script vanaf een subdomein dat u beheert, zoals fingerprint.example.com. Dit is bedoeld voor productieaccounts die first-party scriptlevering en strakkere CSP-controle willen.

Account-enabled setup

Aangepaste fingerprintdomeinen vereisen dat cside een doelhostname voor uw account provisiont. Neem contact op met cside voordat u DNS-records toevoegt.

DNS-setup

Kies een subdomein, bijvoorbeeld fingerprint.example.com
Vraag cside om uw fingerprinting-doelhostname
Voeg een CNAME-record toe van uw subdomein naar het cside-doel
Wacht op DNS-propagatie en cside-validatie van de hostname
Gebruik uw subdomein als scriptbron

Voorbeeld van DNS-record:

Type	Naam	Waarde
`CNAME`	`fingerprint.example.com`	`[your-team-id].csidefd.com`

Gebruik na validatie de klantdomein-script-URL:

Gebruik de fail-open browser-bootstrap en vervang de waarde van script.src door https://fingerprint.example.com/client.js.

Werk uw CSP bij om het klantensubdomein toe te staan voor script-src en connect-src.

Directe scriptinjectie

De tag direct in uw HTML injecteren wordt ondersteund. Voeg het script toe aan de <head> van de pagina voordat u fingerprintingfuncties aanroept.

Gebruik de fail-open browser-bootstrap en vervang de waarde van script.src door de csidefd.com-URL van uw team.

Roep daarna sendClientTelemetry aan nadat het script is geladen. U kunt de functie zonder argumenten aanroepen of optioneel een externalIds-object meegeven.

const result = await sendClientTelemetry({
  accountId: "customer-123",
  orderId: "order-456",
});

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

const { token: sessionToken } = result;

Stuur het sessietoken naar uw backend en wissel het uit met de cside API. Productie-uitwisselingen vanuit de backend gebruiken een server-side Device Intelligence API-sleutel die in het cside-dashboard is gegenereerd. Zie de Events API voor de volledige flow.

Problemen oplossen

Device Intelligence-icoon ontbreekt in de UI - Controleer dat Device Intelligence is ingeschakeld voor het beheerde domein in cside. Als u het domein hebt verwijderd en opnieuw toegevoegd, moet de functie mogelijk opnieuw worden ingeschakeld.
Script laadt, maar er verschijnen geen fingerprints - Controleer dat uw site sendClientTelemetry(externalIds?) aanroept nadat het script is geladen. Het laden van client.js maakt alleen de functie beschikbaar.
Aangepaste ID’s ontbreken - Geef optionele externalIds mee bij het aanroepen van sendClientTelemetry, zoals accountId, orderId of email.

NPM-pakket

Als uw app met een bundler wordt gebouwd, installeer dan @cside.dev/device-intelligence in plaats van de bootstrap hierboven te plakken. Het laadt dezelfde client.js voor uw team en geeft een getypeerde sendClientTelemetry terug, zodat u nooit naar window.sendClientTelemetry hoeft te grijpen en nooit hoeft te gokken of het script al geladen is.

npm i @cside.dev/device-intelligence

import { initDeviceIntelligence } from "@cside.dev/device-intelligence";

const { sendClientTelemetry } = await initDeviceIntelligence({
  teamID: "[your-team-id]",
});

const { token, errors } = await sendClientTelemetry({ accountId: "1234567890" });

initDeviceIntelligence voegt <script async referrerpolicy="origin" src="https://[your-team-id].csidefd.com/client.js"> toe aan de <head> en wordt opgelost zodra het script geladen is en zijn telemetriefunctie beschikbaar heeft gemaakt. Roep het zo vroeg aan als uw app toelaat, om dezelfde reden dat de bootstrap bovenaan de <head> hoort: het script moet al aan het laden zijn voordat u een token nodig hebt.

Wat het voor u afhandelt:

Herhaalde aanroepen. Opnieuw aanroepen voor hetzelfde team sluit aan bij het laden dat al loopt in plaats van een tweede tag toe te voegen, dus een React-effect dat twee keer draait is onschadelijk. Het pakt ook een tag op die al op de pagina staat, bijvoorbeeld geïnjecteerd door @cside.dev/vite of @cside.dev/next.
Fouten. De promise wordt afgewezen als het script niet laadt, niet binnen tien seconden laadt, of laadt zonder zijn telemetriefunctie beschikbaar te maken. Uw pagina blijft werken: zet de aanroep in een try/catch en ga verder zonder token.
Server-side rendering. Zonder document wordt het opgelost met een sendClientTelemetry die { token: null, errors } teruggeeft in plaats van een fout te gooien, zodat gedeelde code het zonder controle kan aanroepen.

Eén pagina rapporteert voor één team. Een tweede aanroep met een ander team-ID laadt niets en wordt opgelost met een sendClientTelemetry die het conflict meldt, omdat het browserscript één telemetriefunctie beschikbaar maakt.

Voor een Content-Security-Policy exporteert het pakket de script-URL, zodat u het formaat niet hoeft vast te leggen:

import { buildDeviceIntelligenceScriptUrl } from "@cside.dev/device-intelligence";

buildDeviceIntelligenceScriptUrl("[your-team-id]"); // https://[your-team-id].csidefd.com/client.js

Sta die host toe in script-src en https://edge.csidefd.com in connect-src.

Andere cside-pakketten

@cside.dev/vite en @cside.dev/next injecteren de scripttag tijdens de build of het renderen, maar geven geen getypeerde toegang tot sendClientTelemetry. Gebruik @cside.dev/device-intelligence wanneer uw app de telemetriefunctie zelf aanroept.

Google Tag Manager

GTM is handig voor snelle tests, maar garandeert niet dat cside vóór andere scripts laadt. Gebruik een Custom HTML-tag met een All Pages-trigger om de flow te valideren.

Gebruik GTM voor validatie

Voor productie-enforcement of gegevensverzameling met hoge betrouwbaarheid gebruikt u directe scriptinjectie, een NPM-pakket of Cloudflare Workers.

Cloudflare Workers

Gebruik Cloudflare Workers wanneer verkeer al via Cloudflare loopt en u scriptinjectie aan de edge wilt beheren. Zie de Cloudflare Workers-handleiding.