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

Genere un token de identificación

Una vez que el script se haya cargado, una función global estará disponible. Llámela con un identificador de cliente (por ejemplo, un clientId o userId) para generar un token.

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

Parámetros

Parámetro	Tipo	Descripción
`clientId`	`string`	Un identificador único para el usuario o la sesión, como un `clientId` o `userId`.

Valor de retorno

La función devuelve un objeto token:

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

Envíe el token a su backend

Pase el token devuelto a su backend para la verificación del lado del servidor. La URL de su endpoint de backend se proporcionará después del despliegue.

URL provisional

Reemplace la URL a continuación con su endpoint de backend real una vez que haya sido aprovisionado.

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

Ejemplo de solicitud

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

Cuerpo de la solicitud

Campo	Tipo	Descripción
`token`	`string`	El token devuelto por la llamada a `submitFingerprint` del lado del cliente.

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

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 booleanas y de cadena que indican atributos sospechosos o notables del visitante.

Campo	Tipo	Descripción
`bot`	`string`	Resultado de detección de bots. `"not_detected"` cuando no se encuentra ningún 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.

`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": "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."
  }
}