이 가이드는 TRACIO를 애플리케이션에 통합하는 과정을 단계별로 안내합니다. 클라이언트 SDK를 설치하고, 퍼블릭 키로 초기화한 뒤, 첫 번째 방문자 식별 결과를 읽어 봅니다.
선호하는 패키지 매니저로 TRACIO SDK를 설치하세요:
npm install @tracio/sdk또는 pnpm으로:
pnpm add @tracio/sdk또는 yarn으로:
yarn add @tracio/sdk번들러를 사용하지 않는 경우, 에지 스크립트 태그를 페이지에 삽입하세요. k 쿼리 파라미터의 퍼블릭 키로 자동 초기화됩니다.
스크립트를 어디에서 로드할지 선택하세요. 일부 네트워크와 브라우저 확장 프로그램은 서드파티 분석 도메인으로의 요청을 차단합니다. 기업 필터, DNS 수준 차단기, 지역 제한, 개인정보 보호 확장 프로그램이 그렇습니다. 자체 서브도메인에서 제공하면 스크립트는 사이트의 퍼스트파티 요청이 되어 그러한 환경에서도 계속 동작합니다. 커스텀 도메인을 참고하세요:
<script src="https://metrics.yoursite.com/s.js?k=PUBLIC_KEY" async></script>또는 공유 에지 도메인에서 로드하세요. 가장 빠르게 시작하는 방법입니다:
<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를 설정하면 무시됩니다. |
endpoint | string | 자동 | https://metrics.yoursite.com과 같은 자체 서브도메인의 오리진. 스크립트와 신호가 여기에서 제공됩니다. 커스텀 도메인을 참고하세요. |
scriptUrl | string | 자동 | 에이전트 스크립트의 전체 URL. 퍼블릭 키를 포함한 URL 전체를 대체하므로, 커스텀 도메인에는 endpoint를 사용하세요. |
linkedId | string | 없음 | 이 방문자를 시스템 내 엔터티와 연결하는 식별자. 계정 연결을 참고하세요. |
tag | string | 없음 | 나중에 필터링하기 위해 요청에 첨부되는 자유 형식 라벨. |
debug | boolean | false | 상세 진단 정보를 콘솔에 기록합니다. |
timeoutMs | number | 15000 | 타임아웃되기 전까지 결과를 기다리는 시간. |
tracio.getVisitorId()를 호출하여 안정적인 방문자 식별자를 받으세요. 이는 비동기 작업입니다.
const visitorId = await tracio.getVisitorId()
console.log(visitorId) // "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"tracio.getResult()를 호출하여 봇 탐지를 포함한 전체 식별 결과를 받으세요.
const result = await tracio.getResult()
console.log(result.visitorId) // "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"
if (result.bot.detected) { console.warn("bot, confidence:", result.bot.confidence)}결과는 다음과 같은 형태입니다:
{ visitorId: "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y", 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()}