SDK JavaScript

O SDK JavaScript da TRACIO (@tracio/sdk) coleta sinais de navegador e os envia para a nuvem da TRACIO para identificação de visitantes e detecção de bots. Ele é leve, não bloqueante e compatível com todos os navegadores modernos.

Instalação

bash

npm install @tracio/sdk

O pacote inclui builds ESM, CJS e IIFE com tipos TypeScript completos.

CDN

Existem duas maneiras de usar a TRACIO a partir de um CDN sem um bundler.

Script de edge (auto-init)

O script de edge se autoinicializa usando a chave pública no parâmetro de consulta k. Nenhum JavaScript é necessário:

HTML

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

Bundle npm (global IIFE)

Você também pode carregar o bundle npm publicado a partir do unpkg ou jsDelivr. Ele expõe um global TracioSDK. Fixe uma versão:

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>

Inicialização

Tracio.init(config)

Inicializa o SDK e retorna uma TracioInstance de forma síncrona. O agente carrega em segundo plano; os métodos da instância resolvem assim que ele estiver pronto.

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
}

Opção	Tipo	Padrão	Descrição
`publicKey`	`string`	obrigatório	Sua chave pública. Copie-a do seu dashboard.
`region`	`"us" \| "eu"`	nenhum	Região de dados opcional. Quando não definida, o SDK usa o endpoint genérico `https://edge.tracio.ai` (sem residência de dados nos EUA implícita). Defina explicitamente para fixar `us` ou `eu`.
`endpoint`	`string`	auto	Endpoint de API personalizado (para um endpoint com proxy de origem própria).
`scriptUrl`	`string`	auto	URL personalizada para o script do agente (para um endpoint com proxy de origem própria).
`linkedId`	`string`	nenhum	Identificador que vincula este visitante a uma entidade no seu sistema.
`tag`	`string`	nenhum	Rótulo de formato livre anexado à requisição para filtragem posterior.
`debug`	`boolean`	`false`	Registra diagnósticos detalhados no console.
`timeoutMs`	`number`	`15000`	Quanto tempo esperar pelo resultado antes de expirar.

Chamar Tracio.init() mais de uma vez com uma chave pública diferente lança um erro multiple_keys.

Identificação

tracio.getVisitorId()

Retorna uma Promise<string> que resolve para o identificador de visitante estável.

TypeScript

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

tracio.getResult()

Retorna uma Promise<TracioResult> com o ID de visitante e o resultado da detecção 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 de ciclo de vida

tracio.onReady(cb)

Invocado assim que o agente carrega e produz um resultado.

TypeScript

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

tracio.onError(cb)

Invocado quando o SDK encontra um erro.

TypeScript

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

tracio.destroy()

Desmonta a instância e libera recursos. Chamadas subsequentes são rejeitadas com um erro destroyed.

TypeScript

tracio.destroy()

Tratamento de erros

O SDK lança instâncias de TracioError com um code tipado. Use os helpers isTracioError e isRetryableError para ramificar:

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 erro

A união TracioErrorCode cobre:

Código	Descrição
`blocked`	A requisição foi bloqueada (ex.: por um bloqueador de anúncios).
`destroyed`	A instância foi destruída antes de a chamada concluir.
`invalid_config`	A configuração é inválida (ex.: `publicKey` ausente).
`load_failed`	O script do agente falhou ao carregar.
`multiple_keys`	`Tracio.init()` foi chamado com uma chave pública conflitante.
`network`	Uma requisição de rede falhou.
`non_browser`	O SDK foi usado fora de um ambiente de navegador.
`script_error`	O script do agente lançou um erro em tempo de execução.
`server`	O servidor retornou um erro.
`timeout`	A requisição excedeu `timeoutMs`.

load_failed, blocked, script_error, network, timeout e server são passíveis de nova tentativa; isRetryableError(error) retorna true para eles.

Integração com frameworks

Para React, Vue, Angular e Svelte, use os pacotes de framework dedicados em vez de conectar o SDK principal manualmente:

Cada um encapsula @tracio/sdk e expõe primitivas idiomáticas (providers, plugins, hooks, composables e services). Consulte a visão geral dos SDKs para snippets por framework.

Considerações de desempenho

Não bloqueante: Tracio.init() retorna de forma síncrona e carrega o agente em segundo plano. Não bloqueia a renderização da página.
Requisição única: uma requisição é feita por identificação.
Timeout: a identificação é limitada por timeoutMs (padrão 15000ms), então uma rede lenta nunca trava seu código indefinidamente.

SDK JavaScript

Instalação

bash

npm install @tracio/sdk

O pacote inclui builds ESM, CJS e IIFE com tipos TypeScript completos.

CDN

Existem duas maneiras de usar a TRACIO a partir de um CDN sem um bundler.

Script de edge (auto-init)

O script de edge se autoinicializa usando a chave pública no parâmetro de consulta k. Nenhum JavaScript é necessário:

HTML

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

Bundle npm (global IIFE)

Você também pode carregar o bundle npm publicado a partir do unpkg ou jsDelivr. Ele expõe um global TracioSDK. Fixe uma versão:

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>

Inicialização

Tracio.init(config)

Inicializa o SDK e retorna uma TracioInstance de forma síncrona. O agente carrega em segundo plano; os métodos da instância resolvem assim que ele estiver pronto.

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
}

Opção	Tipo	Padrão	Descrição
`publicKey`	`string`	obrigatório	Sua chave pública. Copie-a do seu dashboard.
`region`	`"us" \| "eu"`	nenhum	Região de dados opcional. Quando não definida, o SDK usa o endpoint genérico `https://edge.tracio.ai` (sem residência de dados nos EUA implícita). Defina explicitamente para fixar `us` ou `eu`.
`endpoint`	`string`	auto	Endpoint de API personalizado (para um endpoint com proxy de origem própria).
`scriptUrl`	`string`	auto	URL personalizada para o script do agente (para um endpoint com proxy de origem própria).
`linkedId`	`string`	nenhum	Identificador que vincula este visitante a uma entidade no seu sistema.
`tag`	`string`	nenhum	Rótulo de formato livre anexado à requisição para filtragem posterior.
`debug`	`boolean`	`false`	Registra diagnósticos detalhados no console.
`timeoutMs`	`number`	`15000`	Quanto tempo esperar pelo resultado antes de expirar.

Chamar Tracio.init() mais de uma vez com uma chave pública diferente lança um erro multiple_keys.

Identificação

tracio.getVisitorId()

Retorna uma Promise<string> que resolve para o identificador de visitante estável.

TypeScript

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

tracio.getResult()

Retorna uma Promise<TracioResult> com o ID de visitante e o resultado da detecção 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 de ciclo de vida

tracio.onReady(cb)

Invocado assim que o agente carrega e produz um resultado.

TypeScript

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

tracio.onError(cb)

Invocado quando o SDK encontra um erro.

TypeScript

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

tracio.destroy()

Desmonta a instância e libera recursos. Chamadas subsequentes são rejeitadas com um erro destroyed.

TypeScript

tracio.destroy()

Tratamento de erros

O SDK lança instâncias de TracioError com um code tipado. Use os helpers isTracioError e isRetryableError para ramificar:

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 erro

A união TracioErrorCode cobre:

Código	Descrição
`blocked`	A requisição foi bloqueada (ex.: por um bloqueador de anúncios).
`destroyed`	A instância foi destruída antes de a chamada concluir.
`invalid_config`	A configuração é inválida (ex.: `publicKey` ausente).
`load_failed`	O script do agente falhou ao carregar.
`multiple_keys`	`Tracio.init()` foi chamado com uma chave pública conflitante.
`network`	Uma requisição de rede falhou.
`non_browser`	O SDK foi usado fora de um ambiente de navegador.
`script_error`	O script do agente lançou um erro em tempo de execução.
`server`	O servidor retornou um erro.
`timeout`	A requisição excedeu `timeoutMs`.

load_failed, blocked, script_error, network, timeout e server são passíveis de nova tentativa; isRetryableError(error) retorna true para eles.

Integração com frameworks

Para React, Vue, Angular e Svelte, use os pacotes de framework dedicados em vez de conectar o SDK principal manualmente:

Cada um encapsula @tracio/sdk e expõe primitivas idiomáticas (providers, plugins, hooks, composables e services). Consulte a visão geral dos SDKs para snippets por framework.

Considerações de desempenho

Não bloqueante: Tracio.init() retorna de forma síncrona e carrega o agente em segundo plano. Não bloqueia a renderização da página.
Requisição única: uma requisição é feita por identificação.
Timeout: a identificação é limitada por timeoutMs (padrão 15000ms), então uma rede lenta nunca trava seu código indefinidamente.