SDK JavaScript

Le SDK JavaScript de TRACIO (@tracio/sdk) collecte les signaux du navigateur et les envoie au cloud TRACIO pour l'identification des visiteurs et la détection des bots. Il est léger, non bloquant et compatible avec tous les navigateurs modernes.

Installation

bash

npm install @tracio/sdk

Le package est fourni en builds ESM, CJS et IIFE avec des types TypeScript complets.

CDN

Il existe deux façons d'utiliser TRACIO depuis un CDN sans bundler.

Script edge (auto-init)

Le script edge s'initialise automatiquement à l'aide de la clé publique passée dans le paramètre de requête k. Aucun JavaScript requis :

HTML

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

Bundle npm (global IIFE)

Vous pouvez aussi charger le bundle npm publié depuis unpkg ou jsDelivr. Il expose un global TracioSDK. Épinglez une 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>

Initialisation

Tracio.init(config)

Initialise le SDK et retourne un TracioInstance de manière synchrone. L'agent se charge en arrière-plan ; les méthodes de l'instance se résolvent une fois qu'il est prêt.

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	Défaut	Description
`publicKey`	`string`	requis	Votre clé publique. Copiez-la depuis votre dashboard.
`region`	`"us" \| "eu"`	aucun	Région de données optionnelle. Non définie, le SDK utilise l'endpoint générique `https://edge.tracio.ai` (aucune résidence de données US implicite). Définissez-la explicitement pour épingler `us` ou `eu`.
`endpoint`	`string`	auto	Endpoint API personnalisé (pour un endpoint proxifié en first-party).
`scriptUrl`	`string`	auto	URL personnalisée du script de l'agent (pour un endpoint proxifié en first-party).
`linkedId`	`string`	aucun	Identifiant liant ce visiteur à une entité dans votre système.
`tag`	`string`	aucun	Étiquette libre attachée à la requête pour un filtrage ultérieur.
`debug`	`boolean`	`false`	Journalise des diagnostics détaillés dans la console.
`timeoutMs`	`number`	`15000`	Durée d'attente du résultat avant expiration.

Appeler Tracio.init() plus d'une fois avec une clé publique différente lève une erreur multiple_keys.

Identification

tracio.getVisitorId()

Retourne une Promise<string> qui se résout en l'identifiant visiteur stable.

TypeScript

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

tracio.getResult()

Retourne une Promise<TracioResult> avec le visitor ID et le résultat de détection des bots.

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[]
  }
}

Callbacks de cycle de vie

tracio.onReady(cb)

Invoqué une fois que l'agent s'est chargé et a produit un résultat.

TypeScript

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

tracio.onError(cb)

Invoqué lorsque le SDK rencontre une erreur.

TypeScript

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

tracio.destroy()

Démonte l'instance et libère les ressources. Les appels ultérieurs sont rejetés avec une erreur destroyed.

TypeScript

tracio.destroy()

Gestion des erreurs

Le SDK lève des instances TracioError avec un code typé. Utilisez les helpers isTracioError et isRetryableError pour brancher :

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

Codes d'erreur

L'union TracioErrorCode couvre :

Code	Description
`blocked`	La requête a été bloquée (par ex. par un ad blocker).
`destroyed`	L'instance a été détruite avant la fin de l'appel.
`invalid_config`	La configuration est invalide (par ex. `publicKey` manquante).
`load_failed`	Le script de l'agent n'a pas pu se charger.
`multiple_keys`	`Tracio.init()` a été appelé avec une clé publique en conflit.
`network`	Une requête réseau a échoué.
`non_browser`	Le SDK a été utilisé en dehors d'un environnement navigateur.
`script_error`	Le script de l'agent a levé une erreur à l'exécution.
`server`	Le serveur a renvoyé une erreur.
`timeout`	La requête a dépassé `timeoutMs`.

load_failed, blocked, script_error, network, timeout et server sont réessayables ; isRetryableError(error) retourne true pour ces cas.

Intégration avec les frameworks

Pour React, Vue, Angular et Svelte, utilisez les packages de framework dédiés plutôt que de câbler le SDK cœur à la main :

Chacun encapsule @tracio/sdk et expose des primitives idiomatiques (providers, plugins, hooks, composables et services). Consultez la vue d'ensemble des SDKs pour les extraits par framework.

Considérations de performance

Non bloquant : Tracio.init() retourne de manière synchrone et charge l'agent en arrière-plan. Il ne bloque pas le rendu de la page.
Requête unique : une seule requête est effectuée par identification.
Timeout : l'identification est bornée par timeoutMs (15000 ms par défaut), de sorte qu'un réseau lent ne bloque jamais votre code indéfiniment.

SDK JavaScript

Installation

bash

npm install @tracio/sdk

Le package est fourni en builds ESM, CJS et IIFE avec des types TypeScript complets.

CDN

Il existe deux façons d'utiliser TRACIO depuis un CDN sans bundler.

Script edge (auto-init)

Le script edge s'initialise automatiquement à l'aide de la clé publique passée dans le paramètre de requête k. Aucun JavaScript requis :

HTML

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

Bundle npm (global IIFE)

Vous pouvez aussi charger le bundle npm publié depuis unpkg ou jsDelivr. Il expose un global TracioSDK. Épinglez une 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>

Initialisation

Tracio.init(config)

Initialise le SDK et retourne un TracioInstance de manière synchrone. L'agent se charge en arrière-plan ; les méthodes de l'instance se résolvent une fois qu'il est prêt.

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	Défaut	Description
`publicKey`	`string`	requis	Votre clé publique. Copiez-la depuis votre dashboard.
`region`	`"us" \| "eu"`	aucun	Région de données optionnelle. Non définie, le SDK utilise l'endpoint générique `https://edge.tracio.ai` (aucune résidence de données US implicite). Définissez-la explicitement pour épingler `us` ou `eu`.
`endpoint`	`string`	auto	Endpoint API personnalisé (pour un endpoint proxifié en first-party).
`scriptUrl`	`string`	auto	URL personnalisée du script de l'agent (pour un endpoint proxifié en first-party).
`linkedId`	`string`	aucun	Identifiant liant ce visiteur à une entité dans votre système.
`tag`	`string`	aucun	Étiquette libre attachée à la requête pour un filtrage ultérieur.
`debug`	`boolean`	`false`	Journalise des diagnostics détaillés dans la console.
`timeoutMs`	`number`	`15000`	Durée d'attente du résultat avant expiration.

Appeler Tracio.init() plus d'une fois avec une clé publique différente lève une erreur multiple_keys.

Identification

tracio.getVisitorId()

Retourne une Promise<string> qui se résout en l'identifiant visiteur stable.

TypeScript

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

tracio.getResult()

Retourne une Promise<TracioResult> avec le visitor ID et le résultat de détection des bots.

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[]
  }
}

Callbacks de cycle de vie

tracio.onReady(cb)

Invoqué une fois que l'agent s'est chargé et a produit un résultat.

TypeScript

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

tracio.onError(cb)

Invoqué lorsque le SDK rencontre une erreur.

TypeScript

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

tracio.destroy()

Démonte l'instance et libère les ressources. Les appels ultérieurs sont rejetés avec une erreur destroyed.

TypeScript

tracio.destroy()

Gestion des erreurs

Le SDK lève des instances TracioError avec un code typé. Utilisez les helpers isTracioError et isRetryableError pour brancher :

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

Codes d'erreur

L'union TracioErrorCode couvre :

Code	Description
`blocked`	La requête a été bloquée (par ex. par un ad blocker).
`destroyed`	L'instance a été détruite avant la fin de l'appel.
`invalid_config`	La configuration est invalide (par ex. `publicKey` manquante).
`load_failed`	Le script de l'agent n'a pas pu se charger.
`multiple_keys`	`Tracio.init()` a été appelé avec une clé publique en conflit.
`network`	Une requête réseau a échoué.
`non_browser`	Le SDK a été utilisé en dehors d'un environnement navigateur.
`script_error`	Le script de l'agent a levé une erreur à l'exécution.
`server`	Le serveur a renvoyé une erreur.
`timeout`	La requête a dépassé `timeoutMs`.

load_failed, blocked, script_error, network, timeout et server sont réessayables ; isRetryableError(error) retourne true pour ces cas.

Intégration avec les frameworks

Pour React, Vue, Angular et Svelte, utilisez les packages de framework dédiés plutôt que de câbler le SDK cœur à la main :

Chacun encapsule @tracio/sdk et expose des primitives idiomatiques (providers, plugins, hooks, composables et services). Consultez la vue d'ensemble des SDKs pour les extraits par framework.

Considérations de performance

Non bloquant : Tracio.init() retourne de manière synchrone et charge l'agent en arrière-plan. Il ne bloque pas le rendu de la page.
Requête unique : une seule requête est effectuée par identification.
Timeout : l'identification est bornée par timeoutMs (15000 ms par défaut), de sorte qu'un réseau lent ne bloque jamais votre code indéfiniment.