Szybki start

Ten przewodnik przeprowadzi Cię przez integrację TRACIO z Twoją aplikacją. Zainstalujesz kliencki SDK, zainicjujesz go swoim kluczem publicznym i odczytasz pierwszy wynik identyfikacji odwiedzającego.

Krok 1: Instalacja SDK

Zainstaluj SDK TRACIO przy użyciu preferowanego menedżera pakietów:

npm install @tracio/sdk

Lub za pomocą pnpm:

pnpm add @tracio/sdk

Lub za pomocą yarn:

yarn add @tracio/sdk

Snippet CDN bez procesu budowania

Jeśli nie używasz bundlera, wstaw znacznik edge script na swoją stronę. Inicjalizuje się automatycznie kluczem publicznym przekazanym w parametrze zapytania k.

Wybierz, skąd ładuje się skrypt. Niektóre sieci i rozszerzenia przeglądarek blokują żądania do domen analityki firm trzecich: filtry korporacyjne, blokery na poziomie DNS, ograniczenia regionalne, rozszerzenia prywatności. Serwowany z Twojej własnej subdomeny skrypt jest żądaniem first-party w Twojej witrynie i działa dalej w takich środowiskach — zobacz Własne domeny:

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

Albo załaduj go ze współdzielonej domeny edge — to najszybszy sposób, aby zacząć:

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

Krok 2: Inicjalizacja SDK

Zaimportuj Tracio i wywołaj Tracio.init() ze swoim kluczem publicznym. Zwraca to natychmiast TracioInstance — bazowy agent ładuje się w tle.

import { Tracio } from "@tracio/sdk"

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

Twój klucz publiczny można bezpiecznie umieścić w kodzie po stronie klienta. Znajdziesz go w panelu w sekcji API Keys.

Opcje konfiguracji

Tracio.init() przyjmuje obiekt TracioConfig:

Krok 3: Uzyskanie identyfikatora odwiedzającego

Wywołaj tracio.getVisitorId(), aby otrzymać stabilny identyfikator odwiedzającego. Jest to operacja asynchroniczna.

const visitorId = await tracio.getVisitorId()

console.log(visitorId) // "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

Krok 4: Odczyt pełnego wyniku

Wywołaj tracio.getResult(), aby otrzymać pełny wynik identyfikacji, wraz z wykrywaniem botów.

const result = await tracio.getResult()

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

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

Wynik ma postać:

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

Krok 5: Cykl życia i błędy

Wykorzystaj callbacki cyklu życia, aby zareagować, gdy agent jest gotowy lub gdy coś zawiedzie, oraz destroy(), aby zniszczyć instancję:

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

Zobacz Obsługa błędów, aby zapoznać się z pełną listą kodów błędów i pomocnikami do ponawiania.

Typowe wzorce integracji

Ochrona logowania

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

Zapobieganie oszustwom płatniczym

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

Następne kroki

• Jak to działa — Zrozum proces zbierania sygnałów i pipeline identyfikacji
• Dokumentacja SDK JavaScript — Pełna dokumentacja API SDK
• Webhooks — Odbieraj zdarzenia identyfikacji na swoim serwerze w czasie rzeczywistym
• Data API — Odczytuj odwiedzających, sesje i velocity ze swojego backendu
• Wykrywanie botów — Szczegółowe omówienie wykrywania automatyzacji