Configurar Device Intelligence

Configure cside Device Intelligence cargando el script del navegador temprano, recopilando telemetría con sendClientTelemetry y enviando el token de sesión devuelto a su backend.

El script no crea fingerprints por sí solo

Cargar https://[your-team-id].csidefd.com/client.js expone sendClientTelemetry en el navegador. Un fingerprint de sesión solo se crea después de que su sitio llama a sendClientTelemetry(externalIds?).

Elija una opción de implementación

Método	Mejor para	Guía de producción
Cloudflare Workers	Sitios ya enrutados por Cloudflare	Bueno para inyección en edge y despliegue por rutas limitadas
Inyección directa de script	La mayoría de sitios de producción	Recomendado cuando controla el HTML o app shell
Webflow	Sitios Webflow no-code	Use Custom code y publique antes de probar
Paquete NPM	Apps que usan un bundler	Recomendado cuando su app llama a `sendClientTelemetry`
Google Tag Manager	Validación rápida sin cambios de código	Úselo solo para pruebas cuando el orden de carga importa

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.

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.

Setup habilitado por cuenta

Los dominios personalizados de fingerprint requieren que cside aprovisione un hostname de destino para su cuenta. Contacte a cside antes de agregar registros DNS.

Configuración DNS

Elija un subdominio, por ejemplo fingerprint.example.com
Pida a cside su hostname de destino de fingerprinting
Agregue un registro CNAME desde su subdominio al destino de cside
Espere la propagación DNS y la validación del hostname por cside
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 y connect-src.

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

Solución de problemas

No aparece el icono de Device Intelligence en la UI - Confirme que Device Intelligence esté habilitado para el dominio gestionado en cside. Si quitó y volvió a agregar el dominio, es posible que la función deba habilitarse de nuevo.
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 accountId, orderId o email.

Paquete NPM

Si su app usa un bundler, instale @cside.dev/device-intelligence en lugar de pegar el bootstrap anterior. Carga el mismo client.js de su equipo y devuelve un sendClientTelemetry tipado, así que nunca recurre a window.sendClientTelemetry ni tiene que adivinar si el 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({ accountId: "1234567890" });

initDeviceIntelligence agrega <script async referrerpolicy="origin" src="https://[your-team-id].csidefd.com/client.js"> al <head> y se resuelve cuando el script se ha cargado y ha expuesto su función de telemetría. Llámelo tan pronto como su app lo permita, por la misma razón por la que el bootstrap va al principio del <head>: el script tiene que estar cargándose antes de que necesite un token.

Lo que resuelve por usted:

Llamadas repetidas. Llamarlo de nuevo para el mismo equipo se une a la carga que ya está en curso en lugar de agregar una segunda etiqueta, así que un efecto de React que se ejecuta dos veces es inofensivo. También aprovecha una etiqueta que ya esté en la página, por ejemplo una inyectada por @cside.dev/vite o @cside.dev/next.
Fallos. La promesa se rechaza si el script no carga, si no carga en diez segundos o si carga sin exponer su función de telemetría. Su página sigue funcionando: envuelva la llamada en try/catch y continúe sin token.
Renderizado en el servidor. Sin un document se resuelve con un sendClientTelemetry que devuelve { token: null, errors } en lugar de lanzar una excepción, así que el código compartido puede llamarlo sin comprobaciones.

Una página reporta para un solo equipo. Una segunda llamada con otro ID de equipo no carga nada y se resuelve con un sendClientTelemetry que informa del conflicto, porque el script del navegador expone una única función de telemetría.

Para una Content-Security-Policy, el paquete exporta la URL del script para que no tenga que codificar el formato a mano:

import { buildDeviceIntelligenceScriptUrl } from "@cside.dev/device-intelligence";

buildDeviceIntelligenceScriptUrl("[your-team-id]"); // https://[your-team-id].csidefd.com/client.js

Permita ese host en script-src y https://edge.csidefd.com en connect-src.

Otros paquetes de cside

@cside.dev/vite y @cside.dev/next inyectan la etiqueta del script en build o en render, pero no dan acceso tipado a sendClientTelemetry. Use @cside.dev/device-intelligence cuando su app llame a la función de telemetría.

Google Tag Manager

GTM sirve para pruebas rápidas, pero no garantiza que cside cargue antes que otros scripts. Use una tag Custom HTML con un trigger All Pages para validar el flujo.

Use GTM para validación

Para enforcement en producción o recopilación de datos de alta confianza, use inyección directa, un paquete NPM o Cloudflare Workers.

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.