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 identificaçã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>.csidetm.com/script.js"
  referrerpolicy="origin"
  data-src="6">
</script>

Gere um token de identificação

Depois que o script for carregado, uma função global ficará disponível. Chame-a com um identificador do cliente (ex.: um clientId ou userId) para gerar um token.

const result = await submitFingerprint("your-client-id");

Parâmetros

Parâmetro	Tipo	Descrição
`clientId`	`string`	Um identificador único para o usuário ou sessão, como um `clientId` ou `userId`.

Valor de retorno

A função retorna um objeto de token:

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

Envie o token para o seu backend

Passe o token retornado para o seu backend para verificação server-side. A URL do endpoint do seu backend será fornecida após o deploy.

URL provisória

Substitua a URL abaixo pelo endpoint real do seu backend depois que ele for provisionado.

POST https://<YOUR_BACKEND_HOST>/<PLACEHOLDER_PATH>

Exemplo de requisição

const response = await fetch("https://<YOUR_BACKEND_HOST>/<PLACEHOLDER_PATH>", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ token: result.token }),
});

const data = await response.json();

Corpo da requisição

Campo	Tipo	Descrição
`token`	`string`	O token retornado pela chamada `submitFingerprint` do lado do cliente.

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

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 booleanos e de string indicando atributos suspeitos ou notáveis do visitante.

Campo	Tipo	Descrição
`bot`	`string`	Resultado da detecção de bot. `"not_detected"` quando nenhum bot é encontrado.
`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.

`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": "not_detected",
  "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,
  "raw_device_attributes": {
    "math": "5f030fa7d2e5f9f757bfaf81642eb1a6",
    "vendor": "Google Inc."
  }
}