Events API | cside docs

Esta guía le explica cómo integrar la Events API de cside fingerprinting 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

Agregue el script a su página

Incluya el script de cside fingerprinting en el <head> de su página. Debe cargarse antes de llamar a cualquier función de fingerprinting.

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

Envíe la telemetría y reciba un token de sesión

Una vez que el script se haya cargado, la función global sendClientTelemetry estará disponible. Cargar el script no crea un fingerprint de sesión por sí solo. Llame a sendClientTelemetry(externalIds?) para enviar telemetría a /client y recibir un token de sesión. Pase un objeto externalIds opcional si quiere adjuntar sus propios identificadores.

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;

Parámetros

Parámetro	Tipo	Requerido	Descripción
`externalIds`	`Record<string, string>`	No	Identificadores opcionales que quiere adjuntar al fingerprint, como `accountId`, `orderId` o `email`.

Para recibir la señal throwawayEmail, pase la dirección de correo electrónico en este objeto usando la clave email.

Valor de retorno

La función devuelve un objeto JSON (ya analizado, por lo que no necesita llamar a .json() sobre él):

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

El campo token contiene el token de sesión de fingerprint. Si la recopilación de telemetría encuentra problemas, el objeto también incluye un array opcional errors que puede registrar. Extraiga result.token y envíe solo esa cadena del token de sesión a su backend.

Recupere datos de fingerprint desde su backend

Genere una clave API de fingerprint solo para backend en el dashboard de cside, guárdela como secreto del servidor y úsela para intercambiar el token de sesión con cside. La clave API se muestra solo una vez y no debe exponerse en código de navegador.

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

Cuerpo de la solicitud

Envíe JSON con la forma { "token": "<token de sesión>" }, donde el valor es result.token del paso anterior.

Opciones de lookup del token

Use el endpoint autenticado para intercambios server-to-server de producción. Los endpoints públicos siguen disponibles cuando una integración necesita específicamente el flujo de lookup no autenticado.

Endpoint	Respuesta	Úselo cuando
`/token/v2/verify`	JSON	Necesite recuperación backend autenticada con una clave API de fingerprint.
`/token/v2/device/entries`	JSON	Necesite evaluaciones completadas para el mismo ID de dispositivo que un token de sesión.
`/token/v1/client`	JSON	Necesite el payload público de respuesta de fingerprinting.
`/token/v1/clientId`	Texto plano	Solo necesite el fingerprint ID estable del flujo público de lookup.

/token/v2/verify devuelve 202 Accepted con { "status": "pending" } mientras procesa, luego 200 OK con el payload completado. /token/v2/device/entries acepta { "token": "...", "limit": 100, "offset": 0 } y devuelve { "device_id": "...", "entries": [...], "next_offset": 100, "has_more": true }, donde cada entrada usa la forma de respuesta de /token/v2/verify. limit es opcional, su valor predeterminado es 500 y el máximo permitido es 500. El endpoint clientId devuelve solo el identificador único del fingerprint como texto plano. Si no existe un identificador único del fingerprint para el token de sesión, devuelve 404.

Ejemplo de solicitud 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 la respuesta del backend

Su backend devuelve una respuesta JSON que contiene el resultado de identificación y las señales asociadas. Consulte la referencia completa de la respuesta a continuación.

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

Campo	Tipo	Descripción
`linked_id`	`string`	Un identificador que usted asoció con este visitante.
`tags`	`object`	Metadatos personalizados adjuntos al evento.
`timestamp`	`number`	Marca de tiempo Unix (milisegundos) del evento.
`event_id`	`string`	Identificador único para este evento de fingerprinting.
`url`	`string`	La URL de la página donde se recopiló el fingerprint.
`ip_address`	`string`	La dirección IP del visitante.
`user_agent`	`string`	La cadena User-Agent sin procesar del navegador del visitante.
`client_referrer`	`string`	La URL de referencia de la página.

`browser_details`

Detalles sobre el navegador y el sistema operativo del visitante.

Campo	Tipo	Descripción
`browser_name`	`string`	Nombre del navegador (por ejemplo, `"Chrome"`).
`browser_major_version`	`string`	Número de versión principal.
`browser_full_version`	`string`	Cadena de versión completa.
`os`	`string`	Nombre del sistema operativo.
`os_version`	`string`	Versión del sistema operativo.
`device`	`string`	Tipo de dispositivo (por ejemplo, `"Other"`, `"Mobile"`).

`identification`

El resultado de identificación principal del visitante.

Campo	Tipo	Descripción
`visitor_id`	`string`	Un identificador único y estable para este visitante.
`confidence.score`	`number`	Puntuación de confianza entre `0` y `1`.
`confidence.version`	`string`	Versión del modelo de confianza utilizado.
`visitor_found`	`boolean`	Si este visitante ha sido visto antes.
`first_seen_at`	`number`	Marca de tiempo Unix (ms) de la primera identificación del visitante.
`last_seen_at`	`number`	Marca de tiempo Unix (ms) de la identificación más reciente 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.

Campo	Tipo	Descripción
`visitor_id`	`string`	Identificador del visitante bajo el modelo de alto recall.
`visitor_found`	`boolean`	Si se encontró al visitante.
`confidence.score`	`number`	Puntuación de confianza entre `0` y `1`.
`confidence.version`	`string`	Versión del modelo de confianza utilizado.
`first_seen_at`	`number`	Marca de tiempo Unix (ms) de la primera identificación.
`last_seen_at`	`number`	Marca de tiempo Unix (ms) de la identificación más reciente.

`proximity`

Datos de proximidad geográfica del visitante.

Campo	Tipo	Descripción
`id`	`string`	Identificador de ubicación de proximidad.
`precision_radius`	`number`	Radio de precisión en kilómetros.
`confidence`	`number`	Puntuación de confianza para la estimación de proximidad.

`ip_info`

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

Campo	Tipo	Descripción
`v4.address`	`string`	Dirección IPv4.
`v6.address`	`string`	Dirección IPv6.

`ip_blocklist`

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

Campo	Tipo	Descripción
`email_spam`	`boolean`	La IP está asociada con spam de correo electrónico.
`attack_source`	`boolean`	La IP es una fuente de ataque conocida.
`tor_node`	`boolean`	La IP es un nodo de salida de Tor.

Señales de fraude y entorno

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

Campo	Tipo	Descripción
`bot.result`	`string`	Estado de detección de bot. Use `"detected"` o `"not_detected"`.
`bot.score`	`number`	Puntuación numérica de bot.
`bot.signal`	`string[]`	Señales que contribuyeron a la detección de bot.
`root_apps`	`boolean`	El dispositivo tiene aplicaciones root/superusuario instaladas.
`emulator`	`boolean`	El dispositivo es un emulador.
`proxy`	`boolean`	El visitante está usando un proxy.
`proxy_confidence`	`string`	Nivel de confianza: `"low"`, `"medium"` o `"high"`.
`vpn`	`boolean`	El visitante está usando una VPN.
`vpn_confidence`	`string`	Nivel de confianza: `"low"`, `"medium"` o `"high"`.
`incognito`	`boolean`	El navegador está en modo incógnito/privado.
`tampering`	`boolean`	Los atributos del navegador han sido manipulados.
`jailbroken`	`boolean`	El dispositivo tiene jailbreak.
`frida`	`boolean`	Se detectó el toolkit de instrumentación Frida.
`virtual_machine`	`boolean`	El visitante está ejecutando en una máquina virtual.
`developer_tools`	`boolean`	Las herramientas de desarrollo del navegador están abiertas.
`mitm_attack`	`boolean`	Se detectó un ataque man-in-the-middle.
`replayed`	`boolean`	La solicitud es una repetición de una solicitud anterior.
`high_activity_device`	`boolean`	Número inusualmente alto de identificaciones desde este dispositivo.
`throwawayEmail`	`boolean`	`true` cuando el identificador `email` enviado es una dirección de correo electrónico desechable o temporal.

`raw_device_attributes`

Componentes de bajo nivel del fingerprint del navegador.

Campo	Tipo	Descripción
`math`	`string`	Hash de la salida del motor matemático.
`vendor`	`string`	Cadena del proveedor de GPU/gráficos.

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