JavaScript SDK

TRACIO JavaScript SDK (@tracio/sdk) sbírá signály z prohlížeče a odesílá je do cloudu TRACIO za účelem identifikace návštěvníků a detekce botů. Je odlehčené, neblokující a kompatibilní se všemi moderními prohlížeči.

Instalace

bash

npm install @tracio/sdk

Balíček dodává buildy ESM, CJS a IIFE s kompletními TypeScript typy.

CDN

Existují dva způsoby, jak používat TRACIO z CDN bez bundleru.

Edge skript (automatická inicializace)

Edge skript se automaticky inicializuje pomocí veřejného klíče v query parametru k. Není potřeba žádný JavaScript:

HTML

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

npm bundle (globální IIFE)

Publikovaný npm bundle můžete také načíst z unpkg nebo jsDelivr. Zpřístupňuje globální objekt TracioSDK. Zafixujte verzi:

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>

Inicializace

Tracio.init(config)

Inicializuje SDK a synchronně vrací TracioInstance. Agent se načítá na pozadí; metody instance se vyhodnotí, jakmile je připraven.

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
}

Volba	Typ	Výchozí	Popis
`publicKey`	`string`	povinné	Váš veřejný klíč. Zkopírujte jej ze svého dashboardu.
`region`	`"us" \| "eu"`	žádná	Volitelný datový region. Bez nastavení používá SDK generický endpoint `https://edge.tracio.ai` (bez implikované datové rezidence v USA). Nastavte jej explicitně na `us` nebo `eu`.
`endpoint`	`string`	auto	Vlastní API endpoint (pro endpoint proxovaný jako first-party).
`scriptUrl`	`string`	auto	Vlastní URL pro skript agenta (pro endpoint proxovaný jako first-party).
`linkedId`	`string`	žádné	Identifikátor propojující tohoto návštěvníka s entitou ve vašem systému.
`tag`	`string`	žádný	Volně definovaný štítek připojený k požadavku pro pozdější filtrování.
`debug`	`boolean`	`false`	Loguje podrobné diagnostické informace do konzole.
`timeoutMs`	`number`	`15000`	Jak dlouho se čeká na výsledek, než dojde k vypršení časového limitu.

Zavolání Tracio.init() více než jednou s odlišným veřejným klíčem vyvolá chybu multiple_keys.

Identifikace

tracio.getVisitorId()

Vrací Promise<string>, který se vyhodnotí na stabilní identifikátor návštěvníka.

TypeScript

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

tracio.getResult()

Vrací Promise<TracioResult> s ID návštěvníka a výsledkem detekce botů.

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

Lifecycle callbacky

tracio.onReady(cb)

Vyvolá se, jakmile je agent načten a vyprodukuje výsledek.

TypeScript

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

tracio.onError(cb)

Vyvolá se, když SDK narazí na chybu.

TypeScript

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

tracio.destroy()

Zruší instanci a uvolní prostředky. Následná volání jsou odmítnuta s chybou destroyed.

TypeScript

tracio.destroy()

Zpracování chyb

SDK vyvolává instance TracioError s typovaným code. K větvení použijte pomocné funkce isTracioError a isRetryableError:

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

Chybové kódy

Union TracioErrorCode pokrývá:

Kód	Popis
`blocked`	Požadavek byl zablokován (např. blokovačem reklam).
`destroyed`	Instance byla zrušena před dokončením volání.
`invalid_config`	Konfigurace je neplatná (např. chybějící `publicKey`).
`load_failed`	Skript agenta se nepodařilo načíst.
`multiple_keys`	`Tracio.init()` byl zavolán s konfliktním veřejným klíčem.
`network`	Síťový požadavek selhal.
`non_browser`	SDK bylo použito mimo prostředí prohlížeče.
`script_error`	Skript agenta vyvolal chybu za běhu.
`server`	Server vrátil chybu.
`timeout`	Požadavek překročil `timeoutMs`.

load_failed, blocked, script_error, network, timeout a server lze opakovat; isRetryableError(error) pro ně vrací true.

Integrace s frameworky

Pro React, Vue, Angular a Svelte použijte dedikované framework balíčky namísto ručního propojování jádra SDK:

Každý z nich obaluje @tracio/sdk a zpřístupňuje idiomatické primitivy (providery, pluginy, hooky, composable funkce a služby). Ukázky pro jednotlivé frameworky najdete v přehledu SDK.

Aspekty výkonu

Neblokující: Tracio.init() se vrací synchronně a načítá agenta na pozadí. Neblokuje vykreslování stránky.
Jediný požadavek: Na jednu identifikaci se odesílá jeden požadavek.
Časový limit: Identifikace je ohraničena hodnotou timeoutMs (výchozí 15000 ms), takže pomalá síť nikdy nezablokuje váš kód donekonečna.

JavaScript SDK

Instalace

bash

npm install @tracio/sdk

Balíček dodává buildy ESM, CJS a IIFE s kompletními TypeScript typy.

CDN

Existují dva způsoby, jak používat TRACIO z CDN bez bundleru.

Edge skript (automatická inicializace)

Edge skript se automaticky inicializuje pomocí veřejného klíče v query parametru k. Není potřeba žádný JavaScript:

HTML

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

npm bundle (globální IIFE)

Publikovaný npm bundle můžete také načíst z unpkg nebo jsDelivr. Zpřístupňuje globální objekt TracioSDK. Zafixujte verzi:

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>

Inicializace

Tracio.init(config)

Inicializuje SDK a synchronně vrací TracioInstance. Agent se načítá na pozadí; metody instance se vyhodnotí, jakmile je připraven.

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
}

Volba	Typ	Výchozí	Popis
`publicKey`	`string`	povinné	Váš veřejný klíč. Zkopírujte jej ze svého dashboardu.
`region`	`"us" \| "eu"`	žádná	Volitelný datový region. Bez nastavení používá SDK generický endpoint `https://edge.tracio.ai` (bez implikované datové rezidence v USA). Nastavte jej explicitně na `us` nebo `eu`.
`endpoint`	`string`	auto	Vlastní API endpoint (pro endpoint proxovaný jako first-party).
`scriptUrl`	`string`	auto	Vlastní URL pro skript agenta (pro endpoint proxovaný jako first-party).
`linkedId`	`string`	žádné	Identifikátor propojující tohoto návštěvníka s entitou ve vašem systému.
`tag`	`string`	žádný	Volně definovaný štítek připojený k požadavku pro pozdější filtrování.
`debug`	`boolean`	`false`	Loguje podrobné diagnostické informace do konzole.
`timeoutMs`	`number`	`15000`	Jak dlouho se čeká na výsledek, než dojde k vypršení časového limitu.

Zavolání Tracio.init() více než jednou s odlišným veřejným klíčem vyvolá chybu multiple_keys.

Identifikace

tracio.getVisitorId()

Vrací Promise<string>, který se vyhodnotí na stabilní identifikátor návštěvníka.

TypeScript

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

tracio.getResult()

Vrací Promise<TracioResult> s ID návštěvníka a výsledkem detekce botů.

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

Lifecycle callbacky

tracio.onReady(cb)

Vyvolá se, jakmile je agent načten a vyprodukuje výsledek.

TypeScript

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

tracio.onError(cb)

Vyvolá se, když SDK narazí na chybu.

TypeScript

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

tracio.destroy()

Zruší instanci a uvolní prostředky. Následná volání jsou odmítnuta s chybou destroyed.

TypeScript

tracio.destroy()

Zpracování chyb

SDK vyvolává instance TracioError s typovaným code. K větvení použijte pomocné funkce isTracioError a isRetryableError:

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

Chybové kódy

Union TracioErrorCode pokrývá:

Kód	Popis
`blocked`	Požadavek byl zablokován (např. blokovačem reklam).
`destroyed`	Instance byla zrušena před dokončením volání.
`invalid_config`	Konfigurace je neplatná (např. chybějící `publicKey`).
`load_failed`	Skript agenta se nepodařilo načíst.
`multiple_keys`	`Tracio.init()` byl zavolán s konfliktním veřejným klíčem.
`network`	Síťový požadavek selhal.
`non_browser`	SDK bylo použito mimo prostředí prohlížeče.
`script_error`	Skript agenta vyvolal chybu za běhu.
`server`	Server vrátil chybu.
`timeout`	Požadavek překročil `timeoutMs`.

load_failed, blocked, script_error, network, timeout a server lze opakovat; isRetryableError(error) pro ně vrací true.

Integrace s frameworky

Pro React, Vue, Angular a Svelte použijte dedikované framework balíčky namísto ručního propojování jádra SDK:

Každý z nich obaluje @tracio/sdk a zpřístupňuje idiomatické primitivy (providery, pluginy, hooky, composable funkce a služby). Ukázky pro jednotlivé frameworky najdete v přehledu SDK.

Aspekty výkonu

Neblokující: Tracio.init() se vrací synchronně a načítá agenta na pozadí. Neblokuje vykreslování stránky.
Jediný požadavek: Na jednu identifikaci se odesílá jeden požadavek.
Časový limit: Identifikace je ohraničena hodnotou timeoutMs (výchozí 15000 ms), takže pomalá síť nikdy nezablokuje váš kód donekonečna.