Configurar Device Intelligence

Configure cside Device Intelligence iniciando la recopilación de señales temprano, recopilando telemetría con sendClientTelemetry y enviando el token de sesión devuelto a su backend.

Elija una opción de implementación

La página Install Device Intelligence del panel tiene cinco pestañas: npm, AI, HTML, Cloudflare y Framer. npm es la predeterminada.

Método	Mejor para	Guía de producción
Paquete npm	Apps que usan un bundler	Opción predeterminada en el panel. Recomendado cuando su app llama a sendClientTelemetry
Asistente de codificación con IA	Equipos que dejan que Claude Code, Cursor o un asistente similar haga la instalación	La pestaña AI le da un prompt con la URL de script de su equipo para pegarlo en el asistente
Inyección directa de script (pestaña HTML)	Sitios donde controla el HTML o app shell	Usa el bootstrap del navegador tolerante a fallos
Cloudflare Workers	Sitios ya enrutados por Cloudflare	Bueno para inyección en edge y despliegue por rutas limitadas
Framer	Sitios Framer no-code	Use Custom Code y publique antes de probar
Webflow	Sitios Webflow no-code	Use Custom code y publique antes de probar

Recomendación de dominio del cliente

Use la configuración DNS para usar su propio dominio siempre que sea posible. cside ofrece esto para evitar inquietudes de privacidad relacionadas con dominios de terceros, hacer que el script parezca first-party para el navegador y evitar que los bloqueadores de anuncios del navegador o el bloqueo client-side interfieran con el script o afecten la precisión de las detecciones.

Si cside le proporciona una URL de script dedicada, use esa URL exacta en cada método de instalación. Los ejemplos siguientes usan placeholders. Para ver su URL de script completa, vaya al panel de cside y abra la pestaña HTML.

Bootstrap del navegador tolerante a fallos

Use el bootstrap del navegador tolerante a fallos siempre que inyecte Device Intelligence directamente en una página. Colóquelo al principio del <head>, antes de otros scripts. Carga client.js de forma asíncrona, pone en cola las llamadas tempranas y las rechaza si cside falla, no inicializa la telemetría o tarda más de diez segundos. La página sigue funcionando aunque cside no esté disponible. No use una etiqueta <script src=".../client.js"> simple.

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

Reemplace solo la URL del script. Su aplicación debe manejar las llamadas rechazadas a sendClientTelemetry y continuar con su flujo normal: ese es el comportamiento tolerante a fallos.

Servir el script desde su propio dominio

Con esta opción puede servir el script de Device Intelligence desde un subdominio que usted controla, como fingerprint.example.com. Está pensada para cuentas de producción que quieren entrega first-party del script y control más estricto de CSP.

Configuración DNS

1. Elija un subdominio, por ejemplo fingerprint.example.com
2. Pida a cside su hostname de destino de fingerprinting
3. Agregue un registro CNAME desde su subdominio al destino de cside
4. Espere la propagación DNS y la validación del hostname por cside
5. Use su subdominio como origen del script

Ejemplo de registro DNS:

Tipo	Nombre	Valor
CNAME	fingerprint.example.com	[your-team-id].csidefd.com

Después de la validación, use la URL del script en el dominio del cliente:

Use el bootstrap tolerante a fallos y cambie su valor script.src por https://fingerprint.example.com/client.js.

Actualice su CSP para permitir el subdominio del cliente en script-src. La telemetría se envía a https://edge.csidefd.com/client sin importar desde dónde se sirva el script, así que connect-src necesita https://edge.csidefd.com. Consulte Content Security Policy.

Inyección directa de script

Inyectar la tag directamente en su HTML es compatible. Agregue el script en el <head> de la página antes de llamar funciones de fingerprinting.

Use el bootstrap tolerante a fallos y cambie su valor script.src por la URL de csidefd.com de su equipo.

Luego llame a sendClientTelemetry después de que cargue el script. Puede llamarla sin argumentos o pasar un objeto externalIds opcional.

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

if (result.errors) {
  console.error(result.errors);
  throw new Error("La solicitud de telemetría falló.");
}

const { token: sessionToken } = result;

Envíe el token de sesión a su backend e intercámbielo con la API de cside. Los intercambios backend de producción usan una clave API de Device Intelligence del servidor generada en el dashboard de cside. Consulte la Events API para el flujo completo.

Content Security Policy

Sea cual sea el método de instalación que use, el navegador envía la telemetría a https://edge.csidefd.com/client. Permita ese host en connect-src. Cuando cargue client.js desde un subdominio del equipo o desde su propio dominio first-party, permita también ese origen del script en script-src:

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

El paquete npm no carga ningún script remoto, así que solo necesita la entrada connect-src. Consulte Ajustar su CSP para ver cómo cside le ayuda a gestionar la política.

Solución de problemas

• No hay datos de Device Intelligence en ningún sitio - Confirme que Device Intelligence esté habilitado para el equipo en Install Device Intelligence. El interruptor necesita al menos un dominio gestionado y no suspendido: activar un equipo sin ninguno funciona, pero no recopila nada.
• El script carga, pero no aparecen fingerprints - Confirme que su sitio llama a sendClientTelemetry(externalIds?) después de que carga el script. Cargar client.js solo hace que la función esté disponible.
• Faltan IDs personalizados - Pase externalIds opcionales al llamar a sendClientTelemetry, como userId, orderId o email.

Paquete NPM

Si su app usa un bundler, instale @cside.dev/device-intelligence en lugar de pegar el bootstrap anterior. Es el método predeterminado en la configuración de Device Intelligence del panel de cside. El código de recopilación viene incluido en el paquete, así que no hay ningún script remoto que cargar, y devuelve un sendClientTelemetry tipado, así que nunca recurre a window.sendClientTelemetry ni tiene que adivinar si un script ya se cargó.

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 inicia la recopilación pasiva de señales y el seguimiento de comportamiento en cuanto se llama, así que una llamada posterior a sendClientTelemetry solo tiene que ejecutar las pruebas por llamada. Llámelo tan pronto como su app lo permita, por la misma razón por la que el bootstrap va al principio del <head>: la recopilación tiene que estar en marcha antes de que necesite un token.

Lo que resuelve por usted:

• Llamadas repetidas. La recopilación solo se inicia una vez por página y cada llamada se resuelve con el mismo sendClientTelemetry, así que un efecto de React que se ejecuta dos veces (también en StrictMode) es inofensivo.
• Fallos. sendClientTelemetry nunca se rechaza: cuando no se pudo recopilar telemetría se resuelve con { token: null, errors }. Lea errors, continúe sin token y mantenga su página funcionando. initDeviceIntelligence solo se rechaza, con un TypeError, cuando falta teamID o está vacío.
• Renderizado en el servidor. El paquete se puede importar donde sea que un renderizador de servidor o un runtime edge evalúe código de cliente: su mapa exports apunta las condiciones react-server, edge-light, workerd, worker y node a una pequeña entrada de servidor con la misma API. Allí, initDeviceIntelligence se resuelve con un sendClientTelemetry que devuelve { token: null, errors }, así que el código compartido puede llamarlo sin comprobaciones.

Para una Content-Security-Policy, el paquete envía la telemetría al edge de cside y no carga ningún script desde un subdominio del equipo, así que la única entrada que necesita es:

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

Asistente de codificación con IA

La pestaña AI de la página Install Device Intelligence genera un prompt que dirige a su asistente (Claude Code, Cursor y herramientas similares) a esta guía e incluye la URL de script de su equipo. Péguelo en el asistente y revise el resultado: el asistente debe usar el paquete npm o el bootstrap tolerante a fallos anterior, nunca una etiqueta <script src=".../client.js"> simple.

Cloudflare Workers

Use Cloudflare Workers cuando el tráfico ya pasa por Cloudflare y quiera controlar la inyección del script en edge. Consulte la guía de Cloudflare Workers.

Framer

Use la pestaña Framer, o la guía de Framer, cuando su sitio esté construido con Framer. Usa el mismo bootstrap tolerante a fallos en el Custom Code de Framer.