JavaScript SDK

TRACIO JavaScript SDK(@tracio/sdk)는 브라우저 신호를 수집하여 방문자 식별 및 봇 탐지를 위해 TRACIO 클라우드로 전송합니다. 경량이며 논블로킹이고, 모든 최신 브라우저와 호환됩니다.

설치

bash

npm install @tracio/sdk

이 패키지는 완전한 TypeScript 타입과 함께 ESM, CJS, IIFE 빌드를 제공합니다.

CDN

번들러 없이 CDN에서 TRACIO를 사용하는 방법은 두 가지가 있습니다.

엣지 스크립트(자동 초기화)

엣지 스크립트는 k 쿼리 파라미터의 퍼블릭 키를 사용해 자동으로 초기화합니다. JavaScript가 필요 없습니다:

HTML

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

npm 번들(IIFE 전역)

unpkg 또는 jsDelivr에서 게시된 npm 번들을 로드할 수도 있습니다. 이는 TracioSDK 전역 객체를 노출합니다. 버전을 고정하세요:

HTML

<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를 동기적으로 반환합니다. 에이전트는 백그라운드에서 로드되며, 인스턴스 메서드는 준비가 완료되면 resolve됩니다.

TypeScript

import { Tracio } from "@tracio/sdk"

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

TracioConfig

TypeScript

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

옵션	타입	기본값	설명
`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.init()을 두 번 이상 호출하면 multiple_keys 오류가 발생합니다.

식별

tracio.getVisitorId()

안정적인 방문자 식별자로 resolve되는 Promise<string>을 반환합니다.

TypeScript

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

tracio.getResult()

방문자 ID와 봇 탐지 결과가 담긴 Promise<TracioResult>를 반환합니다.

TypeScript

const result = await tracio.getResult()

console.log(result.visitorId)

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

TracioResult

TypeScript

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

라이프사이클 콜백

tracio.onReady(cb)

에이전트가 로드되어 결과를 생성하면 한 번 호출됩니다.

TypeScript

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

tracio.onError(cb)

SDK에서 오류가 발생하면 호출됩니다.

TypeScript

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

tracio.destroy()

인스턴스를 해제하고 리소스를 반환합니다. 이후 호출은 destroyed 오류로 reject됩니다.

TypeScript

tracio.destroy()

오류 처리

SDK는 타입이 지정된 code를 가진 TracioError 인스턴스를 던집니다. 분기 처리를 위해 isTracioError와 isRetryableError 헬퍼를 사용하세요:

TypeScript

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 유니온은 다음을 포함합니다:

코드	설명
`blocked`	요청이 차단되었습니다(예: 광고 차단기에 의해).
`destroyed`	호출이 완료되기 전에 인스턴스가 파괴되었습니다.
`invalid_config`	구성이 유효하지 않습니다(예: `publicKey` 누락).
`load_failed`	에이전트 스크립트를 로드하지 못했습니다.
`multiple_keys`	`Tracio.init()`이 충돌하는 퍼블릭 키로 호출되었습니다.
`network`	네트워크 요청이 실패했습니다.
`non_browser`	SDK가 브라우저 환경 밖에서 사용되었습니다.
`script_error`	에이전트 스크립트가 런타임에 오류를 일으켰습니다.
`server`	서버가 오류를 반환했습니다.
`timeout`	요청이 `timeoutMs`를 초과했습니다.

load_failed, blocked, script_error, network, timeout, server는 재시도 가능하며, 이들에 대해 isRetryableError(error)는 true를 반환합니다.

프레임워크 통합

React, Vue, Angular, Svelte의 경우 코어 SDK를 직접 연결하는 대신 전용 프레임워크 패키지를 사용하세요:

각 패키지는 @tracio/sdk를 래핑하고 관용적인 프리미티브(프로바이더, 플러그인, 훅, 컴포저블, 서비스)를 노출합니다. 프레임워크별 스니펫은 SDK 개요를 참조하세요.

성능 고려사항

논블로킹: Tracio.init()은 동기적으로 반환되며 에이전트를 백그라운드에서 로드합니다. 페이지 렌더링을 차단하지 않습니다.
단일 요청: 식별당 하나의 요청이 이루어집니다.
타임아웃: 식별은 timeoutMs(기본 15000ms)로 제한되므로, 느린 네트워크가 코드를 무기한 멈추게 하지 않습니다.

JavaScript SDK

설치

bash

npm install @tracio/sdk

이 패키지는 완전한 TypeScript 타입과 함께 ESM, CJS, IIFE 빌드를 제공합니다.

CDN

번들러 없이 CDN에서 TRACIO를 사용하는 방법은 두 가지가 있습니다.

엣지 스크립트(자동 초기화)

엣지 스크립트는 k 쿼리 파라미터의 퍼블릭 키를 사용해 자동으로 초기화합니다. JavaScript가 필요 없습니다:

HTML

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

npm 번들(IIFE 전역)

unpkg 또는 jsDelivr에서 게시된 npm 번들을 로드할 수도 있습니다. 이는 TracioSDK 전역 객체를 노출합니다. 버전을 고정하세요:

HTML

<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를 동기적으로 반환합니다. 에이전트는 백그라운드에서 로드되며, 인스턴스 메서드는 준비가 완료되면 resolve됩니다.

TypeScript

import { Tracio } from "@tracio/sdk"

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

TracioConfig

TypeScript

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

옵션	타입	기본값	설명
`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.init()을 두 번 이상 호출하면 multiple_keys 오류가 발생합니다.

식별

tracio.getVisitorId()

안정적인 방문자 식별자로 resolve되는 Promise<string>을 반환합니다.

TypeScript

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

tracio.getResult()

방문자 ID와 봇 탐지 결과가 담긴 Promise<TracioResult>를 반환합니다.

TypeScript

const result = await tracio.getResult()

console.log(result.visitorId)

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

TracioResult

TypeScript

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

라이프사이클 콜백

tracio.onReady(cb)

에이전트가 로드되어 결과를 생성하면 한 번 호출됩니다.

TypeScript

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

tracio.onError(cb)

SDK에서 오류가 발생하면 호출됩니다.

TypeScript

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

tracio.destroy()

인스턴스를 해제하고 리소스를 반환합니다. 이후 호출은 destroyed 오류로 reject됩니다.

TypeScript

tracio.destroy()

오류 처리

SDK는 타입이 지정된 code를 가진 TracioError 인스턴스를 던집니다. 분기 처리를 위해 isTracioError와 isRetryableError 헬퍼를 사용하세요:

TypeScript

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 유니온은 다음을 포함합니다:

코드	설명
`blocked`	요청이 차단되었습니다(예: 광고 차단기에 의해).
`destroyed`	호출이 완료되기 전에 인스턴스가 파괴되었습니다.
`invalid_config`	구성이 유효하지 않습니다(예: `publicKey` 누락).
`load_failed`	에이전트 스크립트를 로드하지 못했습니다.
`multiple_keys`	`Tracio.init()`이 충돌하는 퍼블릭 키로 호출되었습니다.
`network`	네트워크 요청이 실패했습니다.
`non_browser`	SDK가 브라우저 환경 밖에서 사용되었습니다.
`script_error`	에이전트 스크립트가 런타임에 오류를 일으켰습니다.
`server`	서버가 오류를 반환했습니다.
`timeout`	요청이 `timeoutMs`를 초과했습니다.

load_failed, blocked, script_error, network, timeout, server는 재시도 가능하며, 이들에 대해 isRetryableError(error)는 true를 반환합니다.

프레임워크 통합

React, Vue, Angular, Svelte의 경우 코어 SDK를 직접 연결하는 대신 전용 프레임워크 패키지를 사용하세요:

성능 고려사항

논블로킹: Tracio.init()은 동기적으로 반환되며 에이전트를 백그라운드에서 로드합니다. 페이지 렌더링을 차단하지 않습니다.
단일 요청: 식별당 하나의 요청이 이루어집니다.
타임아웃: 식별은 timeoutMs(기본 15000ms)로 제한되므로, 느린 네트워크가 코드를 무기한 멈추게 하지 않습니다.