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 com frameworks compatíveis	Recomendado quando o pacote posiciona o script cedo
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

Para frameworks compatíveis, use o pacote do cside que adiciona o script do navegador ao app shell. Isso é útil quando o seu framework controla a renderização do documento.

O pacote ainda deve carregar o mesmo script do cside antes que a sua app chame sendClientTelemetry.

Fale com a equipe da cside para receber ajuda se tiver interesse em usar o método de instalação NPM.

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.