Quick Start

Este guia orienta você na integração do TRACIO à sua aplicação. Você vai instalar o SDK cliente, inicializá-lo com sua chave pública e ler o seu primeiro resultado de identificação de visitante.

Passo 1: instale o SDK

Instale o SDK do TRACIO usando o seu gerenciador de pacotes preferido:

npm install @tracio/sdk

Ou com pnpm:

pnpm add @tracio/sdk

Ou com yarn:

yarn add @tracio/sdk

Snippet de CDN sem build

Se você não usa um bundler, insira a tag de script edge na sua página. Ela se autoinicializa com a chave pública no parâmetro de query k:

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

Passo 2: inicialize o SDK

Importe Tracio e chame Tracio.init() com sua chave pública. Isso retorna uma TracioInstance imediatamente — o agente subjacente carrega em segundo plano.

import { Tracio } from "@tracio/sdk"

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

Sua chave pública pode ser enviada com segurança no código do lado do cliente. Você a encontra no seu dashboard, em API Keys.

Opções de configuração

Tracio.init() aceita um objeto TracioConfig:

Passo 3: obtenha um ID de visitante

Chame tracio.getVisitorId() para receber um identificador estável de visitante. Esta é uma operação assíncrona.

const visitorId = await tracio.getVisitorId()

console.log(visitorId) // "X7fh2Hg9LkMn3pQr"

Passo 4: leia o resultado completo

Chame tracio.getResult() para receber o resultado completo de identificação, incluindo a detecção de bots.

const result = await tracio.getResult()

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

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

O resultado tem o formato:

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

Passo 5: ciclo de vida e erros

Use os callbacks de ciclo de vida para reagir quando o agente estiver pronto ou quando algo falhar, e destroy() para desmontar a instância:

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 Error Handling para a lista completa de códigos de erro e helpers de retry.

Padrões comuns de integração

Proteção de login

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

Prevenção de fraudes em pagamentos

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 passos

• How It Works — Entenda o pipeline de coleta de sinais e identificação
• JavaScript SDK Reference — Documentação completa da API do SDK
• Webhooks — Receba eventos de identificação no seu servidor em tempo real
• Bot Detection — Mergulho profundo na detecção de automação