JavaScript-SDK

De TRACIO JavaScript-SDK (@tracio/sdk) verzamelt browsersignalen en verstuurt ze naar de TRACIO-cloud voor bezoekersidentificatie en botdetectie. De SDK is lichtgewicht, niet-blokkerend en compatibel met alle moderne browsers.

Installatie

bash

npm install @tracio/sdk

Het pakket wordt geleverd met ESM-, CJS- en IIFE-builds met volledige TypeScript-types.

CDN

Er zijn twee manieren om TRACIO zonder bundler via een CDN te gebruiken.

Edge-script (auto-init)

Het edge-script initialiseert zichzelf automatisch met de public key in de query-parameter k. Geen JavaScript vereist:

HTML

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

npm-bundle (IIFE-global)

U kunt ook de gepubliceerde npm-bundle van unpkg of jsDelivr laden. Deze stelt een globale TracioSDK beschikbaar. Zet een versie vast:

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>

Initialisatie

Tracio.init(config)

Initialiseert de SDK en retourneert synchroon een TracioInstance. De agent laadt op de achtergrond; de instantiemethoden worden opgelost zodra deze gereed is.

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
}

Optie	Type	Standaard	Beschrijving
`publicKey`	`string`	vereist	Uw public key. Kopieer deze uit uw dashboard.
`region`	`"us" \| "eu"`	geen	Optionele dataregio. Zonder opgave gebruikt de SDK het generieke endpoint `https://edge.tracio.ai` (geen impliciete dataresidentie in de VS). Stel deze expliciet in om `us` of `eu` vast te zetten.
`endpoint`	`string`	auto	Aangepast API-endpoint (voor een als first-party geproxyd endpoint).
`scriptUrl`	`string`	auto	Aangepaste URL voor het agent-script (voor een als first-party geproxyd endpoint).
`linkedId`	`string`	geen	Identifier die deze bezoeker koppelt aan een entiteit in uw systeem.
`tag`	`string`	geen	Vrij te kiezen label dat aan de aanvraag wordt gekoppeld voor latere filtering.
`debug`	`boolean`	`false`	Logt uitgebreide diagnostiek naar de console.
`timeoutMs`	`number`	`15000`	Hoe lang op het resultaat wordt gewacht voordat er een time-out optreedt.

Wanneer Tracio.init() meer dan eens met een andere public key wordt aangeroepen, wordt een multiple_keys-fout gegenereerd.

Identificatie

tracio.getVisitorId()

Retourneert een Promise<string> die wordt opgelost naar de stabiele bezoekersidentifier.

TypeScript

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

tracio.getResult()

Retourneert een Promise<TracioResult> met de bezoekers-ID en het resultaat van de botdetectie.

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-callbacks

tracio.onReady(cb)

Wordt aangeroepen zodra de agent is geladen en een resultaat heeft geproduceerd.

TypeScript

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

tracio.onError(cb)

Wordt aangeroepen wanneer de SDK op een fout stuit.

TypeScript

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

tracio.destroy()

Breekt de instantie af en geeft resources vrij. Volgende aanroepen worden afgewezen met een destroyed-fout.

TypeScript

tracio.destroy()

Foutafhandeling

De SDK genereert TracioError-instanties met een getypeerde code. Gebruik de helpers isTracioError en isRetryableError om te vertakken:

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

Foutcodes

De union TracioErrorCode omvat:

Code	Beschrijving
`blocked`	De aanvraag werd geblokkeerd (bijv. door een adblocker).
`destroyed`	De instantie werd vernietigd voordat de aanroep voltooid was.
`invalid_config`	De configuratie is ongeldig (bijv. ontbrekende `publicKey`).
`load_failed`	Het agent-script kon niet worden geladen.
`multiple_keys`	`Tracio.init()` werd met een tegenstrijdige public key aangeroepen.
`network`	Een netwerkaanvraag is mislukt.
`non_browser`	De SDK werd buiten een browseromgeving gebruikt.
`script_error`	Het agent-script heeft tijdens runtime een fout gegenereerd.
`server`	De server heeft een fout geretourneerd.
`timeout`	De aanvraag overschreed `timeoutMs`.

load_failed, blocked, script_error, network, timeout en server zijn herhaalbaar; isRetryableError(error) geeft voor die codes true terug.

Framework-integratie

Gebruik voor React, Vue, Angular en Svelte de speciale framework-pakketten in plaats van de core-SDK handmatig te bedraden:

Elk pakket omhult @tracio/sdk en biedt idiomatische primitieven (providers, plug-ins, hooks, composables en services). Framework-specifieke snippets vindt u in het SDK-overzicht.

Prestatieoverwegingen

Niet-blokkerend: Tracio.init() keert synchroon terug en laadt de agent op de achtergrond. Het blokkeert het renderen van de pagina niet.
Eén aanvraag: Er wordt één aanvraag per identificatie gedaan.
Time-out: De identificatie wordt begrensd door timeoutMs (standaard 15000 ms), zodat een traag netwerk uw code nooit onbeperkt laat vastlopen.

JavaScript-SDK

Installatie

bash

npm install @tracio/sdk

Het pakket wordt geleverd met ESM-, CJS- en IIFE-builds met volledige TypeScript-types.

CDN

Er zijn twee manieren om TRACIO zonder bundler via een CDN te gebruiken.

Edge-script (auto-init)

Het edge-script initialiseert zichzelf automatisch met de public key in de query-parameter k. Geen JavaScript vereist:

HTML

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

npm-bundle (IIFE-global)

U kunt ook de gepubliceerde npm-bundle van unpkg of jsDelivr laden. Deze stelt een globale TracioSDK beschikbaar. Zet een versie vast:

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>

Initialisatie

Tracio.init(config)

Initialiseert de SDK en retourneert synchroon een TracioInstance. De agent laadt op de achtergrond; de instantiemethoden worden opgelost zodra deze gereed is.

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
}

Optie	Type	Standaard	Beschrijving
`publicKey`	`string`	vereist	Uw public key. Kopieer deze uit uw dashboard.
`region`	`"us" \| "eu"`	geen	Optionele dataregio. Zonder opgave gebruikt de SDK het generieke endpoint `https://edge.tracio.ai` (geen impliciete dataresidentie in de VS). Stel deze expliciet in om `us` of `eu` vast te zetten.
`endpoint`	`string`	auto	Aangepast API-endpoint (voor een als first-party geproxyd endpoint).
`scriptUrl`	`string`	auto	Aangepaste URL voor het agent-script (voor een als first-party geproxyd endpoint).
`linkedId`	`string`	geen	Identifier die deze bezoeker koppelt aan een entiteit in uw systeem.
`tag`	`string`	geen	Vrij te kiezen label dat aan de aanvraag wordt gekoppeld voor latere filtering.
`debug`	`boolean`	`false`	Logt uitgebreide diagnostiek naar de console.
`timeoutMs`	`number`	`15000`	Hoe lang op het resultaat wordt gewacht voordat er een time-out optreedt.

Wanneer Tracio.init() meer dan eens met een andere public key wordt aangeroepen, wordt een multiple_keys-fout gegenereerd.

Identificatie

tracio.getVisitorId()

Retourneert een Promise<string> die wordt opgelost naar de stabiele bezoekersidentifier.

TypeScript

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

tracio.getResult()

Retourneert een Promise<TracioResult> met de bezoekers-ID en het resultaat van de botdetectie.

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-callbacks

tracio.onReady(cb)

Wordt aangeroepen zodra de agent is geladen en een resultaat heeft geproduceerd.

TypeScript

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

tracio.onError(cb)

Wordt aangeroepen wanneer de SDK op een fout stuit.

TypeScript

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

tracio.destroy()

Breekt de instantie af en geeft resources vrij. Volgende aanroepen worden afgewezen met een destroyed-fout.

TypeScript

tracio.destroy()

Foutafhandeling

De SDK genereert TracioError-instanties met een getypeerde code. Gebruik de helpers isTracioError en isRetryableError om te vertakken:

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

Foutcodes

De union TracioErrorCode omvat:

Code	Beschrijving
`blocked`	De aanvraag werd geblokkeerd (bijv. door een adblocker).
`destroyed`	De instantie werd vernietigd voordat de aanroep voltooid was.
`invalid_config`	De configuratie is ongeldig (bijv. ontbrekende `publicKey`).
`load_failed`	Het agent-script kon niet worden geladen.
`multiple_keys`	`Tracio.init()` werd met een tegenstrijdige public key aangeroepen.
`network`	Een netwerkaanvraag is mislukt.
`non_browser`	De SDK werd buiten een browseromgeving gebruikt.
`script_error`	Het agent-script heeft tijdens runtime een fout gegenereerd.
`server`	De server heeft een fout geretourneerd.
`timeout`	De aanvraag overschreed `timeoutMs`.

load_failed, blocked, script_error, network, timeout en server zijn herhaalbaar; isRetryableError(error) geeft voor die codes true terug.

Framework-integratie

Gebruik voor React, Vue, Angular en Svelte de speciale framework-pakketten in plaats van de core-SDK handmatig te bedraden:

Elk pakket omhult @tracio/sdk en biedt idiomatische primitieven (providers, plug-ins, hooks, composables en services). Framework-specifieke snippets vindt u in het SDK-overzicht.

Prestatieoverwegingen

Niet-blokkerend: Tracio.init() keert synchroon terug en laadt de agent op de achtergrond. Het blokkeert het renderen van de pagina niet.
Eén aanvraag: Er wordt één aanvraag per identificatie gedaan.
Time-out: De identificatie wordt begrensd door timeoutMs (standaard 15000 ms), zodat een traag netwerk uw code nooit onbeperkt laat vastlopen.