JavaScript SDK

تجمع حزمة TRACIO JavaScript SDK (@tracio/sdk) إشارات المتصفح وترسلها إلى سحابة TRACIO لتعريف الزوار وكشف الروبوتات. وهي خفيفة الوزن وغير حاجبة ومتوافقة مع جميع المتصفحات الحديثة.

التثبيت

npm install @tracio/sdk

تُشحن الحزمة بإصدارات ESM وCJS وIIFE مع أنواع TypeScript كاملة.

CDN

هناك طريقتان لاستخدام TRACIO من شبكة CDN دون أداة تجميع (bundler).

سكربت الحافة (تهيئة تلقائية)

يقوم سكربت الحافة بالتهيئة تلقائيًا باستخدام المفتاح العام في معامل الاستعلام 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)

تُهيّئ الحزمة وتُعيد TracioInstance بشكل متزامن. يُحمّل الوكيل (agent) في الخلفية؛ وتُحل توابع النسخة (instance) بمجرد جاهزيته.

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)

تُستدعى عندما تواجه الحزمة خطأً.

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

tracio.destroy()

تُفكّك النسخة وتحرّر الموارد. تُرفض الاستدعاءات اللاحقة بخطأ destroyed.

tracio.destroy()

معالجة الأخطاء

تُطلق الحزمة نسخًا من 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 لها.

التكامل مع أطر العمل

لأطر React وVue وAngular وSvelte، استخدم حزم أطر العمل المخصصة بدلًا من ربط الحزمة الأساسية يدويًا:

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

تغلّف كل منها @tracio/sdk وتتيح عناصر أولية اصطلاحية (مزوّدات، وإضافات، وخطافات، ومركّبات، وخدمات). راجع نظرة عامة على حزم SDK للاطلاع على مقتطفات خاصة بكل إطار.

اعتبارات الأداء

• غير حاجبة: تُعيد Tracio.init() بشكل متزامن وتحمّل الوكيل في الخلفية. ولا تحجب عرض الصفحة.
• طلب واحد: يُجرى طلب واحد لكل عملية تعريف.
• المهلة: التعريف مقيّد بـ timeoutMs (افتراضيًا 15000 مللي ثانية)، بحيث لا تعلّق شبكة بطيئة شيفرتك إلى ما لا نهاية.