Быстрый старт

Это руководство проведёт вас через интеграцию TRACIO в ваше приложение. Вы установите клиентский SDK, инициализируете его вашим публичным ключом и прочитаете первый результат идентификации посетителя.

Шаг 1: Установите SDK

Установите TRACIO SDK с помощью предпочитаемого менеджера пакетов:

npm install @tracio/sdk

Или через pnpm:

pnpm add @tracio/sdk

Или через yarn:

yarn add @tracio/sdk

CDN-сниппет без сборки

Если вы не используете бандлер, добавьте на страницу тег edge-скрипта. Он автоматически инициализируется публичным ключом из query-параметра k:

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

Шаг 2: Инициализируйте SDK

Импортируйте Tracio и вызовите Tracio.init() с вашим публичным ключом. Это сразу возвращает TracioInstance — базовый агент загружается в фоне.

import { Tracio } from "@tracio/sdk"

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

Ваш публичный ключ можно безопасно поставлять в клиентском коде. Найти его можно в вашей панели управления в разделе API Keys.

Параметры конфигурации

Tracio.init() принимает объект TracioConfig:

Шаг 3: Получите идентификатор посетителя

Вызовите tracio.getVisitorId(), чтобы получить стабильный идентификатор посетителя. Это асинхронная операция.

const visitorId = await tracio.getVisitorId()

console.log(visitorId) // "X7fh2Hg9LkMn3pQr"

Шаг 4: Прочитайте полный результат

Вызовите tracio.getResult(), чтобы получить полный результат идентификации, включая обнаружение ботов.

const result = await tracio.getResult()

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

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

Результат имеет вид:

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

Шаг 5: Жизненный цикл и ошибки

Используйте колбэки жизненного цикла, чтобы реагировать, когда агент готов или что-то не удалось, и destroy(), чтобы разобрать экземпляр:

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

См. Обработку ошибок для полного списка кодов ошибок и хелперов повторных попыток.

Типичные паттерны интеграции

Защита входа в систему

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

Предотвращение платёжного мошенничества

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

Дальнейшие шаги

• Как это работает — Разберитесь в конвейере сбора сигналов и идентификации
• Справочник по JavaScript SDK — Полная документация по API SDK
• Вебхуки — Получайте события идентификации на вашем сервере в реальном времени
• Обнаружение ботов — Глубокое погружение в обнаружение автоматизации