JavaScript-SDK

TRACIO:s JavaScript-SDK (@tracio/sdk) samlar in webbläsarsignaler och skickar dem till TRACIO-molnet för besökaridentifiering och botdetektering. Det är lättviktigt, icke-blockerande och kompatibelt med alla moderna webbläsare.

Installation

bash

npm install @tracio/sdk

Paketet levereras med ESM-, CJS- och IIFE-byggen med fullständiga TypeScript-typer.

CDN

Det finns två sätt att använda TRACIO från ett CDN utan bundler.

Edge-skript (auto-init)

Edge-skriptet initieras automatiskt med hjälp av den publika nyckeln i query-parametern k. Ingen JavaScript krävs:

HTML

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

npm-bundle (IIFE-global)

Du kan också ladda det publicerade npm-bundlet från unpkg eller jsDelivr. Det exponerar en global TracioSDK. Fäst en 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>

Initiering

Tracio.init(config)

Initierar SDK:t och returnerar synkront en TracioInstance. Agenten laddas i bakgrunden; instansens metoder resolveras så snart den är redo.

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
}

Alternativ	Typ	Standard	Beskrivning
`publicKey`	`string`	krävs	Din publika nyckel. Kopiera den från din dashboard.
`region`	`"us" \| "eu"`	ingen	Valfri dataregion. När den inte anges använder SDK:t den generiska endpointen `https://edge.tracio.ai` (ingen underförstådd datalagring i USA). Ange den explicit för att fästa `us` eller `eu`.
`endpoint`	`string`	auto	Anpassad API-endpoint (för en first-party-proxad endpoint).
`scriptUrl`	`string`	auto	Anpassad URL för agentskriptet (för en first-party-proxad endpoint).
`linkedId`	`string`	ingen	Identifierare som kopplar denna besökare till en entitet i ditt system.
`tag`	`string`	ingen	Fritt formulerad etikett som bifogas begäran för senare filtrering.
`debug`	`boolean`	`false`	Loggar utförlig diagnostik till konsolen.
`timeoutMs`	`number`	`15000`	Hur länge resultatet inväntas innan en timeout inträffar.

Om Tracio.init() anropas mer än en gång med en annan publik nyckel kastas ett multiple_keys-fel.

Identifiering

tracio.getVisitorId()

Returnerar en Promise<string> som resolveras till den stabila besökaridentifieraren.

TypeScript

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

tracio.getResult()

Returnerar en Promise<TracioResult> med besökar-ID:t och resultatet av botdetekteringen.

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

Livscykel-callbacks

tracio.onReady(cb)

Anropas så snart agenten har laddats och producerat ett resultat.

TypeScript

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

tracio.onError(cb)

Anropas när SDK:t stöter på ett fel.

TypeScript

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

tracio.destroy()

River ner instansen och frigör resurser. Efterföljande anrop avvisas med ett destroyed-fel.

TypeScript

tracio.destroy()

Felhantering

SDK:t kastar TracioError-instanser med en typad code. Använd hjälpfunktionerna isTracioError och isRetryableError för att förgrena:

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

Felkoder

Unionen TracioErrorCode omfattar:

Kod	Beskrivning
`blocked`	Begäran blockerades (t.ex. av en annonsblockerare).
`destroyed`	Instansen förstördes innan anropet slutfördes.
`invalid_config`	Konfigurationen är ogiltig (t.ex. saknad `publicKey`).
`load_failed`	Agentskriptet kunde inte laddas.
`multiple_keys`	`Tracio.init()` anropades med en motstridig publik nyckel.
`network`	En nätverksbegäran misslyckades.
`non_browser`	SDK:t användes utanför en webbläsarmiljö.
`script_error`	Agentskriptet utlöste ett fel vid körning.
`server`	Servern returnerade ett fel.
`timeout`	Begäran överskred `timeoutMs`.

load_failed, blocked, script_error, network, timeout och server är återförsökbara; isRetryableError(error) returnerar true för dem.

Framework-integration

För React, Vue, Angular och Svelte, använd de dedikerade framework-paketen istället för att koppla ihop core-SDK:t för hand:

Vart och ett omsluter @tracio/sdk och exponerar idiomatiska primitiver (providers, plugins, hooks, composables och services). Se SDK-översikten för snuttar per framework.

Prestandaöverväganden

Icke-blockerande: Tracio.init() returnerar synkront och laddar agenten i bakgrunden. Den blockerar inte sidans rendering.
Enkel begäran: En begäran görs per identifiering.
Timeout: Identifieringen är begränsad av timeoutMs (standard 15000 ms), så ett långsamt nätverk låser aldrig din kod på obestämd tid.

JavaScript-SDK

Installation

bash

npm install @tracio/sdk

Paketet levereras med ESM-, CJS- och IIFE-byggen med fullständiga TypeScript-typer.

CDN

Det finns två sätt att använda TRACIO från ett CDN utan bundler.

Edge-skript (auto-init)

Edge-skriptet initieras automatiskt med hjälp av den publika nyckeln i query-parametern k. Ingen JavaScript krävs:

HTML

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

npm-bundle (IIFE-global)

Du kan också ladda det publicerade npm-bundlet från unpkg eller jsDelivr. Det exponerar en global TracioSDK. Fäst en 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>

Initiering

Tracio.init(config)

Initierar SDK:t och returnerar synkront en TracioInstance. Agenten laddas i bakgrunden; instansens metoder resolveras så snart den är redo.

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
}

Alternativ	Typ	Standard	Beskrivning
`publicKey`	`string`	krävs	Din publika nyckel. Kopiera den från din dashboard.
`region`	`"us" \| "eu"`	ingen	Valfri dataregion. När den inte anges använder SDK:t den generiska endpointen `https://edge.tracio.ai` (ingen underförstådd datalagring i USA). Ange den explicit för att fästa `us` eller `eu`.
`endpoint`	`string`	auto	Anpassad API-endpoint (för en first-party-proxad endpoint).
`scriptUrl`	`string`	auto	Anpassad URL för agentskriptet (för en first-party-proxad endpoint).
`linkedId`	`string`	ingen	Identifierare som kopplar denna besökare till en entitet i ditt system.
`tag`	`string`	ingen	Fritt formulerad etikett som bifogas begäran för senare filtrering.
`debug`	`boolean`	`false`	Loggar utförlig diagnostik till konsolen.
`timeoutMs`	`number`	`15000`	Hur länge resultatet inväntas innan en timeout inträffar.

Om Tracio.init() anropas mer än en gång med en annan publik nyckel kastas ett multiple_keys-fel.

Identifiering

tracio.getVisitorId()

Returnerar en Promise<string> som resolveras till den stabila besökaridentifieraren.

TypeScript

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

tracio.getResult()

Returnerar en Promise<TracioResult> med besökar-ID:t och resultatet av botdetekteringen.

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

Livscykel-callbacks

tracio.onReady(cb)

Anropas så snart agenten har laddats och producerat ett resultat.

TypeScript

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

tracio.onError(cb)

Anropas när SDK:t stöter på ett fel.

TypeScript

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

tracio.destroy()

River ner instansen och frigör resurser. Efterföljande anrop avvisas med ett destroyed-fel.

TypeScript

tracio.destroy()

Felhantering

SDK:t kastar TracioError-instanser med en typad code. Använd hjälpfunktionerna isTracioError och isRetryableError för att förgrena:

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

Felkoder

Unionen TracioErrorCode omfattar:

Kod	Beskrivning
`blocked`	Begäran blockerades (t.ex. av en annonsblockerare).
`destroyed`	Instansen förstördes innan anropet slutfördes.
`invalid_config`	Konfigurationen är ogiltig (t.ex. saknad `publicKey`).
`load_failed`	Agentskriptet kunde inte laddas.
`multiple_keys`	`Tracio.init()` anropades med en motstridig publik nyckel.
`network`	En nätverksbegäran misslyckades.
`non_browser`	SDK:t användes utanför en webbläsarmiljö.
`script_error`	Agentskriptet utlöste ett fel vid körning.
`server`	Servern returnerade ett fel.
`timeout`	Begäran överskred `timeoutMs`.

load_failed, blocked, script_error, network, timeout och server är återförsökbara; isRetryableError(error) returnerar true för dem.

Framework-integration

För React, Vue, Angular och Svelte, använd de dedikerade framework-paketen istället för att koppla ihop core-SDK:t för hand:

Vart och ett omsluter @tracio/sdk och exponerar idiomatiska primitiver (providers, plugins, hooks, composables och services). Se SDK-översikten för snuttar per framework.

Prestandaöverväganden

Icke-blockerande: Tracio.init() returnerar synkront och laddar agenten i bakgrunden. Den blockerar inte sidans rendering.
Enkel begäran: En begäran görs per identifiering.
Timeout: Identifieringen är begränsad av timeoutMs (standard 15000 ms), så ett långsamt nätverk låser aldrig din kod på obestämd tid.