Configurar Device Intelligence

Configure cside Device Intelligence iniciando a coleta de sinais cedo, coletando telemetria com sendClientTelemetry e enviando o token de sessão retornado ao seu backend.

Escolha uma opção de implementação

A página Install Device Intelligence do painel tem cinco abas: npm, AI, HTML, Cloudflare e Framer. npm é o padrão.

Método	Melhor para	Orientação de produção
Pacote npm	Apps construídas com um bundler	Padrão no painel. Recomendado quando a sua app chama sendClientTelemetry
Assistente de código com IA	Times que deixam o Claude Code, o Cursor ou um assistente semelhante fazer a instalação	A aba AI fornece um prompt com a URL do script do seu time para colar no assistente
Injeção direta de script (aba HTML)	Sites em que você controla o HTML ou app shell	Usa o bootstrap do navegador tolerante a falhas
Cloudflare Workers	Sites já roteados pela Cloudflare	Bom para injeção no edge e rollout em rotas limitadas
Framer	Sites Framer no-code	Use Custom Code e publique antes de testar
Webflow	Sites Webflow no-code	Use Custom code e publique antes de testar

Recomendação de domínio do cliente

Use a configuração de DNS para usar o seu próprio domínio sempre que possível. A cside oferece isso para evitar preocupações de privacidade relacionadas a domínios de terceiros, fazer o script parecer first-party para o navegador e impedir que bloqueadores de anúncios do navegador ou bloqueios client-side interfiram no script ou afetem a precisão das detecções.

Se o cside fornecer uma URL de script dedicada, use essa URL exata em todos os métodos de instalação. Os exemplos abaixo usam placeholders. Para ver a URL completa do seu script, acesse o painel do cside e abra a aba HTML.

Bootstrap do navegador tolerante a falhas

Use o bootstrap do navegador tolerante a falhas sempre que injetar o Device Intelligence diretamente em uma página. Adicione-o no início do <head>, antes dos outros scripts. Ele carrega o client.js de forma assíncrona, enfileira chamadas antecipadas e as rejeita se o cside falhar, não inicializar a telemetria ou demorar mais de dez segundos. A página continua funcionando quando o cside não está disponível. Não use uma tag simples <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>

Substitua apenas a URL do script. Sua aplicação deve tratar as chamadas rejeitadas de sendClientTelemetry e continuar o fluxo normal: esse é o comportamento tolerante a falhas.

Servir o script pelo seu próprio domínio

Com esta opção, você serve o script de Device Intelligence por um subdomínio que você controla, como fingerprint.example.com. Ela é destinada a contas de produção que querem entrega first-party do script e controle mais rígido de CSP.

Configuração DNS

1. Escolha um subdomínio, por exemplo fingerprint.example.com
2. Peça ao cside o seu hostname de destino de fingerprinting
3. Adicione um registro CNAME do seu subdomínio para o destino do cside
4. Aguarde a propagação DNS e a validação do hostname pelo cside
5. Use o seu subdomínio como origem do script

Exemplo de registro DNS:

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

Depois da validação, use a URL do script no domínio do cliente:

Use o bootstrap tolerante a falhas e substitua o valor de script.src por https://fingerprint.example.com/client.js.

Atualize sua CSP para permitir o subdomínio do cliente em script-src. A telemetria é enviada para https://edge.csidefd.com/client independentemente de onde o script é servido, então connect-src precisa de https://edge.csidefd.com. Consulte Content Security Policy.

Injeção direta de script

Injetar a tag diretamente no seu HTML é compatível. Adicione o script no <head> da página antes de chamar funções de fingerprinting.

Use o bootstrap tolerante a falhas e substitua o valor de script.src pela URL csidefd.com da sua equipe.

Depois chame sendClientTelemetry após o script carregar. Você pode chamar a função sem argumentos ou passar um objeto externalIds opcional.

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

if (result.errors) {
  console.error(result.errors);
  throw new Error("A solicitação de telemetria falhou.");
}

const { token: sessionToken } = result;

Envie o token de sessão ao seu backend e troque-o com a API do cside. Trocas de backend em produção usam uma chave de API de Device Intelligence do servidor gerada no dashboard do cside. Consulte a Events API para o fluxo completo.

Content Security Policy

Seja qual for o método de instalação, o navegador envia a telemetria para https://edge.csidefd.com/client. Permita esse host em connect-src. Quando você carrega client.js de um subdomínio do time ou do seu próprio domínio first-party, permita também essa origem do script em script-src:

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

O pacote npm não carrega nenhum script remoto, então só precisa da entrada connect-src. Consulte Ajustando sua CSP para saber como o cside ajuda você a gerenciar a política.

Solução de problemas

• Nenhum dado de Device Intelligence em lugar nenhum - Confirme que Device Intelligence está ativado para o time em Install Device Intelligence. A ativação exige pelo menos um domínio gerenciado e não suspenso: ativar um time sem domínio funciona, mas não coleta nada.
• O script carrega, mas nenhum fingerprint aparece - Confirme que o seu site chama sendClientTelemetry(externalIds?) depois que o script carrega. Carregar client.js apenas disponibiliza a função.
• IDs personalizados ausentes - Passe externalIds opcionais ao chamar sendClientTelemetry, como userId, orderId ou email.

Pacote NPM

Se a sua app é construída com um bundler, instale @cside.dev/device-intelligence em vez de colar o bootstrap acima. É o método padrão na configuração de Device Intelligence do painel do cside. O código de coleta vem incluído no pacote, então não há nenhum script remoto para carregar, e ele devolve um sendClientTelemetry tipado, então você nunca recorre a window.sendClientTelemetry nem precisa adivinhar se um script já carregou.

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 a coleta passiva de sinais e o rastreamento de comportamento assim que é chamado, então uma chamada posterior a sendClientTelemetry só precisa executar as sondagens por chamada. Chame-o o mais cedo que a sua app permitir, pelo mesmo motivo que o bootstrap fica no topo do <head>: a coleta precisa estar em andamento antes de você precisar de um token.

O que ele resolve para você:

• Chamadas repetidas. A coleta só começa uma vez por página e toda chamada é resolvida com o mesmo sendClientTelemetry, então um efeito do React que roda duas vezes (inclusive em StrictMode) é inofensivo.
• Falhas. sendClientTelemetry nunca é rejeitado: quando a telemetria não pôde ser coletada, ele é resolvido com { token: null, errors }. Leia errors, siga sem token e mantenha a sua página funcionando. O próprio initDeviceIntelligence só é rejeitado, com um TypeError, quando teamID está ausente ou vazio.
• Renderização no servidor. O pacote pode ser importado onde quer que um renderizador de servidor ou runtime edge avalie código de cliente: o seu mapa exports aponta as condições react-server, edge-light, workerd, worker e node para uma pequena entrada de servidor com a mesma API. Ali, initDeviceIntelligence é resolvido com um sendClientTelemetry que devolve { token: null, errors }, então código compartilhado pode chamá-lo sem verificações.

Para uma Content-Security-Policy, o pacote envia a telemetria para o edge do cside e não carrega nenhum script de um subdomínio da equipe, então a única entrada necessária é:

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

Assistente de código com IA

A aba AI da página Install Device Intelligence gera um prompt que aponta o seu assistente (Claude Code, Cursor e ferramentas semelhantes) para este guia e inclui a URL do script do seu time. Cole-o no assistente e revise o resultado: o assistente deve usar o pacote npm ou o bootstrap tolerante a falhas acima, nunca uma tag <script src=".../client.js"> isolada.

Cloudflare Workers

Use Cloudflare Workers quando o tráfego já passa pela Cloudflare e você quer controlar a injeção do script no edge. Consulte o guia de Cloudflare Workers.

Framer

Use a aba Framer, ou o guia do Framer, quando o seu site é construído com Framer. Ele usa o mesmo bootstrap tolerante a falhas no Custom Code do Framer.