Events API

Esta guía le explica cómo integrar la Events API de cside Device Intelligence de principio a fin: cargar el script del cliente, generar un token de sesión, enviarlo a su backend e interpretar la respuesta.

Flujo de integración

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

// O llamarla sin argumentos
// const result = await sendClientTelemetry();

if (result.errors) {
  console.error(result.errors);
  throw new Error("La solicitud de telemetría falló.");
}

const token = result.token;

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

if (!token) {
  throw new Error("No se devolvió un token de sesión de fingerprint.");
}

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

Referencia de la respuesta

Esta referencia de respuesta se aplica a /token/v1/client. El endpoint autenticado /token/v2/verify devuelve un payload JSON plano con status, created_at, updated_at y los campos de enriquecimiento disponibles, como vpn_evaluation, fingerprint, geo_data, ip_enrichment, bot, network_client_metrics y fingerprint_enrichment. El endpoint autenticado /token/v2/device/entries devuelve un device_id, un array entries con esos mismos payloads planos para evaluaciones completadas asociadas a ese ID de dispositivo y campos de paginación como limit, offset, next_offset y has_more.

La respuesta del backend incluye identificación del visitante, detalles del navegador, inteligencia IP y un conjunto de señales de detección de fraude.

Campos de nivel superior

browser_details

Detalles sobre el navegador y el sistema operativo del visitante.

identification

El resultado de identificación principal del visitante.

supplementary_id_high_recall

Una identificación secundaria optimizada para mayor recall (menos falsos negativos) a costa de una precisión ligeramente menor.

proximity

Datos de proximidad geográfica del visitante.

ip_info

Información de la dirección IP del visitante.

ip_blocklist

Si la IP del visitante aparece en listas de bloqueo conocidas.

Señales de fraude y entorno

Señales que indican atributos sospechosos o notables del visitante.

vpn_methods

vpn_methods contiene señales a nivel de método relacionadas con el uso de VPN y el tráfico anonimizado. Use el campo de nivel superior vpn como veredicto general. El valor de un método puede ser true cuando vpn es false, por ejemplo, cuando cside detecta tráfico de proxy o relay que el modelo de VPN no clasifica como VPN.

raw_device_attributes

Componentes de bajo nivel del fingerprint del navegador.

Ejemplo completo de respuesta

{
  "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."
  }
}