Configurar Device Intelligence

Configure cside Device Intelligence carregando o script do navegador cedo, coletando telemetria com sendClientTelemetry e enviando o token de sessão retornado ao seu backend.

O script não cria fingerprints sozinho

Carregar https://[your-team-id].csidefd.com/client.js expõe sendClientTelemetry no navegador. Um fingerprint de sessão só é criado depois que o seu site chama sendClientTelemetry(externalIds?).

Escolha uma opção de implementação

Método	Melhor para	Orientação de produção
Cloudflare Workers	Sites já roteados pela Cloudflare	Bom para injeção no edge e rollout em rotas limitadas
Injeção direta de script	A maioria dos sites em produção	Recomendado quando você controla o HTML ou app shell
Webflow	Sites Webflow no-code	Use Custom code e publique antes de testar
Pacote NPM	Apps construídas com um bundler	Recomendado quando a sua app chama `sendClientTelemetry`
Google Tag Manager	Validação rápida sem mudar código	Use apenas para teste quando a ordem dos scripts importa

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.

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.

Setup habilitado por conta

Domínios personalizados de fingerprint exigem que o cside provisione um hostname de destino para a sua conta. Fale com o cside antes de adicionar registros DNS.

Configuração DNS

Escolha um subdomínio, por exemplo fingerprint.example.com
Peça ao cside o seu hostname de destino de fingerprinting
Adicione um registro CNAME do seu subdomínio para o destino do cside
Aguarde a propagação DNS e a validação do hostname pelo cside
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 e connect-src.

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

Solução de problemas

Ícone de Device Intelligence ausente na UI - Confirme que Device Intelligence está ativado para o domínio gerenciado no cside. Se você removeu e adicionou o domínio novamente, a função pode precisar ser ativada de novo.
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 accountId, 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. Ele carrega o mesmo client.js da sua equipe e devolve um sendClientTelemetry tipado, então você nunca recorre a window.sendClientTelemetry nem precisa adivinhar se o 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({ accountId: "1234567890" });

initDeviceIntelligence adiciona <script async referrerpolicy="origin" src="https://[your-team-id].csidefd.com/client.js"> ao <head> e é resolvido assim que o script carrega e expõe a sua função de telemetria. Chame-o o mais cedo que a sua app permitir, pelo mesmo motivo que o bootstrap fica no topo do <head>: o script precisa estar carregando antes de você precisar de um token.

O que ele resolve para você:

Chamadas repetidas. Chamar de novo para a mesma equipe entra no carregamento que já está em andamento em vez de adicionar uma segunda tag, então um efeito do React que roda duas vezes é inofensivo. Ele também aproveita uma tag que já esteja na página, por exemplo injetada por @cside.dev/vite ou @cside.dev/next.
Falhas. A promise é rejeitada se o script não carregar, não carregar em dez segundos, ou carregar sem expor a sua função de telemetria. A sua página continua funcionando: envolva a chamada em try/catch e siga sem token.
Renderização no servidor. Sem um document, ele é resolvido com um sendClientTelemetry que devolve { token: null, errors } em vez de lançar erro, então código compartilhado pode chamá-lo sem verificações.

Uma página reporta para uma única equipe. Uma segunda chamada com outro ID de equipe não carrega nada e é resolvida com um sendClientTelemetry que informa o conflito, porque o script do navegador expõe uma única função de telemetria.

Para uma Content-Security-Policy, o pacote exporta a URL do script para você não precisar fixar o formato:

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

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

Libere esse host em script-src e https://edge.csidefd.com em connect-src.

Outros pacotes do cside

@cside.dev/vite e @cside.dev/next injetam a tag do script no build ou na renderização, mas não dão acesso tipado a sendClientTelemetry. Use @cside.dev/device-intelligence quando a sua app chama a função de telemetria.

Google Tag Manager

GTM é útil para testes rápidos, mas não garante que o cside carregue antes de outros scripts. Use uma tag Custom HTML com trigger All Pages para validar o fluxo.

Use GTM para validação

Para enforcement em produção ou coleta de dados de alta confiança, use injeção direta, um pacote NPM ou Cloudflare Workers.

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.