Guida rapida

Questa guida illustra l'integrazione di TRACIO nella sua applicazione. Installerà l'SDK client, lo inizializzerà con la sua chiave pubblica e leggerà il primo risultato di identificazione del visitatore.

Passo 1: installare l'SDK

Installi l'SDK TRACIO utilizzando il gestore di pacchetti preferito:

npm install @tracio/sdk

Oppure con pnpm:

pnpm add @tracio/sdk

Oppure con yarn:

yarn add @tracio/sdk

Snippet CDN senza build

Se non utilizza un bundler, inserisca il tag script edge nella sua pagina. Si auto-inizializza con la chiave pubblica nel parametro di query k:

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

Passo 2: inizializzare l'SDK

Importi Tracio e chiami Tracio.init() con la sua chiave pubblica. Questo restituisce immediatamente un TracioInstance — l'agente sottostante viene caricato in background.

import { Tracio } from "@tracio/sdk"

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

La sua chiave pubblica può essere distribuita in sicurezza nel codice lato client. La trova nella dashboard, sotto API Keys.

Opzioni di configurazione

Tracio.init() accetta un oggetto TracioConfig:

Passo 3: ottenere un ID visitatore

Chiami tracio.getVisitorId() per ricevere un identificatore stabile del visitatore. È un'operazione asincrona.

const visitorId = await tracio.getVisitorId()

console.log(visitorId) // "X7fh2Hg9LkMn3pQr"

Passo 4: leggere il risultato completo

Chiami tracio.getResult() per ricevere il risultato completo dell'identificazione, incluso il rilevamento dei bot.

const result = await tracio.getResult()

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

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

Il risultato ha la forma:

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

Passo 5: ciclo di vita ed errori

Utilizzi i callback del ciclo di vita per reagire quando l'agente è pronto o quando qualcosa fallisce, e destroy() per smontare l'istanza:

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

// più tardi, quando non ne ha più bisogno
tracio.destroy()

Consulti Gestione degli errori per l'elenco completo dei codici di errore e degli helper di retry.

Pattern di integrazione comuni

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

Prevenzione delle frodi nei pagamenti

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

Prossimi passi

• Come funziona — Comprenda la pipeline di raccolta dei segnali e di identificazione
• Riferimento SDK JavaScript — Documentazione completa dell'API SDK
• Webhook — Riceva gli eventi di identificazione sul suo server in tempo reale
• Rilevamento dei bot — Approfondimento sul rilevamento dell'automazione