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

Lifecycle-колбеки

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 мс), тож повільна мережа ніколи не заблокує ваш код на невизначений час.