Device Intelligence instellen

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

Kies een implementatieoptie

De pagina Install Device Intelligence in het dashboard heeft vijf tabbladen: npm, AI, HTML, Cloudflare en Framer. npm is de standaard.

Methode	Best voor	Productieadvies
npm-pakket	Apps die met een bundler worden gebouwd	Standaard in het dashboard. Aanbevolen wanneer uw app zelf sendClientTelemetry aanroept
AI-codeerassistent	Teams die de installatie laten doen door Claude Code, Cursor of een vergelijkbare assistent	Het tabblad AI geeft u een prompt met de teamspecifieke script-URL om in de assistent te plakken
Directe scriptinjectie (tabblad HTML)	Sites waar u de HTML of app shell beheert	Gebruikt de fail-open browser-bootstrap
Cloudflare Workers	Sites die al via Cloudflare lopen	Goed voor edge-injectie en uitrol op beperkte routes
Framer	No-code Framer-sites	Gebruik Custom Code en publiceer voordat u test
Webflow	No-code Webflow-sites	Gebruik Custom code en publiceer voordat u test

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 en opent u het tabblad HTML.

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.

DNS-setup

1. Kies een subdomein, bijvoorbeeld fingerprint.example.com
2. Vraag cside om uw fingerprinting-doelhostname
3. Voeg een CNAME-record toe van uw subdomein naar het cside-doel
4. Wacht op DNS-propagatie en cside-validatie van de hostname
5. 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. Telemetry wordt altijd naar https://edge.csidefd.com/client gestuurd, ongeacht waar het script vandaan wordt geserveerd, dus connect-src heeft https://edge.csidefd.com nodig. Zie Content Security Policy.

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({
  userId: "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.

Content Security Policy

Welke installatiemethode u ook gebruikt, de browser stuurt telemetry naar https://edge.csidefd.com/client. Sta die host toe in connect-src. Wanneer u client.js laadt vanaf een teamsubdomein of uw eigen first-party domein, sta dan ook die scriptorigin toe in script-src:

script-src https://[your-team-id].csidefd.com;
connect-src https://edge.csidefd.com;

Het npm-pakket laadt geen extern script, dus het heeft alleen de connect-src-vermelding nodig. Zie Uw CSP aanpassen voor hoe cside u helpt het beleid te beheren.

Problemen oplossen

• Nergens Device Intelligence-gegevens - Controleer dat Device Intelligence is ingeschakeld voor het team onder Install Device Intelligence. De schakelaar vereist minstens één beheerd, niet-geschorst domein: een team zonder zo’n domein inschakelen lukt wel, maar verzamelt niets.
• 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 userId, 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. Dit is de standaardmethode in de Device Intelligence-setup van het cside-dashboard. De verzamelcode zit in het pakket zelf, dus er is geen extern script om te laden, en het geeft een getypeerde sendClientTelemetry terug, zodat u nooit naar window.sendClientTelemetry hoeft te grijpen en nooit hoeft te gokken of een 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({ userId: "1234567890" });

initDeviceIntelligence start de passieve signaalverzameling en het gedragsvolgen zodra het wordt aangeroepen, zodat een latere aanroep van sendClientTelemetry alleen nog de probes per aanroep hoeft uit te voeren. Roep het zo vroeg aan als uw app toelaat, om dezelfde reden dat de bootstrap bovenaan de <head> hoort: het verzamelen moet al lopen voordat u een token nodig hebt.

Wat het voor u afhandelt:

• Herhaalde aanroepen. Het verzamelen start maar één keer per pagina en elke aanroep wordt opgelost met dezelfde sendClientTelemetry, dus een React-effect dat twee keer draait (ook onder StrictMode) is onschadelijk.
• Fouten. sendClientTelemetry wordt nooit afgewezen: als er geen telemetrie verzameld kon worden, wordt het opgelost met { token: null, errors }. Lees errors, ga verder zonder token en houd uw pagina werkend. initDeviceIntelligence zelf wordt alleen afgewezen, met een TypeError, wanneer teamID ontbreekt of leeg is.
• Server-side rendering. Het pakket kan overal worden geïmporteerd waar een serverrenderer of edge-runtime clientcode evalueert: de exports-map wijst de condities react-server, edge-light, workerd, worker en node naar een kleine server-entry met dezelfde API. Daar wordt initDeviceIntelligence opgelost met een sendClientTelemetry die { token: null, errors } teruggeeft, zodat gedeelde code het zonder controle kan aanroepen.

Voor een Content-Security-Policy: het pakket stuurt telemetrie naar de cside-edge en laadt geen script vanaf een teamsubdomein, dus de enige vermelding die het nodig heeft is:

connect-src https://edge.csidefd.com;

AI-codeerassistent

Het tabblad AI op de pagina Install Device Intelligence genereert een prompt die uw assistent (Claude Code, Cursor en vergelijkbare tools) naar deze handleiding verwijst en uw teamspecifieke script-URL bevat. Plak de prompt in de assistent en controleer het resultaat: de assistent hoort het npm-pakket of de fail-open bootstrap hierboven te gebruiken, nooit een kale <script src=".../client.js">-tag.

Cloudflare Workers

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

Framer

Gebruik het tabblad Framer, of de Framer-handleiding, wanneer uw site met Framer is gebouwd. Die gebruikt dezelfde fail-open bootstrap in Framer Custom Code.