Events API

Este guia orienta você na integração completa da Events API de cside Device Intelligence: 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

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;

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

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();

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();

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

browser_details

Detalhes sobre o navegador e sistema operacional do visitante.

identification

O resultado principal de identificação 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.

proximity

Dados de geolocalização de proximidade do visitante.

ip_info

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

ip_blocklist

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

Sinais de fraude e ambiente

Sinais indicando atributos suspeitos ou notáveis do visitante.

vpn_methods

vpn_methods contém sinais no nível de método relacionados ao uso de VPN e ao tráfego anonimizado. Use o campo de nível superior vpn como veredito geral. O valor de um método pode ser true quando vpn é false, por exemplo, quando o cside detecta tráfego de proxy ou relay que o modelo de VPN não classifica como VPN.

raw_device_attributes

Componentes de fingerprint de baixo nível do navegador.

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",
  "vpn_origin_timezone": "Europe/Amsterdam",
  "vpn_origin_country": "NL",
  "vpn_methods": {
    "timezone_mismatch": false,
    "public_vpn": false,
    "auxiliary_mobile": false,
    "os_mismatch": false,
    "relay": true
  },
  "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."
  }
}