البداية السريعة

يرشدك هذا الدليل خطوة بخطوة إلى دمج TRACIO في تطبيقك. ستقوم بتثبيت SDK الخاص بالعميل، وتهيئته باستخدام مفتاحك العام، وقراءة أول نتيجة لتحديد هوية الزائر.

الخطوة 1: تثبيت SDK

ثبّت TRACIO SDK باستخدام مدير الحزم المفضّل لديك:

npm install @tracio/sdk

أو باستخدام pnpm:

pnpm add @tracio/sdk

أو باستخدام yarn:

yarn add @tracio/sdk

مقتطف CDN بدون بناء

إذا كنت لا تستخدم أداة تجميع (bundler)، أدرج وسم سكربت الحافة (edge) في صفحتك. تتم تهيئته تلقائيًا باستخدام المفتاح العام في معامِل الاستعلام k.

اختر الموضع الذي يُحمَّل منه السكربت. تحظر بعض الشبكات وإضافات المتصفح الطلبات الموجَّهة إلى نطاقات التحليلات التابعة لطرف ثالث: مرشّحات الشركات، وأدوات الحجب على مستوى DNS، والقيود الإقليمية، وإضافات الخصوصية. وعند تقديمه من نطاقك الفرعي الخاص، يصبح السكربت طلبًا من الطرف الأول على موقعك ويستمر في العمل في تلك البيئات — انظر النطاقات المخصّصة:

<script src="https://metrics.yoursite.com/s.js?k=PUBLIC_KEY" async></script>

أو حمِّله من نطاق الحافة المشترك، وهو أسرع طريقة للبدء:

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

الخطوة 2: تهيئة SDK

استورد Tracio واستدعِ Tracio.init() باستخدام مفتاحك العام. يعيد هذا TracioInstance على الفور — بينما يُحمَّل الوكيل (agent) الأساسي في الخلفية.

import { Tracio } from "@tracio/sdk"

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

مفتاحك العام آمن للشحن ضمن الكود الذي يعمل من جهة العميل. يمكنك العثور عليه في لوحة التحكم ضمن API Keys.

خيارات التهيئة

يقبل Tracio.init() كائنًا من نوع TracioConfig:

الخطوة 3: الحصول على معرّف الزائر

استدعِ tracio.getVisitorId() للحصول على معرّف زائر ثابت. هذه عملية غير متزامنة.

const visitorId = await tracio.getVisitorId()

console.log(visitorId) // "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

الخطوة 4: قراءة النتيجة الكاملة

استدعِ tracio.getResult() للحصول على نتيجة تحديد الهوية الكاملة، بما في ذلك كشف البوتات.

const result = await tracio.getResult()

console.log(result.visitorId) // "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

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

تأتي النتيجة بالشكل التالي:

{
  visitorId: "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  bot: {
    detected: false,
    confidence: 2,        // 0-100
    reasons: [],
  },
}

الخطوة 5: دورة الحياة والأخطاء

استخدم استدعاءات دورة الحياة (lifecycle callbacks) للتفاعل عندما يصبح الوكيل جاهزًا أو عند فشل شيء ما، واستخدم 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 it
tracio.destroy()

راجع معالجة الأخطاء للاطلاع على القائمة الكاملة لرموز الأخطاء وأدوات إعادة المحاولة المساعِدة.

أنماط دمج شائعة

حماية تسجيل الدخول

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

الخطوات التالية

• كيف يعمل — افهم مسار جمع الإشارات وتحديد الهوية
• مرجع JavaScript SDK — توثيق كامل لواجهة SDK البرمجية
• Webhooks — استقبل أحداث تحديد الهوية على خادمك في الوقت الفعلي
• Data API — اقرأ الزوّار والجلسات وعدّادات velocity من الواجهة الخلفية لديك
• كشف البوتات — تعمّق في كشف الأتمتة