JavaScript-SDK

Das TRACIO JavaScript-SDK (@tracio/sdk) erfasst Browser-Signale und sendet sie an die TRACIO-Cloud zur Besucher-Identifikation und Bot-Erkennung. Es ist leichtgewichtig, nicht blockierend und mit allen modernen Browsern kompatibel.

Installation

bash

npm install @tracio/sdk

Das Paket liefert ESM-, CJS- und IIFE-Builds mit vollständigen TypeScript-Typen aus.

CDN

Es gibt zwei Möglichkeiten, TRACIO ohne Bundler über ein CDN zu nutzen.

Edge-Skript (Auto-Init)

Das Edge-Skript initialisiert sich automatisch mit dem Public Key im Query-Parameter k. Kein JavaScript erforderlich:

HTML

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

npm-Bundle (IIFE-Global)

Sie können auch das veröffentlichte npm-Bundle von unpkg oder jsDelivr laden. Es stellt ein globales TracioSDK bereit. Pinnen Sie eine Version:

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>

Initialisierung

Tracio.init(config)

Initialisiert das SDK und gibt synchron eine TracioInstance zurück. Der Agent lädt im Hintergrund; die Instanzmethoden werden aufgelöst, sobald er bereit ist.

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
}

Option	Typ	Standard	Beschreibung
`publicKey`	`string`	erforderlich	Ihr Public Key. Kopieren Sie ihn aus Ihrem Dashboard.
`region`	`"us" \| "eu"`	keiner	Optionale Datenregion. Ohne Angabe verwendet das SDK den generischen Endpunkt `https://edge.tracio.ai` (keine implizite Datenresidenz in den USA). Setzen Sie ihn explizit, um `us` oder `eu` festzulegen.
`endpoint`	`string`	auto	Benutzerdefinierter API-Endpunkt (für einen als First-Party geproxyten Endpunkt).
`scriptUrl`	`string`	auto	Benutzerdefinierte URL für das Agent-Skript (für einen als First-Party geproxyten Endpunkt).
`linkedId`	`string`	keiner	Kennung, die diesen Besucher mit einer Entität in Ihrem System verknüpft.
`tag`	`string`	keiner	Frei wählbares Label, das der Anfrage für spätere Filterung angehängt wird.
`debug`	`boolean`	`false`	Protokolliert ausführliche Diagnosen in der Konsole.
`timeoutMs`	`number`	`15000`	Wie lange auf das Ergebnis gewartet wird, bevor ein Timeout eintritt.

Wird Tracio.init() mehr als einmal mit einem anderen Public Key aufgerufen, wird ein multiple_keys-Fehler ausgelöst.

Identifikation

tracio.getVisitorId()

Gibt ein Promise<string> zurück, das zur stabilen Besucherkennung aufgelöst wird.

TypeScript

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

tracio.getResult()

Gibt ein Promise<TracioResult> mit der Besucher-ID und dem Ergebnis der Bot-Erkennung zurück.

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)

Wird aufgerufen, sobald der Agent geladen ist und ein Ergebnis erzeugt hat.

TypeScript

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

tracio.onError(cb)

Wird aufgerufen, wenn das SDK auf einen Fehler stößt.

TypeScript

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

tracio.destroy()

Baut die Instanz ab und gibt Ressourcen frei. Nachfolgende Aufrufe werden mit einem destroyed-Fehler abgelehnt.

TypeScript

tracio.destroy()

Fehlerbehandlung

Das SDK löst TracioError-Instanzen mit einem typisierten code aus. Verwenden Sie die Helfer isTracioError und isRetryableError, um zu verzweigen:

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

Fehlercodes

Die Union TracioErrorCode umfasst:

Code	Beschreibung
`blocked`	Die Anfrage wurde blockiert (z. B. durch einen Ad-Blocker).
`destroyed`	Die Instanz wurde zerstört, bevor der Aufruf abgeschlossen war.
`invalid_config`	Die Konfiguration ist ungültig (z. B. fehlender `publicKey`).
`load_failed`	Das Agent-Skript konnte nicht geladen werden.
`multiple_keys`	`Tracio.init()` wurde mit einem widersprüchlichen Public Key aufgerufen.
`network`	Eine Netzwerkanfrage ist fehlgeschlagen.
`non_browser`	Das SDK wurde außerhalb einer Browser-Umgebung verwendet.
`script_error`	Das Agent-Skript hat zur Laufzeit einen Fehler ausgelöst.
`server`	Der Server hat einen Fehler zurückgegeben.
`timeout`	Die Anfrage hat `timeoutMs` überschritten.

load_failed, blocked, script_error, network, timeout und server sind wiederholbar; isRetryableError(error) gibt für sie true zurück.

Framework-Integration

Verwenden Sie für React, Vue, Angular und Svelte die dedizierten Framework-Pakete, anstatt das Core-SDK von Hand zu verdrahten:

Jedes umschließt @tracio/sdk und stellt idiomatische Primitive bereit (Provider, Plug-ins, Hooks, Composables und Services). Framework-spezifische Snippets finden Sie in der SDKs-Übersicht.

Leistungsaspekte

Nicht blockierend: Tracio.init() kehrt synchron zurück und lädt den Agent im Hintergrund. Es blockiert das Rendern der Seite nicht.
Einzelne Anfrage: Pro Identifikation wird eine Anfrage gestellt.
Timeout: Die Identifikation ist durch timeoutMs (Standard 15000 ms) begrenzt, sodass ein langsames Netzwerk Ihren Code niemals unbegrenzt blockiert.

JavaScript-SDK

Installation

bash

npm install @tracio/sdk

Das Paket liefert ESM-, CJS- und IIFE-Builds mit vollständigen TypeScript-Typen aus.

CDN

Es gibt zwei Möglichkeiten, TRACIO ohne Bundler über ein CDN zu nutzen.

Edge-Skript (Auto-Init)

Das Edge-Skript initialisiert sich automatisch mit dem Public Key im Query-Parameter k. Kein JavaScript erforderlich:

HTML

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

npm-Bundle (IIFE-Global)

Sie können auch das veröffentlichte npm-Bundle von unpkg oder jsDelivr laden. Es stellt ein globales TracioSDK bereit. Pinnen Sie eine Version:

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>

Initialisierung

Tracio.init(config)

Initialisiert das SDK und gibt synchron eine TracioInstance zurück. Der Agent lädt im Hintergrund; die Instanzmethoden werden aufgelöst, sobald er bereit ist.

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
}

Option	Typ	Standard	Beschreibung
`publicKey`	`string`	erforderlich	Ihr Public Key. Kopieren Sie ihn aus Ihrem Dashboard.
`region`	`"us" \| "eu"`	keiner	Optionale Datenregion. Ohne Angabe verwendet das SDK den generischen Endpunkt `https://edge.tracio.ai` (keine implizite Datenresidenz in den USA). Setzen Sie ihn explizit, um `us` oder `eu` festzulegen.
`endpoint`	`string`	auto	Benutzerdefinierter API-Endpunkt (für einen als First-Party geproxyten Endpunkt).
`scriptUrl`	`string`	auto	Benutzerdefinierte URL für das Agent-Skript (für einen als First-Party geproxyten Endpunkt).
`linkedId`	`string`	keiner	Kennung, die diesen Besucher mit einer Entität in Ihrem System verknüpft.
`tag`	`string`	keiner	Frei wählbares Label, das der Anfrage für spätere Filterung angehängt wird.
`debug`	`boolean`	`false`	Protokolliert ausführliche Diagnosen in der Konsole.
`timeoutMs`	`number`	`15000`	Wie lange auf das Ergebnis gewartet wird, bevor ein Timeout eintritt.

Wird Tracio.init() mehr als einmal mit einem anderen Public Key aufgerufen, wird ein multiple_keys-Fehler ausgelöst.

Identifikation

tracio.getVisitorId()

Gibt ein Promise<string> zurück, das zur stabilen Besucherkennung aufgelöst wird.

TypeScript

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

tracio.getResult()

Gibt ein Promise<TracioResult> mit der Besucher-ID und dem Ergebnis der Bot-Erkennung zurück.

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)

Wird aufgerufen, sobald der Agent geladen ist und ein Ergebnis erzeugt hat.

TypeScript

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

tracio.onError(cb)

Wird aufgerufen, wenn das SDK auf einen Fehler stößt.

TypeScript

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

tracio.destroy()

Baut die Instanz ab und gibt Ressourcen frei. Nachfolgende Aufrufe werden mit einem destroyed-Fehler abgelehnt.

TypeScript

tracio.destroy()

Fehlerbehandlung

Das SDK löst TracioError-Instanzen mit einem typisierten code aus. Verwenden Sie die Helfer isTracioError und isRetryableError, um zu verzweigen:

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

Fehlercodes

Die Union TracioErrorCode umfasst:

Code	Beschreibung
`blocked`	Die Anfrage wurde blockiert (z. B. durch einen Ad-Blocker).
`destroyed`	Die Instanz wurde zerstört, bevor der Aufruf abgeschlossen war.
`invalid_config`	Die Konfiguration ist ungültig (z. B. fehlender `publicKey`).
`load_failed`	Das Agent-Skript konnte nicht geladen werden.
`multiple_keys`	`Tracio.init()` wurde mit einem widersprüchlichen Public Key aufgerufen.
`network`	Eine Netzwerkanfrage ist fehlgeschlagen.
`non_browser`	Das SDK wurde außerhalb einer Browser-Umgebung verwendet.
`script_error`	Das Agent-Skript hat zur Laufzeit einen Fehler ausgelöst.
`server`	Der Server hat einen Fehler zurückgegeben.
`timeout`	Die Anfrage hat `timeoutMs` überschritten.

load_failed, blocked, script_error, network, timeout und server sind wiederholbar; isRetryableError(error) gibt für sie true zurück.

Framework-Integration

Verwenden Sie für React, Vue, Angular und Svelte die dedizierten Framework-Pakete, anstatt das Core-SDK von Hand zu verdrahten:

Jedes umschließt @tracio/sdk und stellt idiomatische Primitive bereit (Provider, Plug-ins, Hooks, Composables und Services). Framework-spezifische Snippets finden Sie in der SDKs-Übersicht.

Leistungsaspekte

Nicht blockierend: Tracio.init() kehrt synchron zurück und lädt den Agent im Hintergrund. Es blockiert das Rendern der Seite nicht.
Einzelne Anfrage: Pro Identifikation wird eine Anfrage gestellt.
Timeout: Die Identifikation ist durch timeoutMs (Standard 15000 ms) begrenzt, sodass ein langsames Netzwerk Ihren Code niemals unbegrenzt blockiert.