JavaScript SDK

TRACIO JavaScript SDK (@tracio/sdk) собирает сигналы браузера и отправляет их в облако TRACIO для идентификации посетителей и обнаружения ботов. Он легковесный, неблокирующий и совместим со всеми современными браузерами.

Установка

npm install @tracio/sdk

Пакет поставляется в сборках ESM, CJS и IIFE с полными типами TypeScript.

CDN

Есть два способа использовать TRACIO с CDN без сборщика.

Edge-скрипт (авто-инициализация)

Edge-скрипт инициализируется автоматически, используя публичный ключ из query-параметра k. JavaScript не требуется:

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

npm-бандл (глобальный объект IIFE)

Вы также можете загрузить опубликованный npm-бандл с unpkg или jsDelivr. Он предоставляет глобальный объект TracioSDK. Зафиксируйте версию:

<script src="https://unpkg.com/@tracio/sdk@0.1.3/dist/index.min.js"></script>
<script>
  const tracio = TracioSDK.Tracio.init({ publicKey: "5ca175fc..." })
</script>

Инициализация

Tracio.init(config)

Инициализирует SDK и синхронно возвращает TracioInstance. Агент загружается в фоне; методы экземпляра разрешаются, как только он будет готов.

import { Tracio } from "@tracio/sdk"

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

TracioConfig

interface TracioConfig {
  publicKey: string // required
  region?: "us" | "eu"
  endpoint?: string
  scriptUrl?: string
  linkedId?: string
  tag?: string
  debug?: boolean
  timeoutMs?: number // default 15000
}

Повторный вызов Tracio.init() с другим публичным ключом выбрасывает ошибку multiple_keys.

Идентификация

tracio.getVisitorId()

Возвращает Promise<string>, который разрешается в стабильный идентификатор посетителя.

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

tracio.getResult()

Возвращает Promise<TracioResult> с идентификатором посетителя и результатом обнаружения ботов.

const result = await tracio.getResult()

console.log(result.visitorId)

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

TracioResult

interface TracioResult {
  visitorId: string
  bot: {
    detected: boolean
    confidence: number // 0-100
    reasons?: string[]
  }
}

Колбэки жизненного цикла

tracio.onReady(cb)

Вызывается, как только агент загрузился и сформировал результат.

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

tracio.onError(cb)

Вызывается, когда SDK сталкивается с ошибкой.

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

tracio.destroy()

Разбирает экземпляр и освобождает ресурсы. Последующие вызовы отклоняются с ошибкой destroyed.

tracio.destroy()

Обработка ошибок

SDK выбрасывает экземпляры TracioError с типизированным code. Используйте помощники isTracioError и isRetryableError для ветвления:

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

Коды ошибок

Объединение TracioErrorCode включает:

load_failed, blocked, script_error, network, timeout и server можно повторять; isRetryableError(error) возвращает для них true.

Интеграция с фреймворками

Для React, Vue, Angular и Svelte используйте специализированные пакеты для фреймворков вместо ручной обвязки основного SDK:

• @tracio/react
• @tracio/vue
• @tracio/angular
• @tracio/svelte

Каждый оборачивает @tracio/sdk и предоставляет идиоматичные примитивы (провайдеры, плагины, хуки, composables и сервисы). Сниппеты для каждого фреймворка см. в обзоре SDK.

Соображения производительности

• Неблокирующий: Tracio.init() возвращается синхронно и загружает агент в фоне. Он не блокирует рендеринг страницы.
• Единственный запрос: На одну идентификацию делается один запрос.
• Тайм-аут: Идентификация ограничена timeoutMs (по умолчанию 15000 мс), поэтому медленная сеть никогда не подвесит ваш код на неопределённый срок.