Configurer Device Intelligence

Configurez cside Device Intelligence en démarrant la collecte des signaux tôt, en collectant la télémétrie avec sendClientTelemetry, puis en envoyant le token de session renvoyé à votre backend.

Choisir une option d’implémentation

La page Install Device Intelligence du tableau de bord comporte cinq onglets : npm, AI, HTML, Cloudflare et Framer. npm est l’onglet par défaut.

Méthode	Idéal pour	Recommandation production
Package NPM	Apps construites avec un bundler	Méthode par défaut du tableau de bord. Recommandé lorsque votre app appelle sendClientTelemetry
Assistant de codage IA	Équipes qui confient l’installation à Claude Code, Cursor ou un assistant similaire	L’onglet AI vous donne un prompt contenant l’URL de script de votre équipe à coller dans l’assistant
Injection directe du script (onglet HTML)	Sites où vous contrôlez le HTML ou l’app shell	Utilise le bootstrap navigateur tolérant aux pannes
Cloudflare Workers	Sites déjà routés par Cloudflare	Adapté à l’injection edge et au déploiement sur chemins limités
Framer	Sites Framer no-code	Utilisez Custom Code et publiez avant de tester
Webflow	Sites Webflow no-code	Utilisez Custom code et publiez avant de tester

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 et ouvrez l’onglet HTML.

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 DNS

1. Choisissez un sous-domaine, par exemple fingerprint.example.com
2. Demandez à cside votre hostname cible de fingerprinting
3. Ajoutez un enregistrement CNAME depuis votre sous-domaine vers la cible cside
4. Attendez la propagation DNS et la validation du hostname par cside
5. 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. La télémétrie est envoyée à https://edge.csidefd.com/client quel que soit l’endroit d’où le script est servi, connect-src a donc besoin de https://edge.csidefd.com. Consultez Content Security Policy.

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

Content Security Policy

Quelle que soit la méthode d’installation, le navigateur envoie la télémétrie à https://edge.csidefd.com/client. Autorisez cet hôte dans connect-src. Lorsque vous chargez client.js depuis un sous-domaine d’équipe ou votre propre domaine first-party, autorisez aussi cette origine de script dans script-src :

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

Le package NPM ne charge aucun script distant, il n’a donc besoin que de l’entrée connect-src. Consultez Ajuster votre CSP pour savoir comment cside vous aide à gérer la politique.

Dépannage

• Aucune donnée Device Intelligence nulle part - Confirmez que Device Intelligence est activé pour l’équipe sous Install Device Intelligence. L’interrupteur nécessite au moins un domaine géré non suspendu : activer une équipe sans domaine réussit mais ne collecte rien.
• 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 userId, orderId ou email.

Package NPM

Si votre app est construite avec un bundler, installez @cside.dev/device-intelligence au lieu de coller le bootstrap ci-dessus. C’est la méthode par défaut de la configuration Device Intelligence dans le tableau de bord cside. Le code de collecte est inclus dans le package, il n’y a donc aucun script distant à charger, et il renvoie un sendClientTelemetry typé : vous n’utilisez jamais window.sendClientTelemetry et vous n’avez jamais à deviner si un script est déjà chargé.

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 démarre la collecte passive des signaux et le suivi du comportement dès son appel, si bien qu’un appel ultérieur à sendClientTelemetry n’a plus que les sondes par appel à exécuter. Appelez-le aussi tôt que votre app le permet, pour la même raison que le bootstrap se place en haut du <head> : la collecte doit être en cours avant que vous ayez besoin d’un token.

Ce qu’il gère pour vous :

• Les appels répétés. La collecte ne démarre qu’une fois par page et chaque appel se résout avec le même sendClientTelemetry, donc un effet React exécuté deux fois (y compris en StrictMode) est sans conséquence.
• Les échecs. sendClientTelemetry n’est jamais rejeté : lorsque la télémétrie n’a pas pu être collectée, il se résout avec { token: null, errors }. Lisez errors, continuez sans token et gardez votre page fonctionnelle. initDeviceIntelligence lui-même n’est rejeté, avec un TypeError, que lorsque teamID est absent ou vide.
• Le rendu côté serveur. Le package peut être importé partout où un moteur de rendu serveur ou un runtime edge évalue du code client : sa carte exports fait pointer les conditions react-server, edge-light, workerd, worker et node vers une petite entrée serveur avec la même API. Là, initDeviceIntelligence se résout avec un sendClientTelemetry qui renvoie { token: null, errors }, donc du code partagé peut l’appeler sans garde.

Pour une Content-Security-Policy, le package envoie la télémétrie à l’edge cside et ne charge aucun script depuis un sous-domaine d’équipe, la seule entrée nécessaire est donc :

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

Assistant de codage IA

L’onglet AI de la page Install Device Intelligence génère un prompt qui renvoie votre assistant (Claude Code, Cursor et outils similaires) vers ce guide et inclut l’URL de script de votre équipe. Collez-le dans l’assistant et vérifiez le résultat : l’assistant doit utiliser le package NPM ou le bootstrap tolérant aux pannes ci-dessus, jamais une simple balise <script src=".../client.js">.

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.

Framer

Utilisez l’onglet Framer, ou le guide Framer, lorsque votre site est construit avec Framer. Il utilise le même bootstrap tolérant aux pannes dans le Custom Code de Framer.