Démarrage rapide

Ce guide vous accompagne pas à pas dans l'intégration de TRACIO à votre application. Vous installerez le SDK client, vous l'initialiserez avec votre clé publique et vous lirez votre premier résultat d'identification de visiteur.

Étape 1 : installez le SDK

Installez le SDK TRACIO avec votre gestionnaire de paquets préféré :

npm install @tracio/sdk

Ou avec pnpm :

pnpm add @tracio/sdk

Ou avec yarn :

yarn add @tracio/sdk

Snippet CDN sans build

Si vous n'utilisez pas de bundler, insérez la balise de script edge dans votre page. Elle s'auto-initialise avec la clé publique passée dans le paramètre de requête k.

Choisissez depuis où le script est chargé. Certains réseaux et certaines extensions de navigateur bloquent les requêtes vers les domaines d'analytique tiers : filtres d'entreprise, bloqueurs au niveau DNS, restrictions régionales, extensions de confidentialité. Servi depuis votre propre sous-domaine, le script est une requête de première partie sur votre site et continue de fonctionner dans ces environnements — voir Domaines personnalisés :

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

Ou chargez-le depuis le domaine edge partagé, le moyen le plus rapide de démarrer :

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

Étape 2 : initialisez le SDK

Importez Tracio et appelez Tracio.init() avec votre clé publique. Cela renvoie immédiatement une TracioInstance — l'agent sous-jacent se charge en arrière-plan.

import { Tracio } from "@tracio/sdk"

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

Votre clé publique peut être livrée sans risque dans le code côté client. Vous la trouverez dans votre tableau de bord, dans la section API Keys.

Options de configuration

Tracio.init() accepte un objet TracioConfig :

Étape 3 : obtenez un identifiant visiteur

Appelez tracio.getVisitorId() pour recevoir un identifiant visiteur stable. Il s'agit d'une opération asynchrone.

const visitorId = await tracio.getVisitorId()

console.log(visitorId) // "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

Étape 4 : lisez le résultat complet

Appelez tracio.getResult() pour recevoir le résultat d'identification complet, y compris la détection des bots.

const result = await tracio.getResult()

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

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

Le résultat a la forme suivante :

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

Étape 5 : cycle de vie et erreurs

Utilisez les callbacks de cycle de vie pour réagir lorsque l'agent est prêt ou lorsqu'une erreur survient, et destroy() pour démonter l'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()

Consultez Gestion des erreurs pour la liste complète des codes d'erreur et les helpers de nouvelle tentative.

Modèles d'intégration courants

Protection de la connexion

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

Prévention de la fraude au paiement

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

Étapes suivantes

• Comment ça marche — Comprenez le pipeline de collecte de signaux et d'identification
• Référence du SDK JavaScript — Documentation complète de l'API du SDK
• Webhooks — Recevez les événements d'identification sur votre serveur en temps réel
• Data API — Lisez les visiteurs, les sessions et la velocity depuis votre backend
• Détection des bots — Plongée en profondeur dans la détection de l'automatisation