Events API | cside docs

Este guia orienta você na integração completa da Events API de fingerprinting do cside: carregando o script do cliente, gerando um token de sessão, enviando-o para o seu backend e interpretando o payload de resposta.

Fluxo de integração

Adicione o script à sua página

Inclua o script de fingerprinting do cside no <head> da sua página. Ele deve ser carregado antes de chamar qualquer função de fingerprinting.

<script
  src="https://<YOUR_SUBDOMAIN>.csidefd.com/client.js"
  referrerpolicy="origin"
  data-src="6">
</script>

Envie a telemetria e receba um token de sessão

Depois que o script for carregado, a função global sendClientTelemetry ficará disponível. Carregar o script não cria um fingerprint de sessão sozinho. Chame sendClientTelemetry(externalIds?) para enviar telemetria para /client e receber um token de sessão. Passe um objeto externalIds opcional se quiser anexar os seus próprios identificadores.

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

// Ou chame sem argumentos
// const result = await sendClientTelemetry();

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

const token = result.token;

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`externalIds`	`Record<string, string>`	Não	Identificadores opcionais que você quer anexar ao fingerprint, como `accountId`, `orderId` ou `email`.

Para receber o sinal throwawayEmail, passe o endereço de e-mail neste objeto usando a chave email.

Valor de retorno

A função retorna um objeto JSON (já analisado, então você não precisa chamar .json() nele):

{
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

O campo token contém o token de sessão de fingerprint. Se a coleta de telemetria encontrar problemas, o objeto também inclui um array opcional errors que você pode registrar. Extraia result.token e envie apenas essa string do token de sessão para o seu backend.

Recupere dados de fingerprint a partir do seu backend

Gere uma chave de API de fingerprint apenas para backend no dashboard do cside, armazene-a como segredo do servidor e use-a para trocar o token de sessão com o cside. A chave de API é exibida apenas uma vez e não deve ser exposta em código de navegador.

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

const response = 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 }),
});

const data = await response.json();

Corpo da requisição

Envie JSON no formato { "token": "<token de sessão>" }, em que o valor é result.token da etapa anterior.

Opções de lookup do token

Use o endpoint autenticado para trocas server-to-server em produção. Os endpoints públicos continuam disponíveis quando uma integração precisa especificamente do fluxo de lookup não autenticado.

Endpoint	Resposta	Use quando
`/token/v2/verify`	JSON	Você precisar de recuperação backend autenticada com uma chave de API de fingerprint.
`/token/v2/device/entries`	JSON	Você precisar de avaliações concluídas para o mesmo ID de dispositivo de um token de sessão.
`/token/v1/client`	JSON	Você precisar do payload público de resposta de fingerprinting.
`/token/v1/clientId`	Texto simples	Você precisar apenas do fingerprint ID estável do fluxo público de lookup.

/token/v2/verify retorna 202 Accepted com { "status": "pending" } durante o processamento, e depois 200 OK com o payload concluído. /token/v2/device/entries aceita { "token": "...", "limit": 100, "offset": 0 } e retorna { "device_id": "...", "entries": [...], "next_offset": 100, "has_more": true }, em que cada entrada usa o formato de resposta de /token/v2/verify. limit é opcional, o padrão é 500 e o limite máximo é 500. O endpoint clientId retorna apenas o identificador único do fingerprint em texto simples. Se não existir um identificador único do fingerprint para o token de sessão, ele retorna 404.

Exemplo de requisição 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 }),
});

const data = await csideResponse.json();

Interprete a resposta do backend

Seu backend retorna uma resposta JSON contendo o resultado da identificação e sinais associados. Consulte a referência completa de resposta abaixo.

Referência de resposta

Esta referência de resposta se aplica a /token/v1/client. O endpoint autenticado /token/v2/verify retorna um payload JSON plano com status, created_at, updated_at e os campos de enriquecimento disponíveis, como vpn_evaluation, fingerprint, geo_data, ip_enrichment, bot, network_client_metrics e fingerprint_enrichment. O endpoint autenticado /token/v2/device/entries retorna um device_id, um array entries com esses mesmos payloads planos para avaliações concluídas associadas a esse ID de dispositivo e campos de paginação como limit, offset, next_offset e has_more.

A resposta do backend inclui identificação do visitante, detalhes do navegador, inteligência de IP e um conjunto de sinais de detecção de fraude.

Campos de nível superior

Campo	Tipo	Descrição
`linked_id`	`string`	Um identificador que você associou a este visitante.
`tags`	`object`	Metadados personalizados anexados ao evento.
`timestamp`	`number`	Timestamp Unix (milissegundos) do evento.
`event_id`	`string`	Identificador único para este evento de fingerprinting.
`url`	`string`	A URL da página onde o fingerprint foi coletado.
`ip_address`	`string`	O endereço IP do visitante.
`user_agent`	`string`	A string User-Agent bruta do navegador do visitante.
`client_referrer`	`string`	A URL de referência da página.

`browser_details`

Detalhes sobre o navegador e sistema operacional do visitante.

Campo	Tipo	Descrição
`browser_name`	`string`	Nome do navegador (ex.: `"Chrome"`).
`browser_major_version`	`string`	Número da versão principal.
`browser_full_version`	`string`	String da versão completa.
`os`	`string`	Nome do sistema operacional.
`os_version`	`string`	Versão do sistema operacional.
`device`	`string`	Tipo de dispositivo (ex.: `"Other"`, `"Mobile"`).

`identification`

O resultado principal de identificação do visitante.

Campo	Tipo	Descrição
`visitor_id`	`string`	Um identificador único e estável para este visitante.
`confidence.score`	`number`	Pontuação de confiança entre `0` e `1`.
`confidence.version`	`string`	Versão do modelo de confiança utilizado.
`visitor_found`	`boolean`	Se este visitante foi visto anteriormente.
`first_seen_at`	`number`	Timestamp Unix (ms) da primeira identificação do visitante.
`last_seen_at`	`number`	Timestamp Unix (ms) da identificação mais recente do visitante.

`supplementary_id_high_recall`

Uma identificação secundária otimizada para maior recall (menos falsos negativos) ao custo de precisão ligeiramente menor.

Campo	Tipo	Descrição
`visitor_id`	`string`	Identificador do visitante sob o modelo de alto recall.
`visitor_found`	`boolean`	Se este visitante foi encontrado.
`confidence.score`	`number`	Pontuação de confiança entre `0` e `1`.
`confidence.version`	`string`	Versão do modelo de confiança utilizado.
`first_seen_at`	`number`	Timestamp Unix (ms) da primeira identificação.
`last_seen_at`	`number`	Timestamp Unix (ms) da identificação mais recente.

`proximity`

Dados de geolocalização de proximidade do visitante.

Campo	Tipo	Descrição
`id`	`string`	Identificador de localização de proximidade.
`precision_radius`	`number`	Raio de precisão em quilômetros.
`confidence`	`number`	Pontuação de confiança para a estimativa de proximidade.

`ip_info`

Informações do endereço IP do visitante.

Campo	Tipo	Descrição
`v4.address`	`string`	Endereço IPv4.
`v6.address`	`string`	Endereço IPv6.

`ip_blocklist`

Se o IP do visitante aparece em listas de bloqueio conhecidas.

Campo	Tipo	Descrição
`email_spam`	`boolean`	IP está associado a spam de e-mail.
`attack_source`	`boolean`	IP é uma fonte de ataque conhecida.
`tor_node`	`boolean`	IP é um nó de saída Tor.

Sinais de fraude e ambiente

Sinais indicando atributos suspeitos ou notáveis do visitante.

Campo	Tipo	Descrição
`bot.result`	`string`	Status da detecção de bot. Use `"detected"` ou `"not_detected"`.
`bot.score`	`number`	Pontuação numérica de bot.
`bot.signal`	`string[]`	Sinais que contribuíram para a detecção de bot.
`root_apps`	`boolean`	Dispositivo tem aplicativos root/superusuário instalados.
`emulator`	`boolean`	Dispositivo é um emulador.
`proxy`	`boolean`	Visitante está usando um proxy.
`proxy_confidence`	`string`	Nível de confiança: `"low"`, `"medium"` ou `"high"`.
`vpn`	`boolean`	Visitante está usando uma VPN.
`vpn_confidence`	`string`	Nível de confiança: `"low"`, `"medium"` ou `"high"`.
`incognito`	`boolean`	Navegador está no modo anônimo/privado.
`tampering`	`boolean`	Atributos do navegador foram adulterados.
`jailbroken`	`boolean`	Dispositivo está com jailbreak.
`frida`	`boolean`	Kit de instrumentação Frida detectado.
`virtual_machine`	`boolean`	Visitante está executando em uma máquina virtual.
`developer_tools`	`boolean`	Ferramentas de desenvolvedor do navegador estão abertas.
`mitm_attack`	`boolean`	Ataque man-in-the-middle detectado.
`replayed`	`boolean`	A requisição é uma repetição de uma requisição anterior.
`high_activity_device`	`boolean`	Número incomumente alto de identificações deste dispositivo.
`throwawayEmail`	`boolean`	`true` quando o identificador `email` enviado é um endereço de e-mail descartável ou temporário.

`raw_device_attributes`

Componentes de fingerprint de baixo nível do navegador.

Campo	Tipo	Descrição
`math`	`string`	Hash da saída do motor matemático.
`vendor`	`string`	String do fornecedor de GPU/gráficos.

Exemplo completo de resposta

{
  "linked_id": "somelinkedId",
  "tags": {},
  "timestamp": 1708102555327,
  "event_id": "1708102555327.NLOjmg",
  "url": "http://www.example.com/login",
  "ip_address": "61.127.217.15",
  "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) ...",
  "client_referrer": "https://example.com/blog/my-article",
  "browser_details": {
    "browser_name": "Chrome",
    "browser_major_version": "74",
    "browser_full_version": "74.0.3729",
    "os": "Windows",
    "os_version": "7",
    "device": "Other"
  },
  "identification": {
    "visitor_id": "Ibk1527CUFmcnjLwIs4A9",
    "confidence": { "score": 0.97, "version": "1.1" },
    "visitor_found": false,
    "first_seen_at": 1708102555327,
    "last_seen_at": 1708102555327
  },
  "supplementary_id_high_recall": {
    "visitor_id": "3HNey93AkBW6CRbxV6xP",
    "visitor_found": true,
    "confidence": { "score": 0.97, "version": "1.1" },
    "first_seen_at": 1708102555327,
    "last_seen_at": 1708102555327
  },
  "proximity": {
    "id": "w1aTfd4MCvl",
    "precision_radius": 10,
    "confidence": 0.95
  },
  "bot": {
    "result": "not_detected",
    "score": 0,
    "signal": []
  },
  "root_apps": false,
  "emulator": false,
  "ip_info": {
    "v4": { "address": "94.142.239.124" },
    "v6": { "address": "2001:db8:3333:4444:5555:6666:7777:8888" }
  },
  "ip_blocklist": {
    "email_spam": false,
    "attack_source": false,
    "tor_node": false
  },
  "proxy": true,
  "proxy_confidence": "low",
  "vpn": false,
  "vpn_confidence": "high",
  "incognito": false,
  "tampering": false,
  "jailbroken": false,
  "frida": false,
  "virtual_machine": false,
  "developer_tools": false,
  "mitm_attack": false,
  "replayed": false,
  "high_activity_device": false,
  "throwawayEmail": false,
  "raw_device_attributes": {
    "math": "5f030fa7d2e5f9f757bfaf81642eb1a6",
    "vendor": "Google Inc."
  }
}