Configurer Device Intelligence

Configurez cside Device Intelligence en chargeant le script navigateur tôt, en collectant la télémétrie avec sendClientTelemetry, puis en envoyant le token de session renvoyé à votre backend.

Le script ne crée pas de fingerprint tout seul

Charger https://[your-team-id].csidefd.com/client.js expose sendClientTelemetry dans le navigateur. Un fingerprint de session est créé seulement après l’appel de sendClientTelemetry(externalIds?) par votre site.

Choisir une option d’implémentation

Méthode	Idéal pour	Recommandation production
Cloudflare Workers	Sites déjà routés par Cloudflare	Adapté à l’injection edge et au déploiement sur chemins limités
Injection directe du script	La plupart des sites de production	Recommandé lorsque vous contrôlez le HTML ou l’app shell
Webflow	Sites Webflow no-code	Utilisez Custom code et publiez avant de tester
Package NPM	Apps avec frameworks pris en charge	Recommandé lorsque le package place le script tôt
Google Tag Manager	Validation rapide sans changement de code	À utiliser seulement pour tester lorsque l’ordre compte

Recommandation de domaine client

Configurez le DNS pour utiliser votre propre domaine lorsque c’est possible. cside propose cette option pour éviter les préoccupations de confidentialité liées aux domaines tiers, rendre le script first-party pour le navigateur et empêcher les bloqueurs de publicités du navigateur ou le blocage client-side d’interférer avec le script ou d’affecter la précision des détections.

Si cside fournit une URL de script dédiée, utilisez cette URL exacte dans chaque méthode d’installation. Les exemples ci-dessous utilisent des placeholders. Pour voir l’URL complète de votre script, accédez au tableau de bord cside.

Bootstrap navigateur tolérant aux pannes

Utilisez le bootstrap navigateur tolérant aux pannes lorsque vous injectez directement Device Intelligence dans une page. Ajoutez-le au début du <head>, avant les autres scripts. Il charge client.js de manière asynchrone, met en file les appels précoces et les rejette si cside échoue, n’initialise pas la télémétrie ou prend plus de dix secondes. La page reste utilisable lorsque cside est indisponible. N’utilisez pas une simple balise <script src=".../client.js">.

<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>

Remplacez uniquement l’URL du script. Votre application doit gérer les appels sendClientTelemetry rejetés et poursuivre son flux normal : c’est le comportement tolérant aux pannes.

Servir le script depuis votre propre domaine

Cette option vous permet de servir le script de Device Intelligence depuis un sous-domaine que vous contrôlez, comme fingerprint.example.com. Elle est destinée aux comptes de production qui veulent une livraison first-party du script et un contrôle CSP plus strict.

Configuration activée par compte

Les domaines personnalisés de fingerprint nécessitent que cside provisionne un hostname cible pour votre compte. Contactez cside avant d’ajouter des enregistrements DNS.

Configuration DNS

Choisissez un sous-domaine, par exemple fingerprint.example.com
Demandez à cside votre hostname cible de fingerprinting
Ajoutez un enregistrement CNAME depuis votre sous-domaine vers la cible cside
Attendez la propagation DNS et la validation du hostname par cside
Utilisez votre sous-domaine comme source du script

Exemple d’enregistrement DNS :

Type	Nom	Valeur
`CNAME`	`fingerprint.example.com`	`[your-team-id].csidefd.com`

Après validation, utilisez l’URL du script sur le domaine client :

Utilisez le bootstrap tolérant aux pannes et remplacez sa valeur script.src par https://fingerprint.example.com/client.js.

Mettez à jour votre CSP pour autoriser le sous-domaine client dans script-src et connect-src.

Injection directe du script

L’injection directe de la balise dans votre HTML est prise en charge. Ajoutez le script dans le <head> de la page avant d’appeler les fonctions de fingerprinting.

Utilisez le bootstrap tolérant aux pannes et remplacez sa valeur script.src par l’URL csidefd.com de votre équipe.

Appelez ensuite sendClientTelemetry après le chargement du script. Vous pouvez l’appeler sans argument ou passer un objet externalIds facultatif.

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

if (result.errors) {
  console.error(result.errors);
  throw new Error("La requête de télémétrie a échoué.");
}

const { token: sessionToken } = result;

Envoyez le token de session à votre backend et échangez-le avec l’API cside. Les échanges backend de production utilisent une clé API de Device Intelligence côté serveur générée dans le dashboard cside. Consultez l’Events API pour le flux complet.

Dépannage

L’icône Device Intelligence manque dans l’UI - Confirmez que Device Intelligence est activé pour le domaine géré dans cside. Si vous avez supprimé puis rajouté le domaine, la fonction peut devoir être réactivée.
Le script charge, mais aucun fingerprint n’apparaît - Confirmez que votre site appelle sendClientTelemetry(externalIds?) après le chargement du script. Charger client.js rend seulement la fonction disponible.
Les IDs personnalisés manquent - Passez des externalIds facultatifs lors de l’appel à sendClientTelemetry, comme accountId, orderId ou email.

Package NPM

Pour les frameworks pris en charge, utilisez le package cside qui ajoute le script navigateur à l’app shell. C’est utile lorsque votre framework contrôle le rendu du document.

Le package doit toujours charger le même script cside avant que votre app appelle sendClientTelemetry.

Contactez l’équipe cside pour obtenir de l’aide si la méthode d’installation NPM vous intéresse.

Google Tag Manager

GTM sert aux tests rapides, mais ne garantit pas que cside se charge avant les autres scripts. Utilisez une balise Custom HTML avec un déclencheur All Pages pour valider le flux.

Utilisez GTM pour valider

Pour l’enforcement en production ou une collecte à forte confiance, utilisez l’injection directe, un package NPM ou Cloudflare Workers.

Cloudflare Workers

Utilisez Cloudflare Workers lorsque le trafic passe déjà par Cloudflare et que vous voulez contrôler l’injection du script à l’edge. Consultez le guide Cloudflare Workers.