حزمة React SDK

تغلّف حزمة @tracio/react النواة @tracio/sdk وتوفّر عناصر React أساسية اصطلاحية: مزوّدًا (provider) يركّب الوكيل، وخطافات (hooks) تمنحك معرّف الزائر ونتيجة التعرّف مع حالتَي التحميل والخطأ.

التثبيت

npm install @tracio/react @tracio/sdk

الحزمة react (الإصدار 18 أو 19) هي اعتمادية نظير (peer dependency) ويُفترض أنها مثبّتة مسبقًا في تطبيقك.

الإعداد

غلّف تطبيقك بالمكوّن <TracioProvider>. فهو يركّب وكيل TRACIO عند أول عملية عرض (render) ويستدعي tracio.destroy() تلقائيًا عند إزالة المزوّد (unmount).

import { TracioProvider } from "@tracio/react"

function Root() {
  return (
    <TracioProvider publicKey={process.env.NEXT_PUBLIC_TRACIO_KEY!}>
      <App />
    </TracioProvider>
  )
}

خصائص المزوّد (props)

مرّر إمّا publicKey مع الخصائص القياسية المسطّحة، أو كائن config كاملًا. وعند تمرير كليهما، يفوز config.

الخطافات (Hooks)

useVisitorId()

يُرجع معرّف الزائر الثابت مع حالتَي التحميل والخطأ.

const { data, isLoading, error, isFetched, getId } = useVisitorId()
// data: string | undefined — the visitorId

تعيد الدالة getId() جلب معرّف الزائر بشكل إجرائي (imperative).

useTracioResult(opts?)

يُرجع النتيجة الكاملة TracioResult (معرّف الزائر بالإضافة إلى كشف الروبوتات).

const { data, isLoading, error, isFetched, getData } = useTracioResult()
// data: TracioResult | undefined

القيمة الافتراضية لـ opts.immediate هي true. مرّر { immediate: false } لتأجيل الجلب حتى تستدعي getData() بنفسك — وهو مفيد خلف بوابة موافقة (consent gate):

const { data, getData } = useTracioResult({ immediate: false })

function onConsent() {
  getData() // identify only after the user opts in
}

useTracio()

مخرج طوارئ (escape hatch) يُرجع المثيل الأساسي للاستخدام المتقدّم.

const { tracio } = useTracio()

مثال كامل

import { TracioProvider, useVisitorId } from "@tracio/react"
function App() {
  return (
    <TracioProvider publicKey={process.env.NEXT_PUBLIC_TRACIO_KEY!}>
      <Page />
    </TracioProvider>
  )
}
function Page() {
  const { data: visitorId, isLoading, error } = useVisitorId()
  if (isLoading) return <span>Loading…</span>
  if (error) return <span>Error: {error.message}</span>
  return <span>Visitor: {visitorId}</span>
}

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

• مرجع JavaScript SDK — واجهة النواة @tracio/sdk التي تُبنى عليها الخطافات
• معالجة الأخطاء — رموز الأخطاء واستراتيجيات إعادة المحاولة
• نظرة عامة على حزم SDK — كل حزمة إطار عمل في لمحة