คู่มือนี้จะพาคุณผ่านขั้นตอนการผสาน TRACIO เข้ากับแอปพลิเคชันของคุณ คุณจะติดตั้ง client SDK เริ่มต้นการทำงานด้วย public key ของคุณ และอ่านผลการระบุตัวตนผู้เข้าชม (visitor identification) ครั้งแรกของคุณ
ติดตั้ง TRACIO SDK ด้วยตัวจัดการแพ็กเกจที่คุณต้องการ:
npm install @tracio/sdkหรือด้วย pnpm:
pnpm add @tracio/sdkหรือด้วย yarn:
yarn add @tracio/sdkหากคุณไม่ได้ใช้ bundler ให้วาง edge script tag ลงในหน้าเว็บของคุณ มันจะเริ่มต้นการทำงานโดยอัตโนมัติด้วย public key ใน query parameter k:
<script src="https://edge.tracio.ai/s.js?k=PUBLIC_KEY" async></script>นำเข้า Tracio และเรียก Tracio.init() ด้วย public key ของคุณ ซึ่งจะคืนค่า TracioInstance กลับมาทันที — โดย agent ที่อยู่เบื้องหลังจะโหลดในพื้นหลัง
import { Tracio } from "@tracio/sdk"
const tracio = Tracio.init({ publicKey: "5ca175fc...",})public key ของคุณสามารถส่งไปในโค้ดฝั่ง client ได้อย่างปลอดภัย คุณสามารถหาได้ใน dashboard ของคุณภายใต้ API Keys
Tracio.init() รับอ็อบเจกต์ TracioConfig:
| ตัวเลือก | ประเภท | ค่าเริ่มต้น | คำอธิบาย |
|---|---|---|---|
publicKey | string | จำเป็น | public key ของคุณ คัดลอกมาจาก dashboard ของคุณ |
region | "us" | "eu" | ไม่มี | ภูมิภาคข้อมูล (data region) แบบเลือกได้ เมื่อไม่กำหนด SDK จะใช้ endpoint ทั่วไป https://edge.tracio.ai (ไม่ได้บอกโดยนัยว่าเป็น US data residency) กำหนดค่าอย่างชัดเจนเพื่อตรึงไว้ที่ us หรือ eu |
endpoint | string | อัตโนมัติ | API endpoint แบบกำหนดเอง (สำหรับ endpoint ที่ proxy แบบ first-party) |
scriptUrl | string | อัตโนมัติ | URL แบบกำหนดเองสำหรับ agent script (สำหรับ endpoint ที่ proxy แบบ first-party) |
linkedId | string | ไม่มี | ตัวระบุที่เชื่อมโยงผู้เข้าชมรายนี้กับเอนทิตีในระบบของคุณ |
tag | string | ไม่มี | ป้ายกำกับแบบอิสระที่แนบไปกับคำขอเพื่อใช้กรองในภายหลัง |
debug | boolean | false | บันทึกข้อมูลวินิจฉัยแบบละเอียดลงในคอนโซล |
timeoutMs | number | 15000 | ระยะเวลาที่จะรอผลลัพธ์ก่อนที่จะหมดเวลา (timeout) |
เรียก tracio.getVisitorId() เพื่อรับตัวระบุผู้เข้าชม (visitor identifier) ที่เสถียร นี่เป็นการดำเนินการแบบ asynchronous
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: [], },}ใช้ lifecycle callbacks เพื่อตอบสนองเมื่อ agent พร้อมทำงานหรือเมื่อมีบางอย่างล้มเหลว และใช้ 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()ดู การจัดการข้อผิดพลาด สำหรับรายการโค้ดข้อผิดพลาดทั้งหมดและตัวช่วย retry
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()}