Quick Start

Install the @tracio/client SDK and generate your first visitor fingerprint in 5 minutes

This guide walks you through integrating tracio.ai into your application. You will install the client SDK, identify your first visitor, and verify the result via our API.

Step 1: Install the SDK

Install the tracio.ai client library using your preferred package manager:

npm install @tracio/client

Or with yarn:

yarn add @tracio/client

Or include directly via CDN:

<script src="https://your-domain.com/tracio-client.js"></script>

Step 2: Initialize the Agent

Import and initialize the tracio.ai agent with your API key. The load() call returns a promise that resolves once the agent is ready to collect signals.

import Tracio from '@tracio/client';
// Initialize the agent
const tracio = await Tracio.load({
  apiKey: 'your-api-key',
  endpoint: 'https://api.tracio.ai',
  region: 'eu',
});

Configuration Options

Step 3: Identify a Visitor

Call tracio.get() to collect browser signals and receive a visitor identification result. This is an asynchronous operation that takes approximately 50-150ms.

const result = await tracio.get();
console.log(result.visitorId);  // "X7fh2Hg9LkMn3pQr"
console.log(result.confidence); // 0.995
console.log(result.requestId);  // "1710432000_abc123def"

Extended Results

Pass extendedResult: true to receive additional visitor metadata including bot detection, IP intelligence, and smart signals:

const result = await tracio.get({ extendedResult: true });
console.log(result.visitorId);               // "X7fh2Hg9LkMn3pQr"
console.log(result.bot.result);              // "notDetected"
console.log(result.ipLocation.city.name);    // "Prague"
console.log(result.incognito);               // false

Tagging Requests

You can attach metadata to identification requests for later filtering:

const result = await tracio.get({
  tag: {
    userId: 'user_12345',
    action: 'login',
  },
  linkedId: 'session_abc',
});

Step 4: Server-Side Verification

For security-critical operations (login, payment, account creation), always verify the identification result on your server. Never trust client-side data alone.

Option A: Server API Lookup

Query the Server API with the requestId to retrieve the full identification result:

// Server-side (Node.js)
const response = await fetch(
  `https://api.tracio.ai/api/v1/events/${requestId}`,
  {
    headers: {
      'Authorization': `Bearer ${API_SECRET}`,
    },
  }
);
const event = await response.json();
// Verify the visitor
const visitorId = event.products.identification.data.visitorId;
const confidence = event.products.identification.data.confidence.score;
const isBot = event.products.botd.data.bot.result !== 'notDetected';
if (isBot) {
  return res.status(403).json({ error: 'Bot detected' });
}
if (confidence < 0.9) {
  return res.status(401).json({ error: 'Low confidence, please verify' });
}

Option B: Webhook Verification

Configure a webhook to receive identification events in real-time:

// Express.js webhook handler
app.post('/webhook/tracio', async (req, res) => {
  const event = req.body;
  const visitorId = event.visitorId;
  const requestId = event.requestId;
  const bot = event.bot;
  console.log(`Visitor ${visitorId} identified (request: ${requestId})`);
  await db.visits.insert({
    visitorId,
    requestId,
    timestamp: new Date(),
    isBot: bot.result !== 'notDetected',
    confidence: event.confidence.score,
  });
  res.status(200).send('OK');
});

Step 5: Test Your Integration

Open your browser's developer console and verify the integration is working:

const tracio = await Tracio.load({ apiKey: 'your-api-key' });
const result = await tracio.get({ extendedResult: true });
console.log(JSON.stringify(result, null, 2));

You should see a response containing:

• visitorId — a 16-20 character alphanumeric identifier
• confidence — a score between 0.0 and 1.0 (typically above 0.99)
• requestId — a unique identifier for this event
• bot — bot detection result
• ipLocation — geolocation data derived from the visitor's IP

Common Integration Patterns

Login Protection

async function handleLogin(email: string, password: string) {
  const tracio = await Tracio.load({ apiKey: 'your-api-key' });
  const { visitorId, requestId } = await tracio.get();
  const response = await fetch('/api/login', {
    method: 'POST',
    body: JSON.stringify({ email, password, visitorId, requestId }),
  });
  return response.json();
}

Payment Fraud Prevention

async function processPayment(paymentData: PaymentData) {
  const tracio = await Tracio.load({ apiKey: 'your-api-key' });
  const result = await tracio.get({
    tag: { action: 'payment', amount: paymentData.amount },
    linkedId: paymentData.orderId,
  });
  const response = await fetch('/api/payment', {
    method: 'POST',
    body: JSON.stringify({
      ...paymentData,
      visitorId: result.visitorId,
      requestId: result.requestId,
    }),
  });
  return response.json();
}

Server-Side Verification with Go

Use the official Go SDK to verify identification results on your server:

Install the Go Server SDK

go get github.com/tracio-ai/tracio-go

Verify Events in Go

package main
import (
    "fmt"
    "log"
    tracio "github.com/tracio-ai/tracio-go"
)
func main() {
    client := tracio.NewClient("your-secret-key")
    event, err := client.GetEvent(requestID)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Visitor: %s, Confidence: %.3f\n",
        event.VisitorID, event.Confidence)
}

Server-Side Verification with Rust

Use the Rust SDK for high-performance server-side verification:

Add to Cargo.toml

[dependencies]
tracio = "0.1"
tokio = { version = "1", features = ["full"] }

Verify Events in Rust

use tracio::Client;
#[tokio::main]
async fn main() {
    let client = Client::new("your-secret-key");
    let event = client.get_event(request_id).await.unwrap();
    println!("Visitor: {}, Confidence: {:.3}",
        event.visitor_id, event.confidence);
}

Verify with cURL

Test the Server API directly from your terminal:

curl https://api.tracio.ai/v1/events/YOUR_REQUEST_ID \
  -H "Auth-API-Key: your-secret-key"

Troubleshooting

Build errors?

Ensure your Go version is 1.21 or later. Run go version to check. For Rust, ensure you have Rust 1.70+ with rustc --version.

TLS errors?

If you see TLS handshake failures, configure a proxy endpoint using your own domain. See Cloudflare or AWS CloudFront integration guides for first-party proxy setup.

Low signal count?

Enable async collection mode by setting extendedResult: true in your tracio.get() call. This enables all 1,200+ signal collectors including canvas, WebGL, and audio probes that require asynchronous rendering.

Docker deployment?

See the self-hosting documentation for Docker Compose templates, environment variable reference, and production configuration guides.

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