Quick Start

This guide walks you through integrating TRACIO into your application. You will install the client SDK, initialize it with your public key, and read your first visitor identification result.

Step 1: Install the SDK

Install the TRACIO SDK using your preferred package manager:

bash

npm install @tracio/sdk

Or with pnpm:

bash

pnpm add @tracio/sdk

Or with yarn:

bash

yarn add @tracio/sdk

Zero-build CDN snippet

If you don't use a bundler, drop the edge script tag into your page. It auto-initializes with the public key in the k query parameter:

HTML

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

Step 2: Initialize the SDK

Import Tracio and call Tracio.init() with your public key. This returns a TracioInstance immediately — the underlying agent loads in the background.

TypeScript

import { Tracio } from "@tracio/sdk"

const tracio = Tracio.init({
  publicKey: "5ca175fc...",
})

Your public key is safe to ship in client-side code. You can find it in your dashboard under API Keys.

Configuration Options

Tracio.init() accepts a TracioConfig object:

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.

Step 3: Get a Visitor ID

Call tracio.getVisitorId() to receive a stable visitor identifier. This is an asynchronous operation.

TypeScript

const visitorId = await tracio.getVisitorId()

console.log(visitorId) // "X7fh2Hg9LkMn3pQr"

Step 4: Read the Full Result

Call tracio.getResult() to receive the full identification result, including bot detection.

TypeScript

const result = await tracio.getResult()

console.log(result.visitorId) // "X7fh2Hg9LkMn3pQr"

if (result.bot.detected) {
  console.warn("bot, confidence:", result.bot.confidence)
}

The result has the shape:

TypeScript

{
  visitorId: "X7fh2Hg9LkMn3pQr",
  bot: {
    detected: false,
    confidence: 2,        // 0-100
    reasons: [],
  },
}

Step 5: Lifecycle and Errors

Use the lifecycle callbacks to react when the agent is ready or when something fails, and destroy() to tear down the instance:

TypeScript

const tracio = Tracio.init({ publicKey: "5ca175fc..." })

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

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

// later, when you no longer need it
tracio.destroy()

See Error Handling for the full list of error codes and retry helpers.

Common Integration Patterns

TypeScript

import { Tracio } from "@tracio/sdk"

const tracio = Tracio.init({ publicKey: "5ca175fc..." })

async function handleLogin(email: string, password: string) {
  const visitorId = await tracio.getVisitorId()

  const response = await fetch("/api/login", {
    method: "POST",
    body: JSON.stringify({ email, password, visitorId }),
  })

  return response.json()
}

Payment Fraud Prevention

TypeScript

import { Tracio } from "@tracio/sdk"

const tracio = Tracio.init({
  publicKey: "5ca175fc...",
  tag: "payment",
})

async function processPayment(paymentData: PaymentData) {
  const result = await tracio.getResult()

  if (result.bot.detected) {
    throw new Error("Automated client detected")
  }

  const response = await fetch("/api/payment", {
    method: "POST",
    body: JSON.stringify({ ...paymentData, visitorId: result.visitorId }),
  })

  return response.json()
}

Next Steps

How It Works — Understand the signal collection and identification pipeline
JavaScript SDK Reference — Full SDK API documentation
Server API Reference — Query events and manage visitors
Bot Detection — Deep dive into automation detection

Quick Start

This guide walks you through integrating TRACIO into your application. You will install the client SDK, initialize it with your public key, and read your first visitor identification result.

Step 1: Install the SDK

Install the TRACIO SDK using your preferred package manager:

bash

npm install @tracio/sdk

Or with pnpm:

bash

pnpm add @tracio/sdk

Or with yarn:

bash

yarn add @tracio/sdk

Zero-build CDN snippet

If you don't use a bundler, drop the edge script tag into your page. It auto-initializes with the public key in the k query parameter:

HTML

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

Step 2: Initialize the SDK

Import Tracio and call Tracio.init() with your public key. This returns a TracioInstance immediately — the underlying agent loads in the background.

TypeScript

import { Tracio } from "@tracio/sdk"

const tracio = Tracio.init({
  publicKey: "5ca175fc...",
})

Your public key is safe to ship in client-side code. You can find it in your dashboard under API Keys.

Configuration Options

Tracio.init() accepts a TracioConfig object:

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.

Step 3: Get a Visitor ID

Call tracio.getVisitorId() to receive a stable visitor identifier. This is an asynchronous operation.

TypeScript

const visitorId = await tracio.getVisitorId()

console.log(visitorId) // "X7fh2Hg9LkMn3pQr"

Step 4: Read the Full Result

Call tracio.getResult() to receive the full identification result, including bot detection.

TypeScript

const result = await tracio.getResult()

console.log(result.visitorId) // "X7fh2Hg9LkMn3pQr"

if (result.bot.detected) {
  console.warn("bot, confidence:", result.bot.confidence)
}

The result has the shape:

TypeScript

{
  visitorId: "X7fh2Hg9LkMn3pQr",
  bot: {
    detected: false,
    confidence: 2,        // 0-100
    reasons: [],
  },
}

Step 5: Lifecycle and Errors

Use the lifecycle callbacks to react when the agent is ready or when something fails, and destroy() to tear down the instance:

TypeScript

const tracio = Tracio.init({ publicKey: "5ca175fc..." })

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

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

// later, when you no longer need it
tracio.destroy()

See Error Handling for the full list of error codes and retry helpers.

Common Integration Patterns

TypeScript

import { Tracio } from "@tracio/sdk"

const tracio = Tracio.init({ publicKey: "5ca175fc..." })

async function handleLogin(email: string, password: string) {
  const visitorId = await tracio.getVisitorId()

  const response = await fetch("/api/login", {
    method: "POST",
    body: JSON.stringify({ email, password, visitorId }),
  })

  return response.json()
}

Payment Fraud Prevention

TypeScript

import { Tracio } from "@tracio/sdk"

const tracio = Tracio.init({
  publicKey: "5ca175fc...",
  tag: "payment",
})

async function processPayment(paymentData: PaymentData) {
  const result = await tracio.getResult()

  if (result.bot.detected) {
    throw new Error("Automated client detected")
  }

  const response = await fetch("/api/payment", {
    method: "POST",
    body: JSON.stringify({ ...paymentData, visitorId: result.visitorId }),
  })

  return response.json()
}

Next Steps

How It Works — Understand the signal collection and identification pipeline
JavaScript SDK Reference — Full SDK API documentation
Server API Reference — Query events and manage visitors
Bot Detection — Deep dive into automation detection

Quick Start

Step 1: Install the SDK

Zero-build CDN snippet

Step 2: Initialize the SDK

Configuration Options

Step 3: Get a Visitor ID

Step 4: Read the Full Result

Step 5: Lifecycle and Errors

Common Integration Patterns

Login Protection

Payment Fraud Prevention

Next Steps

Quick Start

Step 1: Install the SDK

Zero-build CDN snippet

Step 2: Initialize the SDK

Configuration Options

Step 3: Get a Visitor ID

Step 4: Read the Full Result

Step 5: Lifecycle and Errors

Common Integration Patterns

Login Protection

Payment Fraud Prevention

Next Steps