JavaScript SDK

ה-JavaScript SDK של TRACIO (@tracio/sdk) אוסף אותות מהדפדפן ושולח אותם לענן של TRACIO לצורך זיהוי מבקרים וזיהוי בוטים. הוא קליל, אינו חוסם ותואם לכל הדפדפנים המודרניים.

התקנה

npm install @tracio/sdk

החבילה כוללת בנייות ESM, CJS ו-IIFE עם טיפוסי TypeScript מלאים.

CDN

יש שתי דרכים להשתמש ב-TRACIO מ-CDN ללא bundler.

סקריפט edge (אתחול אוטומטי)

סקריפט ה-edge מבצע אתחול אוטומטי באמצעות המפתח הציבורי שבפרמטר השאילתה k. אין צורך ב-JavaScript:

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

חבילת npm (גלובל IIFE)

אפשר גם לטעון את חבילת ה-npm שפורסמה מ-unpkg או מ-jsDelivr. היא חושפת גלובל בשם TracioSDK. קבעו גרסה מפורשת:

<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 באופן סינכרוני. הסוכן נטען ברקע; המתודות של המופע נפתרות ברגע שהוא מוכן.

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() יותר מפעם אחת עם מפתח ציבורי שונה זורקת שגיאת multiple_keys.

זיהוי

tracio.getVisitorId()

מחזיר Promise<string> שנפתר למזהה המבקר היציב.

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

tracio.getResult()

מחזיר Promise<TracioResult> עם מזהה המבקר ותוצאת זיהוי הבוט.

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[]
  }
}

קריאות חוזרות של מחזור החיים

tracio.onReady(cb)

נקראת ברגע שהסוכן נטען והפיק תוצאה.

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

מפרק את המופע ומשחרר משאבים. קריאות עוקבות נדחות עם שגיאת destroyed.

tracio.destroy()

טיפול בשגיאות

ה-SDK זורק מופעי TracioError עם code מטופס. השתמשו בפונקציות העזר 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)
  }
}

קודי שגיאה

האיחוד TracioErrorCode מכסה:

load_failed, blocked, script_error, network, timeout ו-server ניתנים לניסיון חוזר; isRetryableError(error) מחזיר true עבורם.

אינטגרציה עם Framework

עבור React, Vue, Angular ו-Svelte השתמשו בחבילות ה-framework הייעודיות במקום לחווט את ה-SDK המרכזי באופן ידני:

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

כל אחת מהן עוטפת את @tracio/sdk וחושפת פרימיטיבים אידיומטיים (providers, plugins, hooks, composables ו-services). לקטעי קוד לכל framework ראו את סקירת ה-SDKs.

שיקולי ביצועים

• אינו חוסם: Tracio.init() חוזרת באופן סינכרוני וטוענת את הסוכן ברקע. היא אינה חוסמת את רינדור העמוד.
• בקשה יחידה: מתבצעת בקשה אחת לכל זיהוי.
• זמן קצוב: הזיהוי מוגבל על ידי timeoutMs (ברירת מחדל 15000ms), כך שרשת איטית לעולם לא תתקע את הקוד שלכם לזמן בלתי מוגבל.