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:

npm install @tracio/sdk

Or with pnpm:

pnpm add @tracio/sdk

Or with yarn:

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.

Choose where the script loads from. Some networks and browser extensions block requests to third-party analytics domains: corporate filters, DNS-level blockers, regional restrictions, privacy extensions. Served from your own subdomain, the script is a first-party request on your site and keeps working in those environments — see Custom Domains:

<script src="https://metrics.yoursite.com/s.js?k=PUBLIC_KEY" async></script>

Or load it from the shared edge domain, the fastest way to start:

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

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:

Step 3: Get a Visitor ID

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

const visitorId = await tracio.getVisitorId()

console.log(visitorId) // "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

Step 4: Read the Full Result

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

const result = await tracio.getResult()

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

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

The result has the shape:

{
  visitorId: "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  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:

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

Login Protection

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

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
• Webhooks — Receive identification events on your server in real time
• Data API — Read visitors, sessions and velocity from your backend
• Bot Detection — Deep dive into automation detection