Recuperar datapoints

O navegador não precisa saber o que sendClientTelemetry(externalIds?) envia internamente. Chame a função, leia o token de sessão retornado e deixe que o seu backend troque esse token de sessão com https://api.cside.com/token/v2/verify para recuperar datapoints de fingerprint, bot, navegador, dispositivo, IP e ambiente.

Fluxo de ponta a ponta

1. O navegador chama sendClientTelemetry(externalIds?).
2. sendClientTelemetry envia telemetria para https://edge.csidefd.com/client. Permita esse host no connect-src da sua CSP.
3. /client retorna JSON no formato { "token": "..." }, em que token é o token de sessão de fingerprint.
4. O seu backend envia esse token de sessão para https://api.cside.com/token/v2/verify com uma chave de API de Device Intelligence do servidor.

Uso de sendClientTelemetry

const result = await sendClientTelemetry({
  email: "user@example.com",
  userId: "1234567890",
});

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

const { token: sessionToken } = result;

if (!sessionToken) {
  throw new Error("Nenhum token de sessão de fingerprint foi retornado.");
}

Depois de extrair sessionToken, envie-o ao seu backend. O seu backend faz a troca do token com o cside.

Você também pode chamar sendClientTelemetry() sem argumentos. Use externalIds apenas quando quiser anexar os seus próprios identificadores, como userId, orderId ou email, ao fingerprint.

O exemplo acima usa o sendClientTelemetry que o client.js expõe em window. Se você instalou o pacote NPM, pegue a mesma função a partir de initDeviceIntelligence e ganhe tipos com ela:

let token = null;

try {
  const { initDeviceIntelligence } = await import("@cside.dev/device-intelligence");
  const { sendClientTelemetry } = await initDeviceIntelligence({
    teamID: "[your-team-id]",
  });
  const result = await sendClientTelemetry({ userId: "1234567890" });
  token = result.token;
  if (result.errors) console.warn(result.errors);
} catch (error) {
  console.warn("Device Intelligence unavailable", error);
}

A importação dinâmica permite que o bundler coloque o código de coleta em um arquivo separado. Inicie a importação e a inicialização o mais cedo possível: esperar pelo checkout ou login atrasa a coleta e pode perder sinais anteriores. Trate falhas de importação e inicialização e mantenha a página funcionando sem token.

Tudo abaixo vale nos dois casos. A função, os argumentos e o token de sessão devolvido são os mesmos.

Escolha os seus identificadores externos

externalIds aceita qualquer chave string, mas duas delas alimentam detecções embutidas:

O Identity graph vincula um dispositivo a uma conta por meio de userId, teamId ou customerId; sem uma dessas chaves, a sessão não tem conta à qual ser vinculada.

Um caso de uso comum de fraude no checkout é detectar um dispositivo que tenta pagar com muitos cartões diferentes. Anexe paymentCardId no momento do pagamento:

const result = await sendClientTelemetry({
  userId: "1234567890",
  orderId: "order-456",
  // Nunca o número do cartão: um hash unidirecional dele, mais os últimos 4 no máximo.
  paymentCardId: "a3f5c8d19b02e74f_4242",
});

O mesmo cartão deve sempre produzir o mesmo paymentCardId, então use um hash determinístico ou o token de cartão do seu processador, nunca um ID por tentativa. Não envie o número completo do cartão, CVC, data de validade nem outros dados brutos de cartão de pagamento por meio de externalIds.

Opções de recuperação

Gere uma chave de API backend

Gere uma chave de API de Device Intelligence em Team Settings > Device Intelligence no dashboard do cside antes de chamar o endpoint autenticado. A chave começa com cside_tgatv1_, é exibida apenas uma vez e deve ser armazenada no gerenciador de segredos do seu backend.

A chave de API é uma credencial de backend associada ao time. Não a envie ao navegador, não a exponha em bundles frontend nem a escreva em HTML a partir de um Worker.

Recuperação por API com o token de sessão

O token de sessão não contém o payload fingerprint completo. Use-o como token de lookup a partir do seu backend com o endpoint autenticado do cside.

Use /token/v2/verify quando precisar do payload JSON completo em uma integração server-to-server.

curl https://api.cside.com/token/v2/verify \
  --request POST \
  --header "Authorization: Bearer $CSIDE_FINGERPRINT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"token":"'"$CSIDE_FINGERPRINT_SESSION_TOKEN"'"}'

O endpoint retorna 202 Accepted com { "status": "pending" } enquanto a avaliação ainda está em processamento. Ele retorna 200 OK quando a avaliação termina, com "status": "completed" e o payload, ou com "status": "failed" e um error_message.

Exemplo de request no backend:

const csideResponse = await fetch("https://api.cside.com/token/v2/verify", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CSIDE_FINGERPRINT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ token: sessionToken }),
});

const datapoints = await csideResponse.json();

if (!csideResponse.ok) {
  throw new Error(datapoints.error || "A busca de fingerprint falhou.");
}

if (datapoints.status === "failed") {
  throw new Error(datapoints.error_message || "A avaliação de fingerprint falhou.");
}

A resposta concluída inclui status, created_at, updated_at e os campos de enriquecimento disponíveis: fingerprint, network_client_metrics, geo_data, ip_enrichment, vpn_evaluation, bot, fingerprint_enrichment, rule_evaluations_v2 e o legado rule_evaluations. Consulte a referência de resposta de /token/v2/verify para cada campo.

Erros e limites de requisições

As respostas de erro trazem um corpo JSON { "error": "<mensagem>", "code": <status HTTP> }, não error_message:

O limite padrão é de 1.000 requisições por minuto por time, com pequenos picos permitidos. Aguarde o período de retry-after antes de tentar novamente.

Explicações das regras

Regras publicadas com resultado verdadeiro podem incluir rule_evaluations_v2.values[].evaluation.explanation.nodes. Cada nó visitado pode descrever seu node_id, outcome, valor tipado observed, subject e compared_to. As explicações são opcionais; resultados falsos, pendentes ou ausentes não as incluem. A ausência de explicação não altera o resultado registrado.

Trate subject e compared_to como texto para exibição, não como um formato a interpretar. Use node_id, valores tipados de observed e outcome no código. Leia esses campos de rule_evaluations_v2, não do objeto legado rule_evaluations. Consulte a API de eventos para os valores dos resultados e a diferença em relação ao formato legado.

Recupere avaliações anteriores do mesmo dispositivo

Use /token/v2/device/entries quando precisar de avaliações concluídas associadas ao mesmo ID de dispositivo do token de sessão. Isso é útil para pontuação de risco de conta, filas de revisão de fraude, investigação de abuso e para vincular uma nova sessão à atividade recente do mesmo fingerprint de navegador.

O endpoint usa a mesma chave de API de Device Intelligence somente para backend que /token/v2/verify. Ele retorna resultados do mais recente para o mais antigo e oferece paginação com limit e offset.

curl https://api.cside.com/token/v2/device/entries \
  --request POST \
  --header "Authorization: Bearer $CSIDE_FINGERPRINT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "token": "'"$CSIDE_FINGERPRINT_SESSION_TOKEN"'",
    "limit": 100,
    "offset": 0
  }'

Body da requisição

Body da resposta

A resposta contém o device_id resolvido, um array entries e metadados de paginação. Cada entrada usa o mesmo formato de payload plano que /token/v2/verify.

{
  "device_id": "a1b2c3d4e5f6...",
  "entries": [
    {
      "status": "completed",
      "created_at": 1779441600000,
      "updated_at": 1779441600000,
      "fingerprint": {},
      "network_client_metrics": {}
    }
  ],
  "limit": 100,
  "offset": 0,
  "next_offset": 100,
  "has_more": true
}

Exemplo de backend

Use next_offset da resposta em vez de calcular offsets manualmente. Pare quando has_more for false.

async function fetchDeviceEntries(sessionToken) {
  const entries = [];
  let offset = 0;
  const limit = 100;

  while (offset !== null) {
    const response = await fetch("https://api.cside.com/token/v2/device/entries", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.CSIDE_FINGERPRINT_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        token: sessionToken,
        limit,
        offset,
      }),
    });

    const page = await response.json();

    if (!response.ok) {
      throw new Error(page.error || "A busca de entradas do dispositivo falhou.");
    }

    entries.push(...page.entries);
    offset = page.has_more ? page.next_offset : null;
  }

  return entries;
}

Se precisar apenas da primeira página, omita limit e offset. A API retorna até 500 avaliações concluídas por padrão.

Endpoints públicos de token

/token/v1/client e /token/v1/clientId continuam disponíveis para integrações que precisam especificamente do fluxo público não autenticado.

Use /token/v1/client quando precisar do payload JSON público sem autenticação por chave de API.

curl https://api.cside.com/token/v1/client \
  --request POST \
  --header "Content-Type: text/plain" \
  --data "$CSIDE_FINGERPRINT_SESSION_TOKEN"

Use /token/v1/clientId quando precisar apenas do fingerprint ID estável.

curl https://api.cside.com/token/v1/clientId \
  --request POST \
  --header "Content-Type: text/plain" \
  --data "$CSIDE_FINGERPRINT_SESSION_TOKEN"

Para /token/v1/*, envie o token de sessão bruto como corpo text/plain e não o envolva em JSON. Apenas os endpoints /token/v2/* aceitam { "token": "..." }. Os dois endpoints v1 retornam 202 Accepted com { "status": "pending" } enquanto a avaliação está em processamento. /token/v1/clientId então retorna JSON:

{ "status": "completed", "device_id": "a1b2c3d4e5f6..." }

Se não existir fingerprint ID para o token de sessão, ele retorna 404 com { "error": "fingerprint id not found", "code": 404 }. Os endpoints v1 compartilham o mesmo formato de erro e o mesmo limite de requisições de /token/v2/verify, com base no time do token.

Exportação S3

O cside pode exportar registros de fingerprint para S3 quando a exportação fingerprint S3 estiver configurada para um domínio. Use isso para workflows batch em que você não precisa de uma decisão no tempo da requisição.

Cada registro exportado é a avaliação completa, não um resumo: os campos de identidade, o fingerprint completo do dispositivo e os sinais de rede, IP, geo, VPN, bot, de regras e comportamentais que o cside calculou para aquela visita. Veja o guia da exportação S3 para os passos de configuração e a estrutura completa do registro.

Webhooks e streams WebSocket

Nenhum dos dois está disponível. O S3 é o único destino de exportação para dados de Device Intelligence, e não existe chave por conta que habilite entrega por webhook ou WebSocket.

Se você precisar dos dados fora de uma janela batch, chame a API no tempo da requisição.