JavaScript SDK

The TRACIO JavaScript SDK (@tracio/sdk) collects browser signals and sends them to the TRACIO cloud for visitor identification and bot detection. It is lightweight, non-blocking, and compatible with all modern browsers.

Installation

bash

npm install @tracio/sdk

The package ships ESM, CJS, and IIFE builds with full TypeScript types.

CDN

There are two ways to use TRACIO from a CDN without a bundler.

Edge script (auto-init)

The edge script auto-initializes using the public key in the k query parameter. No JavaScript required:

HTML

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

npm bundle (IIFE global)

You can also load the published npm bundle from unpkg or jsDelivr. It exposes a TracioSDK global. Pin a 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>

Initialization

Tracio.init(config)

Initializes the SDK and returns a TracioInstance synchronously. The agent loads in the background; the instance methods resolve once it is ready.

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	Type	Default	Description
`publicKey`	`string`	required	Your public key. Copy it from your dashboard.
`region`	`"us" \| "eu"`	none	Optional data region. When unset, the SDK uses the generic `https://edge.tracio.ai` endpoint (no implied US data residency). Set it explicitly to pin `us` or `eu`.
`endpoint`	`string`	auto	Custom API endpoint (for self-hosted deployments).
`scriptUrl`	`string`	auto	Custom URL for the agent script (for self-hosted deployments).
`linkedId`	`string`	none	Identifier linking this visitor to an entity in your system.
`tag`	`string`	none	Free-form label attached to the request for later filtering.
`debug`	`boolean`	`false`	Logs verbose diagnostics to the console.
`timeoutMs`	`number`	`15000`	How long to wait for the result before timing out.

Calling Tracio.init() more than once with a different public key throws a multiple_keys error.

Identification

tracio.getVisitorId()

Returns a Promise<string> that resolves to the stable visitor identifier.

TypeScript

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

tracio.getResult()

Returns a Promise<TracioResult> with the visitor ID and bot detection result.

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)

Invoked once the agent has loaded and produced a result.

TypeScript

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

tracio.onError(cb)

Invoked when the SDK encounters an error.

TypeScript

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

tracio.destroy()

Tears down the instance and releases resources. Subsequent calls reject with a destroyed error.

TypeScript

tracio.destroy()

Error Handling

The SDK throws TracioError instances with a typed code. Use the isTracioError and isRetryableError helpers to branch:

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

Error Codes

The TracioErrorCode union covers:

Code	Description
`blocked`	The request was blocked (e.g. by an ad blocker).
`destroyed`	The instance was destroyed before the call completed.
`invalid_config`	The configuration is invalid (e.g. missing `publicKey`).
`load_failed`	The agent script failed to load.
`multiple_keys`	`Tracio.init()` was called with a conflicting public key.
`network`	A network request failed.
`non_browser`	The SDK was used outside a browser environment.
`script_error`	The agent script raised an error at runtime.
`server`	The server returned an error.
`timeout`	The request exceeded `timeoutMs`.

load_failed, blocked, script_error, network, timeout, and server are retryable; isRetryableError(error) returns true for them.

Framework Integration

For React, Vue, Angular, and Svelte, use the dedicated framework packages instead of wiring up the core SDK by hand:

Each wraps @tracio/sdk and exposes idiomatic primitives (providers, plugins, hooks, composables, and services). See the SDKs overview for per-framework snippets.

Performance Considerations

Non-blocking: Tracio.init() returns synchronously and loads the agent in the background. It does not block page rendering.
Single request: One request is made per identification.
Timeout: Identification is bounded by timeoutMs (default 15000ms), so a slow network never hangs your code indefinitely.

JavaScript SDK

Installation

bash

npm install @tracio/sdk

The package ships ESM, CJS, and IIFE builds with full TypeScript types.

CDN

There are two ways to use TRACIO from a CDN without a bundler.

Edge script (auto-init)

The edge script auto-initializes using the public key in the k query parameter. No JavaScript required:

HTML

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

npm bundle (IIFE global)

You can also load the published npm bundle from unpkg or jsDelivr. It exposes a TracioSDK global. Pin a 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>

Initialization

Tracio.init(config)

Initializes the SDK and returns a TracioInstance synchronously. The agent loads in the background; the instance methods resolve once it is ready.

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	Type	Default	Description
`publicKey`	`string`	required	Your public key. Copy it from your dashboard.
`region`	`"us" \| "eu"`	none	Optional data region. When unset, the SDK uses the generic `https://edge.tracio.ai` endpoint (no implied US data residency). Set it explicitly to pin `us` or `eu`.
`endpoint`	`string`	auto	Custom API endpoint (for self-hosted deployments).
`scriptUrl`	`string`	auto	Custom URL for the agent script (for self-hosted deployments).
`linkedId`	`string`	none	Identifier linking this visitor to an entity in your system.
`tag`	`string`	none	Free-form label attached to the request for later filtering.
`debug`	`boolean`	`false`	Logs verbose diagnostics to the console.
`timeoutMs`	`number`	`15000`	How long to wait for the result before timing out.

Calling Tracio.init() more than once with a different public key throws a multiple_keys error.

Identification

tracio.getVisitorId()

Returns a Promise<string> that resolves to the stable visitor identifier.

TypeScript

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

tracio.getResult()

Returns a Promise<TracioResult> with the visitor ID and bot detection result.

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)

Invoked once the agent has loaded and produced a result.

TypeScript

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

tracio.onError(cb)

Invoked when the SDK encounters an error.

TypeScript

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

tracio.destroy()

Tears down the instance and releases resources. Subsequent calls reject with a destroyed error.

TypeScript

tracio.destroy()

Error Handling

The SDK throws TracioError instances with a typed code. Use the isTracioError and isRetryableError helpers to branch:

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

Error Codes

The TracioErrorCode union covers:

Code	Description
`blocked`	The request was blocked (e.g. by an ad blocker).
`destroyed`	The instance was destroyed before the call completed.
`invalid_config`	The configuration is invalid (e.g. missing `publicKey`).
`load_failed`	The agent script failed to load.
`multiple_keys`	`Tracio.init()` was called with a conflicting public key.
`network`	A network request failed.
`non_browser`	The SDK was used outside a browser environment.
`script_error`	The agent script raised an error at runtime.
`server`	The server returned an error.
`timeout`	The request exceeded `timeoutMs`.

load_failed, blocked, script_error, network, timeout, and server are retryable; isRetryableError(error) returns true for them.

Framework Integration

For React, Vue, Angular, and Svelte, use the dedicated framework packages instead of wiring up the core SDK by hand:

Each wraps @tracio/sdk and exposes idiomatic primitives (providers, plugins, hooks, composables, and services). See the SDKs overview for per-framework snippets.

Performance Considerations

Non-blocking: Tracio.init() returns synchronously and loads the agent in the background. It does not block page rendering.
Single request: One request is made per identification.
Timeout: Identification is bounded by timeoutMs (default 15000ms), so a slow network never hangs your code indefinitely.