SDK de JavaScript

El SDK de JavaScript de TRACIO (@tracio/sdk) recopila señales del navegador y las envía a la nube de TRACIO para la identificación de visitantes y la detección de bots. Es ligero, no bloqueante y compatible con todos los navegadores modernos.

Instalación

bash

npm install @tracio/sdk

El paquete incluye builds ESM, CJS e IIFE con tipos completos de TypeScript.

CDN

Hay dos formas de usar TRACIO desde una CDN sin un bundler.

Script del edge (autoinicialización)

El script del edge se autoinicializa usando la clave pública en el parámetro de consulta k. No requiere JavaScript:

HTML

<script src="https://edge.tracio.ai/s.js?k=PUBLIC_KEY" async></script>

Bundle de npm (global IIFE)

También puede cargar el bundle de npm publicado desde unpkg o jsDelivr. Expone un global TracioSDK. Fije una versión:

HTML

<script src="https://unpkg.com/@tracio/sdk@0.1.3/dist/index.min.js"></script>
<script>
  const tracio = TracioSDK.Tracio.init({ publicKey: "5ca175fc..." })
</script>

Inicialización

Tracio.init(config)

Inicializa el SDK y devuelve una TracioInstance de forma síncrona. El agente se carga en segundo plano; los métodos de la instancia se resuelven una vez que está listo.

TypeScript

import { Tracio } from "@tracio/sdk"

const tracio = Tracio.init({
  publicKey: "5ca175fc...",
})

TracioConfig

TypeScript

interface TracioConfig {
  publicKey: string // required
  region?: "us" | "eu"
  endpoint?: string
  scriptUrl?: string
  linkedId?: string
  tag?: string
  debug?: boolean
  timeoutMs?: number // default 15000
}

Opción	Tipo	Por defecto	Descripción
`publicKey`	`string`	obligatorio	Su clave pública. Cópiela desde su panel.
`region`	`"us" \| "eu"`	ninguno	Región de datos opcional. Cuando no se define, el SDK usa el endpoint genérico `https://edge.tracio.ai` (sin residencia de datos en EE. UU. implícita). Defínala de forma explícita para fijar `us` o `eu`.
`endpoint`	`string`	auto	Endpoint de API personalizado (para un endpoint con proxy de origen).
`scriptUrl`	`string`	auto	URL personalizada para el script del agente (para un endpoint con proxy de origen).
`linkedId`	`string`	ninguno	Identificador que vincula a este visitante con una entidad de su sistema.
`tag`	`string`	ninguno	Etiqueta de formato libre adjunta a la solicitud para filtrar más adelante.
`debug`	`boolean`	`false`	Registra diagnósticos detallados en la consola.
`timeoutMs`	`number`	`15000`	Cuánto tiempo esperar el resultado antes de agotar el tiempo de espera.

Llamar a Tracio.init() más de una vez con una clave pública diferente lanza un error multiple_keys.

Identificación

tracio.getVisitorId()

Devuelve una Promise<string> que se resuelve al identificador de visitante estable.

TypeScript

const visitorId = await tracio.getVisitorId()
// "X7fh2Hg9LkMn3pQr"

tracio.getResult()

Devuelve una Promise<TracioResult> con el ID de visitante y el resultado de la detección de bots.

TypeScript

const result = await tracio.getResult()

console.log(result.visitorId)

if (result.bot.detected) {
  console.warn("bot, confidence:", result.bot.confidence)
}

TracioResult

TypeScript

interface TracioResult {
  visitorId: string
  bot: {
    detected: boolean
    confidence: number // 0-100
    reasons?: string[]
  }
}

Callbacks del ciclo de vida

tracio.onReady(cb)

Se invoca una vez que el agente ha cargado y ha producido un resultado.

TypeScript

tracio.onReady((result) => {
  console.log("ready:", result.visitorId)
})

tracio.onError(cb)

Se invoca cuando el SDK encuentra un error.

TypeScript

tracio.onError((error) => {
  console.error("tracio error:", error.code, error.message)
})

tracio.destroy()

Desmonta la instancia y libera los recursos. Las llamadas posteriores se rechazan con un error destroyed.

TypeScript

tracio.destroy()

Gestión de errores

El SDK lanza instancias de TracioError con un code tipado. Use los helpers isTracioError e isRetryableError para bifurcar:

TypeScript

import { Tracio, isTracioError, isRetryableError } from "@tracio/sdk"

const tracio = Tracio.init({ publicKey: "5ca175fc..." })

try {
  const result = await tracio.getResult()
} catch (error) {
  if (isTracioError(error)) {
    if (isRetryableError(error)) {
      // load_failed / blocked / script_error / network / timeout / server — safe to retry
    }
    console.error("TRACIO error:", error.code, error.message)
  } else {
    console.error("Unexpected error:", error)
  }
}

Códigos de error

La unión TracioErrorCode cubre:

Código	Descripción
`blocked`	La solicitud fue bloqueada (p. ej., por un bloqueador de anuncios).
`destroyed`	La instancia se destruyó antes de que se completara la llamada.
`invalid_config`	La configuración no es válida (p. ej., falta `publicKey`).
`load_failed`	El script del agente no se pudo cargar.
`multiple_keys`	Se llamó a `Tracio.init()` con una clave pública en conflicto.
`network`	Una solicitud de red falló.
`non_browser`	El SDK se usó fuera de un entorno de navegador.
`script_error`	El script del agente lanzó un error en tiempo de ejecución.
`server`	El servidor devolvió un error.
`timeout`	La solicitud superó `timeoutMs`.

load_failed, blocked, script_error, network, timeout y server admiten reintento; isRetryableError(error) devuelve true para ellos.

Integración con frameworks

Para React, Vue, Angular y Svelte, use los paquetes dedicados de cada framework en lugar de conectar el SDK base a mano:

Cada uno envuelve @tracio/sdk y expone primitivas idiomáticas (providers, plugins, hooks, composables y servicios). Consulte la visión general de los SDKs para ver snippets por framework.

Consideraciones de rendimiento

No bloqueante: Tracio.init() devuelve de forma síncrona y carga el agente en segundo plano. No bloquea el renderizado de la página.
Solicitud única: se realiza una solicitud por identificación.
Tiempo de espera: la identificación está acotada por timeoutMs (por defecto 15000ms), de modo que una red lenta nunca deja su código colgado indefinidamente.

SDK de JavaScript

Instalación

bash

npm install @tracio/sdk

El paquete incluye builds ESM, CJS e IIFE con tipos completos de TypeScript.

CDN

Hay dos formas de usar TRACIO desde una CDN sin un bundler.

Script del edge (autoinicialización)

El script del edge se autoinicializa usando la clave pública en el parámetro de consulta k. No requiere JavaScript:

HTML

<script src="https://edge.tracio.ai/s.js?k=PUBLIC_KEY" async></script>

Bundle de npm (global IIFE)

También puede cargar el bundle de npm publicado desde unpkg o jsDelivr. Expone un global TracioSDK. Fije una versión:

HTML

<script src="https://unpkg.com/@tracio/sdk@0.1.3/dist/index.min.js"></script>
<script>
  const tracio = TracioSDK.Tracio.init({ publicKey: "5ca175fc..." })
</script>

Inicialización

Tracio.init(config)

Inicializa el SDK y devuelve una TracioInstance de forma síncrona. El agente se carga en segundo plano; los métodos de la instancia se resuelven una vez que está listo.

TypeScript

import { Tracio } from "@tracio/sdk"

const tracio = Tracio.init({
  publicKey: "5ca175fc...",
})

TracioConfig

TypeScript

interface TracioConfig {
  publicKey: string // required
  region?: "us" | "eu"
  endpoint?: string
  scriptUrl?: string
  linkedId?: string
  tag?: string
  debug?: boolean
  timeoutMs?: number // default 15000
}

Opción	Tipo	Por defecto	Descripción
`publicKey`	`string`	obligatorio	Su clave pública. Cópiela desde su panel.
`region`	`"us" \| "eu"`	ninguno	Región de datos opcional. Cuando no se define, el SDK usa el endpoint genérico `https://edge.tracio.ai` (sin residencia de datos en EE. UU. implícita). Defínala de forma explícita para fijar `us` o `eu`.
`endpoint`	`string`	auto	Endpoint de API personalizado (para un endpoint con proxy de origen).
`scriptUrl`	`string`	auto	URL personalizada para el script del agente (para un endpoint con proxy de origen).
`linkedId`	`string`	ninguno	Identificador que vincula a este visitante con una entidad de su sistema.
`tag`	`string`	ninguno	Etiqueta de formato libre adjunta a la solicitud para filtrar más adelante.
`debug`	`boolean`	`false`	Registra diagnósticos detallados en la consola.
`timeoutMs`	`number`	`15000`	Cuánto tiempo esperar el resultado antes de agotar el tiempo de espera.

Llamar a Tracio.init() más de una vez con una clave pública diferente lanza un error multiple_keys.

Identificación

tracio.getVisitorId()

Devuelve una Promise<string> que se resuelve al identificador de visitante estable.

TypeScript

const visitorId = await tracio.getVisitorId()
// "X7fh2Hg9LkMn3pQr"

tracio.getResult()

Devuelve una Promise<TracioResult> con el ID de visitante y el resultado de la detección de bots.

TypeScript

const result = await tracio.getResult()

console.log(result.visitorId)

if (result.bot.detected) {
  console.warn("bot, confidence:", result.bot.confidence)
}

TracioResult

TypeScript

interface TracioResult {
  visitorId: string
  bot: {
    detected: boolean
    confidence: number // 0-100
    reasons?: string[]
  }
}

Callbacks del ciclo de vida

tracio.onReady(cb)

Se invoca una vez que el agente ha cargado y ha producido un resultado.

TypeScript

tracio.onReady((result) => {
  console.log("ready:", result.visitorId)
})

tracio.onError(cb)

Se invoca cuando el SDK encuentra un error.

TypeScript

tracio.onError((error) => {
  console.error("tracio error:", error.code, error.message)
})

tracio.destroy()

Desmonta la instancia y libera los recursos. Las llamadas posteriores se rechazan con un error destroyed.

TypeScript

tracio.destroy()

Gestión de errores

El SDK lanza instancias de TracioError con un code tipado. Use los helpers isTracioError e isRetryableError para bifurcar:

TypeScript

import { Tracio, isTracioError, isRetryableError } from "@tracio/sdk"

const tracio = Tracio.init({ publicKey: "5ca175fc..." })

try {
  const result = await tracio.getResult()
} catch (error) {
  if (isTracioError(error)) {
    if (isRetryableError(error)) {
      // load_failed / blocked / script_error / network / timeout / server — safe to retry
    }
    console.error("TRACIO error:", error.code, error.message)
  } else {
    console.error("Unexpected error:", error)
  }
}

Códigos de error

La unión TracioErrorCode cubre:

Código	Descripción
`blocked`	La solicitud fue bloqueada (p. ej., por un bloqueador de anuncios).
`destroyed`	La instancia se destruyó antes de que se completara la llamada.
`invalid_config`	La configuración no es válida (p. ej., falta `publicKey`).
`load_failed`	El script del agente no se pudo cargar.
`multiple_keys`	Se llamó a `Tracio.init()` con una clave pública en conflicto.
`network`	Una solicitud de red falló.
`non_browser`	El SDK se usó fuera de un entorno de navegador.
`script_error`	El script del agente lanzó un error en tiempo de ejecución.
`server`	El servidor devolvió un error.
`timeout`	La solicitud superó `timeoutMs`.

load_failed, blocked, script_error, network, timeout y server admiten reintento; isRetryableError(error) devuelve true para ellos.

Integración con frameworks

Para React, Vue, Angular y Svelte, use los paquetes dedicados de cada framework en lugar de conectar el SDK base a mano:

Cada uno envuelve @tracio/sdk y expone primitivas idiomáticas (providers, plugins, hooks, composables y servicios). Consulte la visión general de los SDKs para ver snippets por framework.

Consideraciones de rendimiento

No bloqueante: Tracio.init() devuelve de forma síncrona y carga el agente en segundo plano. No bloquea el renderizado de la página.
Solicitud única: se realiza una solicitud por identificación.
Tiempo de espera: la identificación está acotada por timeoutMs (por defecto 15000ms), de modo que una red lenta nunca deja su código colgado indefinidamente.