JavaScript SDK

TRACIO JavaScript SDK (@tracio/sdk) zbiera sygnały z przeglądarki i wysyła je do chmury TRACIO w celu identyfikacji odwiedzających i wykrywania botów. Jest lekki, nieblokujący i kompatybilny ze wszystkimi nowoczesnymi przeglądarkami.

Instalacja

bash

npm install @tracio/sdk

Pakiet dostarcza buildy ESM, CJS i IIFE z pełnymi typami TypeScript.

CDN

Istnieją dwa sposoby korzystania z TRACIO przez CDN bez bundlera.

Skrypt edge (auto-init)

Skrypt edge inicjalizuje się automatycznie, używając klucza publicznego w parametrze zapytania k. Nie jest wymagany żaden JavaScript:

HTML

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

Bundle npm (globalny IIFE)

Możesz również załadować opublikowany bundle npm z unpkg lub jsDelivr. Udostępnia on globalną zmienną TracioSDK. Przypnij wersję:

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>

Inicjalizacja

Tracio.init(config)

Inicjalizuje SDK i synchronicznie zwraca TracioInstance. Agent ładuje się w tle; metody instancji rozwiązują się, gdy tylko będzie gotowy.

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
}

Opcja	Typ	Domyślnie	Opis
`publicKey`	`string`	wymagane	Twój klucz publiczny. Skopiuj go z panelu.
`region`	`"us" \| "eu"`	brak	Opcjonalny region danych. Gdy nie jest ustawiony, SDK używa ogólnego punktu końcowego `https://edge.tracio.ai` (bez domyślnej rezydencji danych w USA). Ustaw go jawnie, aby przypiąć `us` lub `eu`.
`endpoint`	`string`	auto	Niestandardowy punkt końcowy API (dla punktu końcowego proxowanego jako first-party).
`scriptUrl`	`string`	auto	Niestandardowy URL skryptu agenta (dla punktu końcowego proxowanego jako first-party).
`linkedId`	`string`	brak	Identyfikator łączący tego odwiedzającego z encją w Twoim systemie.
`tag`	`string`	brak	Dowolna etykieta dołączana do żądania w celu późniejszego filtrowania.
`debug`	`boolean`	`false`	Zapisuje szczegółowe informacje diagnostyczne do konsoli.
`timeoutMs`	`number`	`15000`	Jak długo czekać na wynik przed przekroczeniem limitu czasu.

Wywołanie Tracio.init() więcej niż raz z innym kluczem publicznym rzuca błąd multiple_keys.

Identyfikacja

tracio.getVisitorId()

Zwraca Promise<string>, które rozwiązuje się do stabilnego identyfikatora odwiedzającego.

TypeScript

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

tracio.getResult()

Zwraca Promise<TracioResult> z identyfikatorem odwiedzającego i wynikiem wykrywania botów.

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[]
  }
}

Wywołania zwrotne cyklu życia

tracio.onReady(cb)

Wywoływane, gdy agent zostanie załadowany i wygeneruje wynik.

TypeScript

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

tracio.onError(cb)

Wywoływane, gdy SDK napotka błąd.

TypeScript

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

tracio.destroy()

Niszczy instancję i zwalnia zasoby. Kolejne wywołania są odrzucane z błędem destroyed.

TypeScript

tracio.destroy()

Obsługa błędów

SDK rzuca instancje TracioError z typowanym polem code. Użyj funkcji pomocniczych isTracioError i isRetryableError, aby rozgałęzić logikę:

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

Kody błędów

Unia TracioErrorCode obejmuje:

Kod	Opis
`blocked`	Żądanie zostało zablokowane (np. przez blokadę reklam).
`destroyed`	Instancja została zniszczona przed zakończeniem wywołania.
`invalid_config`	Konfiguracja jest nieprawidłowa (np. brak `publicKey`).
`load_failed`	Skrypt agenta nie mógł się załadować.
`multiple_keys`	`Tracio.init()` wywołano z konfliktowym kluczem publicznym.
`network`	Żądanie sieciowe nie powiodło się.
`non_browser`	SDK użyto poza środowiskiem przeglądarki.
`script_error`	Skrypt agenta zgłosił błąd w czasie działania.
`server`	Serwer zwrócił błąd.
`timeout`	Żądanie przekroczyło `timeoutMs`.

load_failed, blocked, script_error, network, timeout i server można ponawiać; isRetryableError(error) zwraca dla nich true.

Integracja z frameworkami

Dla React, Vue, Angular i Svelte używaj dedykowanych pakietów frameworkowych zamiast ręcznego podłączania rdzenia SDK:

Każdy z nich opakowuje @tracio/sdk i udostępnia idiomatyczne prymitywy (providery, wtyczki, hooki, composables i serwisy). Zobacz przegląd SDK, aby poznać fragmenty kodu dla poszczególnych frameworków.

Kwestie wydajności

Nieblokujący: Tracio.init() zwraca wynik synchronicznie i ładuje agenta w tle. Nie blokuje renderowania strony.
Pojedyncze żądanie: Na jedną identyfikację przypada jedno żądanie.
Limit czasu: Identyfikacja jest ograniczona przez timeoutMs (domyślnie 15000 ms), więc wolna sieć nigdy nie zawiesi Twojego kodu na czas nieokreślony.

JavaScript SDK

Instalacja

bash

npm install @tracio/sdk

Pakiet dostarcza buildy ESM, CJS i IIFE z pełnymi typami TypeScript.

CDN

Istnieją dwa sposoby korzystania z TRACIO przez CDN bez bundlera.

Skrypt edge (auto-init)

Skrypt edge inicjalizuje się automatycznie, używając klucza publicznego w parametrze zapytania k. Nie jest wymagany żaden JavaScript:

HTML

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

Bundle npm (globalny IIFE)

Możesz również załadować opublikowany bundle npm z unpkg lub jsDelivr. Udostępnia on globalną zmienną TracioSDK. Przypnij wersję:

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>

Inicjalizacja

Tracio.init(config)

Inicjalizuje SDK i synchronicznie zwraca TracioInstance. Agent ładuje się w tle; metody instancji rozwiązują się, gdy tylko będzie gotowy.

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
}

Opcja	Typ	Domyślnie	Opis
`publicKey`	`string`	wymagane	Twój klucz publiczny. Skopiuj go z panelu.
`region`	`"us" \| "eu"`	brak	Opcjonalny region danych. Gdy nie jest ustawiony, SDK używa ogólnego punktu końcowego `https://edge.tracio.ai` (bez domyślnej rezydencji danych w USA). Ustaw go jawnie, aby przypiąć `us` lub `eu`.
`endpoint`	`string`	auto	Niestandardowy punkt końcowy API (dla punktu końcowego proxowanego jako first-party).
`scriptUrl`	`string`	auto	Niestandardowy URL skryptu agenta (dla punktu końcowego proxowanego jako first-party).
`linkedId`	`string`	brak	Identyfikator łączący tego odwiedzającego z encją w Twoim systemie.
`tag`	`string`	brak	Dowolna etykieta dołączana do żądania w celu późniejszego filtrowania.
`debug`	`boolean`	`false`	Zapisuje szczegółowe informacje diagnostyczne do konsoli.
`timeoutMs`	`number`	`15000`	Jak długo czekać na wynik przed przekroczeniem limitu czasu.

Wywołanie Tracio.init() więcej niż raz z innym kluczem publicznym rzuca błąd multiple_keys.

Identyfikacja

tracio.getVisitorId()

Zwraca Promise<string>, które rozwiązuje się do stabilnego identyfikatora odwiedzającego.

TypeScript

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

tracio.getResult()

Zwraca Promise<TracioResult> z identyfikatorem odwiedzającego i wynikiem wykrywania botów.

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[]
  }
}

Wywołania zwrotne cyklu życia

tracio.onReady(cb)

Wywoływane, gdy agent zostanie załadowany i wygeneruje wynik.

TypeScript

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

tracio.onError(cb)

Wywoływane, gdy SDK napotka błąd.

TypeScript

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

tracio.destroy()

Niszczy instancję i zwalnia zasoby. Kolejne wywołania są odrzucane z błędem destroyed.

TypeScript

tracio.destroy()

Obsługa błędów

SDK rzuca instancje TracioError z typowanym polem code. Użyj funkcji pomocniczych isTracioError i isRetryableError, aby rozgałęzić logikę:

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

Kody błędów

Unia TracioErrorCode obejmuje:

Kod	Opis
`blocked`	Żądanie zostało zablokowane (np. przez blokadę reklam).
`destroyed`	Instancja została zniszczona przed zakończeniem wywołania.
`invalid_config`	Konfiguracja jest nieprawidłowa (np. brak `publicKey`).
`load_failed`	Skrypt agenta nie mógł się załadować.
`multiple_keys`	`Tracio.init()` wywołano z konfliktowym kluczem publicznym.
`network`	Żądanie sieciowe nie powiodło się.
`non_browser`	SDK użyto poza środowiskiem przeglądarki.
`script_error`	Skrypt agenta zgłosił błąd w czasie działania.
`server`	Serwer zwrócił błąd.
`timeout`	Żądanie przekroczyło `timeoutMs`.

load_failed, blocked, script_error, network, timeout i server można ponawiać; isRetryableError(error) zwraca dla nich true.

Integracja z frameworkami

Dla React, Vue, Angular i Svelte używaj dedykowanych pakietów frameworkowych zamiast ręcznego podłączania rdzenia SDK:

Kwestie wydajności

Nieblokujący: Tracio.init() zwraca wynik synchronicznie i ładuje agenta w tle. Nie blokuje renderowania strony.
Pojedyncze żądanie: Na jedną identyfikację przypada jedno żądanie.
Limit czasu: Identyfikacja jest ograniczona przez timeoutMs (domyślnie 15000 ms), więc wolna sieć nigdy nie zawiesi Twojego kodu na czas nieokreślony.