이 가이드는 TRACIO를 애플리케이션에 통합하는 과정을 단계별로 안내합니다. 클라이언트 SDK를 설치하고, 퍼블릭 키로 초기화한 뒤, 첫 번째 방문자 식별 결과를 읽어 봅니다.
선호하는 패키지 매니저로 TRACIO SDK를 설치하세요:
npm install @tracio/sdk또는 pnpm으로:
pnpm add @tracio/sdk또는 yarn으로:
yarn add @tracio/sdk번들러를 사용하지 않는 경우, 에지 스크립트 태그를 페이지에 삽입하세요. k 쿼리 파라미터의 퍼블릭 키로 자동 초기화됩니다:
<script src="https://edge.tracio.ai/s.js?k=PUBLIC_KEY" async></script>Tracio를 임포트하고 퍼블릭 키와 함께 Tracio.init()을 호출하세요. 이 호출은 즉시 TracioInstance를 반환하며, 기반 에이전트는 백그라운드에서 로드됩니다.
import { Tracio } from "@tracio/sdk"
const tracio = Tracio.init({ publicKey: "5ca175fc...",})퍼블릭 키는 클라이언트 측 코드에 포함해 배포해도 안전합니다. 대시보드의 API Keys에서 확인할 수 있습니다.
Tracio.init()은 TracioConfig 객체를 받습니다:
| 옵션 | 타입 | 기본값 | 설명 |
|---|---|---|---|
publicKey | string | 필수 | 퍼블릭 키. 대시보드에서 복사하세요. |
region | "us" | "eu" | 없음 | 선택적 데이터 리전. 지정하지 않으면 SDK는 일반 https://edge.tracio.ai 엔드포인트를 사용합니다(미국 데이터 레지던시를 암시하지 않음). us 또는 eu로 명시적으로 고정하세요. |
endpoint | string | 자동 | 사용자 지정 API 엔드포인트(퍼스트파티 프록시 엔드포인트용). |
scriptUrl | string | 자동 | 에이전트 스크립트의 사용자 지정 URL(퍼스트파티 프록시 엔드포인트용). |
linkedId | string | 없음 | 이 방문자를 시스템 내 엔터티와 연결하는 식별자. |
tag | string | 없음 | 나중에 필터링하기 위해 요청에 첨부되는 자유 형식 라벨. |
debug | boolean | false | 상세 진단 정보를 콘솔에 기록합니다. |
timeoutMs | number | 15000 | 타임아웃되기 전까지 결과를 기다리는 시간. |
tracio.getVisitorId()를 호출하여 안정적인 방문자 식별자를 받으세요. 이는 비동기 작업입니다.
const visitorId = await tracio.getVisitorId()
console.log(visitorId) // "X7fh2Hg9LkMn3pQr"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: [], },}라이프사이클 콜백을 사용하여 에이전트가 준비되거나 문제가 발생했을 때 반응하고, 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 ittracio.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()}