JavaScript SDK

TRACIO JavaScript SDK (@tracio/sdk) รวบรวมสัญญาณจากเบราว์เซอร์และส่งไปยัง TRACIO cloud เพื่อระบุตัวตนผู้เข้าชมและตรวจจับบอท มันมีขนาดเล็ก ไม่บล็อกการทำงาน (non-blocking) และเข้ากันได้กับเบราว์เซอร์สมัยใหม่ทุกตัว

Installation

npm install @tracio/sdk

แพ็กเกจนี้มาพร้อมกับ build แบบ ESM, CJS และ IIFE พร้อม TypeScript types ครบถ้วน

CDN

มีสองวิธีในการใช้ TRACIO จาก CDN โดยไม่ต้องใช้ bundler

Edge script (auto-init)

Edge script จะเริ่มต้นใช้งานโดยอัตโนมัติด้วย public key ใน query parameter k โดยไม่ต้องเขียน JavaScript:

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

npm bundle (IIFE global)

คุณยังสามารถโหลด npm bundle ที่เผยแพร่แล้วจาก unpkg หรือ jsDelivr ได้ด้วย มันจะเปิดเผย global ชื่อ TracioSDK โปรดปักหมุด (pin) เวอร์ชันไว้:

<script src="https://unpkg.com/@tracio/sdk@0.1.3/dist/index.min.js"></script>
<script>
  const tracio = TracioSDK.Tracio.init({ publicKey: "5ca175fc..." })
</script>

Initialization

Tracio.init(config)

เริ่มต้นใช้งาน SDK และคืนค่า TracioInstance แบบ synchronous agent จะโหลดในเบื้องหลัง และเมธอดของ instance จะ resolve เมื่อพร้อมใช้งาน

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() มากกว่าหนึ่งครั้งด้วย public key ที่ต่างกันจะทำให้เกิดข้อผิดพลาด multiple_keys

Identification

tracio.getVisitorId()

คืนค่า Promise<string> ที่ resolve เป็นตัวระบุผู้เข้าชมที่คงที่

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

tracio.getResult()

คืนค่า Promise<TracioResult> พร้อมกับ visitor ID และผลการตรวจจับบอท

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 Callbacks

tracio.onReady(cb)

ถูกเรียกเมื่อ agent โหลดเสร็จและสร้างผลลัพธ์แล้ว

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

รื้อ instance และคืนทรัพยากร การเรียกครั้งต่อ ๆ ไปจะถูก reject ด้วยข้อผิดพลาด destroyed

tracio.destroy()

Error Handling

SDK จะโยน (throw) instance ของ TracioError พร้อมกับ code ที่มีการกำหนดประเภทไว้ ใช้ helper 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)
  }
}

Error Codes

Union TracioErrorCode ครอบคลุม:

load_failed, blocked, script_error, network, timeout และ server สามารถลองใหม่ได้ (retryable) โดย isRetryableError(error) จะคืนค่า true สำหรับรหัสเหล่านี้

Framework Integration

สำหรับ React, Vue, Angular และ Svelte ให้ใช้แพ็กเกจ framework เฉพาะทางแทนการต่อ core SDK เข้าด้วยมือ:

• @tracio/react
• @tracio/vue
• @tracio/angular
• @tracio/svelte

แต่ละแพ็กเกจห่อหุ้ม @tracio/sdk และเปิดเผย primitive ที่เป็นสำนวนเฉพาะของแต่ละ framework (providers, plugins, hooks, composables และ services) ดู snippet ของแต่ละ framework ได้ที่ ภาพรวม SDKs

Performance Considerations

• Non-blocking: Tracio.init() คืนค่าแบบ synchronous และโหลด agent ในเบื้องหลัง มันไม่บล็อกการเรนเดอร์หน้าเว็บ
• Single request: มีการส่งคำขอหนึ่งครั้งต่อการระบุตัวตนหนึ่งครั้ง
• Timeout: การระบุตัวตนถูกจำกัดด้วย timeoutMs (ค่าเริ่มต้น 15000ms) เพื่อให้เครือข่ายที่ช้าไม่ทำให้โค้ดของคุณค้างอย่างไม่มีกำหนด