Pornire rapidă

Acest ghid te conduce prin integrarea TRACIO în aplicația ta. Vei instala SDK-ul client, îl vei inițializa cu cheia publică și vei citi primul rezultat de identificare a vizitatorului.

Pasul 1: Instalează SDK-ul

Instalează SDK-ul TRACIO folosind managerul de pachete preferat:

npm install @tracio/sdk

Sau cu pnpm:

pnpm add @tracio/sdk

Sau cu yarn:

yarn add @tracio/sdk

Snippet CDN fără build

Dacă nu folosești un bundler, adaugă tag-ul de script edge în pagina ta. Acesta se inițializează automat cu cheia publică din parametrul de interogare k.

Alege de unde se încarcă scriptul. Unele rețele și extensii de browser blochează cererile către domenii de analiză terțe: filtre corporative, blocare la nivel de DNS, restricții regionale, extensii de confidențialitate. Servit de pe propriul subdomeniu, scriptul este o cerere first-party pe site și continuă să funcționeze în astfel de medii — consultă Domenii personalizate:

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

Sau încarcă-l de pe domeniul edge partajat, cea mai rapidă cale de a începe:

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

Pasul 2: Inițializează SDK-ul

Importă Tracio și apelează Tracio.init() cu cheia ta publică. Aceasta returnează imediat o TracioInstance — agentul subiacent se încarcă în fundal.

import { Tracio } from "@tracio/sdk"

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

Cheia ta publică poate fi livrată fără riscuri în codul client-side. O găsești în dashboard, la secțiunea API Keys.

Opțiuni de configurare

Tracio.init() acceptă un obiect TracioConfig:

Pasul 3: Obține un ID de vizitator

Apelează tracio.getVisitorId() pentru a primi un identificator stabil de vizitator. Aceasta este o operațiune asincronă.

const visitorId = await tracio.getVisitorId()

console.log(visitorId) // "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

Pasul 4: Citește rezultatul complet

Apelează tracio.getResult() pentru a primi rezultatul complet de identificare, inclusiv detectarea boților.

const result = await tracio.getResult()

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

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

Rezultatul are forma:

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

Pasul 5: Ciclu de viață și erori

Folosește callback-urile de ciclu de viață pentru a reacționa atunci când agentul este gata sau când ceva eșuează, și destroy() pentru a demonta instanța:

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

Consultă Gestionarea erorilor pentru lista completă a codurilor de eroare și a helper-elor de reîncercare.

Modele de integrare frecvente

Protecția autentificării

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

Prevenirea fraudei la plăți

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

Pași următori

• Cum funcționează — Înțelege colectarea semnalelor și pipeline-ul de identificare
• Referință SDK JavaScript — Documentația completă a API-ului SDK
• Webhooks — Primește evenimente de identificare pe serverul tău în timp real
• Data API — Citește vizitatori, sesiuni și velocity din backendul tău
• Detectarea boților — Analiză detaliată a detectării automatizării