SDK JavaScript

SDK-ul JavaScript TRACIO (@tracio/sdk) colectează semnale din browser și le trimite către cloud-ul TRACIO pentru identificarea vizitatorilor și detectarea boților. Este ușor, non-blocant și compatibil cu toate browserele moderne.

Instalare

bash

npm install @tracio/sdk

Pachetul livrează build-uri ESM, CJS și IIFE cu tipuri TypeScript complete.

CDN

Există două modalități de a folosi TRACIO dintr-un CDN fără un bundler.

Script edge (auto-init)

Scriptul edge se inițializează automat folosind cheia publică din parametrul de query k. Nu este necesar niciun JavaScript:

HTML

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

Bundle npm (global IIFE)

Poți încărca și bundle-ul npm publicat de pe unpkg sau jsDelivr. Acesta expune un global TracioSDK. Fixează o versiune:

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>

Inițializare

Tracio.init(config)

Inițializează SDK-ul și returnează sincron o TracioInstance. Agentul se încarcă în fundal; metodele instanței se rezolvă odată ce este gata.

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
}

Opțiune	Tip	Implicit	Descriere
`publicKey`	`string`	obligatoriu	Cheia ta publică. Copiaz-o din dashboard.
`region`	`"us" \| "eu"`	niciunul	Regiunea de date opțională. Când nu este setată, SDK-ul folosește endpoint-ul generic `https://edge.tracio.ai` (fără rezidență a datelor implicită în SUA). Setează-o explicit pentru a fixa `us` sau `eu`.
`endpoint`	`string`	auto	Endpoint API personalizat (pentru un endpoint proxy first-party).
`scriptUrl`	`string`	auto	URL personalizat pentru scriptul agentului (pentru un endpoint proxy first-party).
`linkedId`	`string`	niciunul	Identificator care leagă acest vizitator de o entitate din sistemul tău.
`tag`	`string`	niciunul	Etichetă cu format liber atașată cererii pentru filtrare ulterioară.
`debug`	`boolean`	`false`	Înregistrează diagnostice detaliate în consolă.
`timeoutMs`	`number`	`15000`	Cât timp să se aștepte rezultatul înainte de expirare.

Apelarea Tracio.init() de mai multe ori cu o cheie publică diferită aruncă o eroare multiple_keys.

Identificare

tracio.getVisitorId()

Returnează un Promise<string> care se rezolvă la identificatorul stabil al vizitatorului.

TypeScript

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

tracio.getResult()

Returnează un Promise<TracioResult> cu ID-ul vizitatorului și rezultatul detectării boților.

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

Callback-uri de ciclu de viață

tracio.onReady(cb)

Este invocat odată ce agentul s-a încărcat și a produs un rezultat.

TypeScript

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

tracio.onError(cb)

Este invocat când SDK-ul întâmpină o eroare.

TypeScript

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

tracio.destroy()

Dezasamblează instanța și eliberează resursele. Apelurile ulterioare sunt respinse cu o eroare destroyed.

TypeScript

tracio.destroy()

Tratarea erorilor

SDK-ul aruncă instanțe TracioError cu un code tipizat. Folosește funcțiile ajutătoare isTracioError și isRetryableError pentru a ramifica:

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

Coduri de eroare

Uniunea TracioErrorCode acoperă:

Cod	Descriere
`blocked`	Cererea a fost blocată (de ex. de un ad blocker).
`destroyed`	Instanța a fost distrusă înainte ca apelul să se finalizeze.
`invalid_config`	Configurația este invalidă (de ex. lipsește `publicKey`).
`load_failed`	Scriptul agentului nu a putut fi încărcat.
`multiple_keys`	`Tracio.init()` a fost apelat cu o cheie publică conflictuală.
`network`	O cerere de rețea a eșuat.
`non_browser`	SDK-ul a fost folosit în afara unui mediu de browser.
`script_error`	Scriptul agentului a generat o eroare la runtime.
`server`	Serverul a returnat o eroare.
`timeout`	Cererea a depășit `timeoutMs`.

load_failed, blocked, script_error, network, timeout și server pot fi reîncercate; isRetryableError(error) returnează true pentru ele.

Integrare cu framework-uri

Pentru React, Vue, Angular și Svelte, folosește pachetele dedicate de framework în loc să conectezi manual SDK-ul de bază:

Fiecare încapsulează @tracio/sdk și expune primitive idiomatice (provideri, plugin-uri, hooks, composables și servicii). Consultă prezentarea generală a SDK-urilor pentru fragmente de cod specifice fiecărui framework.

Considerații de performanță

Non-blocant: Tracio.init() returnează sincron și încarcă agentul în fundal. Nu blochează randarea paginii.
O singură cerere: Se face o singură cerere per identificare.
Timeout: Identificarea este limitată de timeoutMs (implicit 15000 ms), astfel încât o rețea lentă nu blochează niciodată codul tău la nesfârșit.

SDK JavaScript

Instalare

bash

npm install @tracio/sdk

Pachetul livrează build-uri ESM, CJS și IIFE cu tipuri TypeScript complete.

CDN

Există două modalități de a folosi TRACIO dintr-un CDN fără un bundler.

Script edge (auto-init)

Scriptul edge se inițializează automat folosind cheia publică din parametrul de query k. Nu este necesar niciun JavaScript:

HTML

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

Bundle npm (global IIFE)

Poți încărca și bundle-ul npm publicat de pe unpkg sau jsDelivr. Acesta expune un global TracioSDK. Fixează o versiune:

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>

Inițializare

Tracio.init(config)

Inițializează SDK-ul și returnează sincron o TracioInstance. Agentul se încarcă în fundal; metodele instanței se rezolvă odată ce este gata.

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
}

Opțiune	Tip	Implicit	Descriere
`publicKey`	`string`	obligatoriu	Cheia ta publică. Copiaz-o din dashboard.
`region`	`"us" \| "eu"`	niciunul	Regiunea de date opțională. Când nu este setată, SDK-ul folosește endpoint-ul generic `https://edge.tracio.ai` (fără rezidență a datelor implicită în SUA). Setează-o explicit pentru a fixa `us` sau `eu`.
`endpoint`	`string`	auto	Endpoint API personalizat (pentru un endpoint proxy first-party).
`scriptUrl`	`string`	auto	URL personalizat pentru scriptul agentului (pentru un endpoint proxy first-party).
`linkedId`	`string`	niciunul	Identificator care leagă acest vizitator de o entitate din sistemul tău.
`tag`	`string`	niciunul	Etichetă cu format liber atașată cererii pentru filtrare ulterioară.
`debug`	`boolean`	`false`	Înregistrează diagnostice detaliate în consolă.
`timeoutMs`	`number`	`15000`	Cât timp să se aștepte rezultatul înainte de expirare.

Apelarea Tracio.init() de mai multe ori cu o cheie publică diferită aruncă o eroare multiple_keys.

Identificare

tracio.getVisitorId()

Returnează un Promise<string> care se rezolvă la identificatorul stabil al vizitatorului.

TypeScript

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

tracio.getResult()

Returnează un Promise<TracioResult> cu ID-ul vizitatorului și rezultatul detectării boților.

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

Callback-uri de ciclu de viață

tracio.onReady(cb)

Este invocat odată ce agentul s-a încărcat și a produs un rezultat.

TypeScript

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

tracio.onError(cb)

Este invocat când SDK-ul întâmpină o eroare.

TypeScript

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

tracio.destroy()

Dezasamblează instanța și eliberează resursele. Apelurile ulterioare sunt respinse cu o eroare destroyed.

TypeScript

tracio.destroy()

Tratarea erorilor

SDK-ul aruncă instanțe TracioError cu un code tipizat. Folosește funcțiile ajutătoare isTracioError și isRetryableError pentru a ramifica:

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

Coduri de eroare

Uniunea TracioErrorCode acoperă:

Cod	Descriere
`blocked`	Cererea a fost blocată (de ex. de un ad blocker).
`destroyed`	Instanța a fost distrusă înainte ca apelul să se finalizeze.
`invalid_config`	Configurația este invalidă (de ex. lipsește `publicKey`).
`load_failed`	Scriptul agentului nu a putut fi încărcat.
`multiple_keys`	`Tracio.init()` a fost apelat cu o cheie publică conflictuală.
`network`	O cerere de rețea a eșuat.
`non_browser`	SDK-ul a fost folosit în afara unui mediu de browser.
`script_error`	Scriptul agentului a generat o eroare la runtime.
`server`	Serverul a returnat o eroare.
`timeout`	Cererea a depășit `timeoutMs`.

load_failed, blocked, script_error, network, timeout și server pot fi reîncercate; isRetryableError(error) returnează true pentru ele.

Integrare cu framework-uri

Pentru React, Vue, Angular și Svelte, folosește pachetele dedicate de framework în loc să conectezi manual SDK-ul de bază:

Considerații de performanță

Non-blocant: Tracio.init() returnează sincron și încarcă agentul în fundal. Nu blochează randarea paginii.
O singură cerere: Se face o singură cerere per identificare.
Timeout: Identificarea este limitată de timeoutMs (implicit 15000 ms), astfel încât o rețea lentă nu blochează niciodată codul tău la nesfârșit.