Inicio rápido

Esta guía le lleva paso a paso por la integración de TRACIO en su aplicación. Instalará el SDK de cliente, lo inicializará con su clave pública y leerá su primer resultado de identificación de visitante.

Paso 1: instale el SDK

Instale el SDK de TRACIO con su gestor de paquetes preferido:

npm install @tracio/sdk

O con pnpm:

pnpm add @tracio/sdk

O con yarn:

yarn add @tracio/sdk

Snippet de CDN sin build

Si no usa un bundler, coloque la etiqueta de script del edge en su página. Se autoinicializa con la clave pública en el parámetro de consulta k.

Elija desde dónde se carga el script. Algunas redes y extensiones de navegador bloquean las solicitudes a dominios de analítica de terceros: filtros corporativos, bloqueadores a nivel de DNS, restricciones regionales, extensiones de privacidad. Servido desde su propio subdominio, el script es una solicitud de origen (first-party) en su sitio y sigue funcionando en esos entornos; consulte Dominios personalizados:

<script src="https://metrics.yoursite.com/s.js?k=PUBLIC_KEY" async></script>

O cárguelo desde el dominio edge compartido, la forma más rápida de empezar:

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

Paso 2: inicializa el SDK

Importe Tracio y llame a Tracio.init() con su clave pública. Esto devuelve una TracioInstance de inmediato; el agente subyacente se carga en segundo plano.

import { Tracio } from "@tracio/sdk"

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

Su clave pública puede incluirse sin problema en el código del lado del cliente. La encontrará en su panel, en la sección API Keys.

Opciones de configuración

Tracio.init() acepta un objeto TracioConfig:

Paso 3: obtenga un ID de visitante

Llame a tracio.getVisitorId() para recibir un identificador de visitante estable. Es una operación asíncrona.

const visitorId = await tracio.getVisitorId()

console.log(visitorId) // "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

Paso 4: lea el resultado completo

Llame a tracio.getResult() para recibir el resultado de identificación completo, incluida la detección de bots.

const result = await tracio.getResult()

console.log(result.visitorId) // "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

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

El resultado tiene la forma:

{
  visitorId: "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  bot: {
    detected: false,
    confidence: 2,        // 0-100
    reasons: [],
  },
}

Paso 5: ciclo de vida y errores

Use los callbacks del ciclo de vida para reaccionar cuando el agente esté listo o cuando algo falle, y destroy() para desmontar la instancia:

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

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

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

// later, when you no longer need it
tracio.destroy()

Consulte Gestión de errores para ver la lista completa de códigos de error y los helpers de reintento.

Patrones de integración habituales

Protección del inicio de sesión

import { Tracio } from "@tracio/sdk"

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

async function handleLogin(email: string, password: string) {
  const visitorId = await tracio.getVisitorId()

  const response = await fetch("/api/login", {
    method: "POST",
    body: JSON.stringify({ email, password, visitorId }),
  })

  return response.json()
}

Prevención del fraude en pagos

import { Tracio } from "@tracio/sdk"

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

async function processPayment(paymentData: PaymentData) {
  const result = await tracio.getResult()

  if (result.bot.detected) {
    throw new Error("Automated client detected")
  }

  const response = await fetch("/api/payment", {
    method: "POST",
    body: JSON.stringify({ ...paymentData, visitorId: result.visitorId }),
  })

  return response.json()
}

Próximos pasos

• Cómo funciona — Comprenda el pipeline de recopilación de señales e identificación
• Referencia del SDK de JavaScript — Documentación completa de la API del SDK
• Webhooks — Reciba eventos de identificación en su servidor en tiempo real
• Data API — Lea visitantes, sesiones y velocity desde su backend
• Detección de bots — Análisis a fondo de la detección de automatización