JavaScript SDK

L'SDK JavaScript di TRACIO (@tracio/sdk) raccoglie i segnali del browser e li invia al cloud di TRACIO per l'identificazione dei visitatori e il rilevamento dei bot. È leggero, non bloccante e compatibile con tutti i browser moderni.

Installazione

bash

npm install @tracio/sdk

Il pacchetto include build ESM, CJS e IIFE con tipi TypeScript completi.

CDN

Ci sono due modi per usare TRACIO da una CDN senza un bundler.

Script edge (auto-init)

Lo script edge si auto-inizializza usando la public key nel parametro di query k. Non è richiesto alcun JavaScript:

HTML

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

Bundle npm (globale IIFE)

Può anche caricare il bundle npm pubblicato da unpkg o jsDelivr. Espone un globale TracioSDK. Fissi una versione:

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>

Inizializzazione

Tracio.init(config)

Inizializza l'SDK e restituisce un TracioInstance in modo sincrono. L'agent viene caricato in background; i metodi dell'istanza si risolvono una volta che è pronto.

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
}

Opzione	Tipo	Default	Descrizione
`publicKey`	`string`	required	La propria public key. La copi dalla propria dashboard.
`region`	`"us" \| "eu"`	none	Regione dati opzionale. Quando non è impostata, l'SDK usa l'endpoint generico `https://edge.tracio.ai` (nessuna residenza dati US implicita). La imposti esplicitamente per fissare `us` o `eu`.
`endpoint`	`string`	auto	Endpoint API personalizzato (per un endpoint proxied first-party).
`scriptUrl`	`string`	auto	URL personalizzato per lo script dell'agent (per un endpoint proxied first-party).
`linkedId`	`string`	none	Identificatore che collega questo visitatore a un'entità nel proprio sistema.
`tag`	`string`	none	Etichetta a formato libero associata alla richiesta per un filtraggio successivo.
`debug`	`boolean`	`false`	Registra diagnostica dettagliata nella console.
`timeoutMs`	`number`	`15000`	Quanto attendere il risultato prima del timeout.

Chiamare Tracio.init() più di una volta con una public key diversa genera un errore multiple_keys.

Identificazione

tracio.getVisitorId()

Restituisce una Promise<string> che si risolve nell'identificatore stabile del visitatore.

TypeScript

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

tracio.getResult()

Restituisce una Promise<TracioResult> con l'ID visitatore e il risultato del rilevamento dei 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[]
  }
}

Callback del ciclo di vita

tracio.onReady(cb)

Invocato una volta che l'agent è stato caricato e ha prodotto un risultato.

TypeScript

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

tracio.onError(cb)

Invocato quando l'SDK incontra un errore.

TypeScript

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

tracio.destroy()

Smonta l'istanza e rilascia le risorse. Le chiamate successive vengono rifiutate con un errore destroyed.

TypeScript

tracio.destroy()

Gestione degli errori

L'SDK genera istanze di TracioError con un code tipizzato. Usi gli helper isTracioError e isRetryableError per ramificare:

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

Codici di errore

L'unione TracioErrorCode copre:

Codice	Descrizione
`blocked`	La richiesta è stata bloccata (ad es. da un ad blocker).
`destroyed`	L'istanza è stata distrutta prima del completamento della chiamata.
`invalid_config`	La configurazione non è valida (ad es. `publicKey` mancante).
`load_failed`	Il caricamento dello script dell'agent è fallito.
`multiple_keys`	`Tracio.init()` è stato chiamato con una public key in conflitto.
`network`	Una richiesta di rete è fallita.
`non_browser`	L'SDK è stato usato al di fuori di un ambiente browser.
`script_error`	Lo script dell'agent ha sollevato un errore a runtime.
`server`	Il server ha restituito un errore.
`timeout`	La richiesta ha superato `timeoutMs`.

load_failed, blocked, script_error, network, timeout e server sono retryable; isRetryableError(error) restituisce true per essi.

Integrazione con i framework

Per React, Vue, Angular e Svelte, usi i pacchetti dedicati dei framework invece di collegare manualmente l'SDK core:

Ciascuno incapsula @tracio/sdk ed espone primitive idiomatiche (provider, plugin, hook, composable e service). Vedi la panoramica degli SDK per gli snippet per ciascun framework.

Considerazioni sulle prestazioni

Non bloccante: Tracio.init() restituisce in modo sincrono e carica l'agent in background. Non blocca il rendering della pagina.
Richiesta singola: viene effettuata una richiesta per identificazione.
Timeout: l'identificazione è limitata da timeoutMs (default 15000ms), così che una rete lenta non blocchi mai il proprio codice indefinitamente.

JavaScript SDK

Installazione

bash

npm install @tracio/sdk

Il pacchetto include build ESM, CJS e IIFE con tipi TypeScript completi.

CDN

Ci sono due modi per usare TRACIO da una CDN senza un bundler.

Script edge (auto-init)

Lo script edge si auto-inizializza usando la public key nel parametro di query k. Non è richiesto alcun JavaScript:

HTML

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

Bundle npm (globale IIFE)

Può anche caricare il bundle npm pubblicato da unpkg o jsDelivr. Espone un globale TracioSDK. Fissi una versione:

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>

Inizializzazione

Tracio.init(config)

Inizializza l'SDK e restituisce un TracioInstance in modo sincrono. L'agent viene caricato in background; i metodi dell'istanza si risolvono una volta che è pronto.

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
}

Opzione	Tipo	Default	Descrizione
`publicKey`	`string`	required	La propria public key. La copi dalla propria dashboard.
`region`	`"us" \| "eu"`	none	Regione dati opzionale. Quando non è impostata, l'SDK usa l'endpoint generico `https://edge.tracio.ai` (nessuna residenza dati US implicita). La imposti esplicitamente per fissare `us` o `eu`.
`endpoint`	`string`	auto	Endpoint API personalizzato (per un endpoint proxied first-party).
`scriptUrl`	`string`	auto	URL personalizzato per lo script dell'agent (per un endpoint proxied first-party).
`linkedId`	`string`	none	Identificatore che collega questo visitatore a un'entità nel proprio sistema.
`tag`	`string`	none	Etichetta a formato libero associata alla richiesta per un filtraggio successivo.
`debug`	`boolean`	`false`	Registra diagnostica dettagliata nella console.
`timeoutMs`	`number`	`15000`	Quanto attendere il risultato prima del timeout.

Chiamare Tracio.init() più di una volta con una public key diversa genera un errore multiple_keys.

Identificazione

tracio.getVisitorId()

Restituisce una Promise<string> che si risolve nell'identificatore stabile del visitatore.

TypeScript

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

tracio.getResult()

Restituisce una Promise<TracioResult> con l'ID visitatore e il risultato del rilevamento dei 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[]
  }
}

Callback del ciclo di vita

tracio.onReady(cb)

Invocato una volta che l'agent è stato caricato e ha prodotto un risultato.

TypeScript

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

tracio.onError(cb)

Invocato quando l'SDK incontra un errore.

TypeScript

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

tracio.destroy()

Smonta l'istanza e rilascia le risorse. Le chiamate successive vengono rifiutate con un errore destroyed.

TypeScript

tracio.destroy()

Gestione degli errori

L'SDK genera istanze di TracioError con un code tipizzato. Usi gli helper isTracioError e isRetryableError per ramificare:

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

Codici di errore

L'unione TracioErrorCode copre:

Codice	Descrizione
`blocked`	La richiesta è stata bloccata (ad es. da un ad blocker).
`destroyed`	L'istanza è stata distrutta prima del completamento della chiamata.
`invalid_config`	La configurazione non è valida (ad es. `publicKey` mancante).
`load_failed`	Il caricamento dello script dell'agent è fallito.
`multiple_keys`	`Tracio.init()` è stato chiamato con una public key in conflitto.
`network`	Una richiesta di rete è fallita.
`non_browser`	L'SDK è stato usato al di fuori di un ambiente browser.
`script_error`	Lo script dell'agent ha sollevato un errore a runtime.
`server`	Il server ha restituito un errore.
`timeout`	La richiesta ha superato `timeoutMs`.

load_failed, blocked, script_error, network, timeout e server sono retryable; isRetryableError(error) restituisce true per essi.

Integrazione con i framework

Per React, Vue, Angular e Svelte, usi i pacchetti dedicati dei framework invece di collegare manualmente l'SDK core:

Ciascuno incapsula @tracio/sdk ed espone primitive idiomatiche (provider, plugin, hook, composable e service). Vedi la panoramica degli SDK per gli snippet per ciascun framework.

Considerazioni sulle prestazioni

Non bloccante: Tracio.init() restituisce in modo sincrono e carica l'agent in background. Non blocca il rendering della pagina.
Richiesta singola: viene effettuata una richiesta per identificazione.
Timeout: l'identificazione è limitata da timeoutMs (default 15000ms), così che una rete lenta non blocchi mai il proprio codice indefinitamente.