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	Framework-apps met ondersteunde pakketten	Aanbevolen wanneer het pakket het script vroeg plaatst
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

Gebruik voor ondersteunde frameworks het cside-pakket dat het browserscript toevoegt aan de app shell. Dit is handig wanneer uw framework documentrendering beheert.

Het pakket moet nog steeds hetzelfde cside-script laden voordat uw app sendClientTelemetry aanroept.

Neem contact op met het cside-team voor hulp als u de NPM-installatiemethode wilt gebruiken.

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.