Vue SDK

تُغلِّف حزمة @tracio/vue الحزمة الأساسية @tracio/sdk وتوفّر بدائيات Vue 3 اصطلاحية: إضافة (plugin) تركّب الوكيل (agent)، ودوال تركيبية (composables) تسلّمك معرّف الزائر ونتيجة التعرّف على هيئة مراجع (refs) تفاعلية.

التثبيت

npm install @tracio/vue @tracio/sdk

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

الإعداد

ثبّت الإضافة على نسخة تطبيقك عبر app.use(TracioPlugin, options). تقبل الخيارات إمّا إعدادًا مسطّحًا (مع publicKey) أو { config } يحمل TracioConfig كاملًا.

// main.ts
import { createApp } from "vue"
import { TracioPlugin } from "@tracio/vue"
import App from "./App.vue"
createApp(App)
  .use(TracioPlugin, { publicKey: import.meta.env.VITE_TRACIO_KEY })
  .mount("#app")

الدوال التركيبية

تُعيد كل دالة تركيبية مراجع Vue للحقول data وisLoading وerror وisFetched، إضافةً إلى الدالة getData للجلب (أو إعادة الجلب) بشكل أمري. لاحظ أنّ الدالة الأمرية تُسمّى getData في كل دالة تركيبية في Vue — ولا يوجد getId على غرار React.

useVisitorId()

تُعيد معرّف الزائر المستقر مع حالتَي التحميل والخطأ.

const { data, isLoading, error, isFetched, getData } = useVisitorId()
// data: Ref<string | null> — the visitorId
// getData(): Promise<void> — re-runs the underlying result fetch

useTracioResult(opts?)

تُعيد TracioResult الكامل (معرّف الزائر إضافةً إلى كشف الروبوتات). القيمة الافتراضية لـ opts.immediate هي true؛ مرّر { immediate: false } لتأجيل الجلب حتى تستدعي getData() — على سبيل المثال خلف بوابة موافقة.

const { data, isLoading, error, isFetched, getData } = useTracioResult()
// data: Ref<TracioResult | null>

useTracio()

مَخرج (escape hatch) يُعيد TracioInstance الأساسية (أو undefined عند عدم تثبيت أي إضافة أعلى المكوّن) للاستخدامات المتقدّمة. تُعيد النسخة مباشرةً — ولا يوجد كائن مُغلِّف لتفكيكه.

const tracio = useTracio()

مثال كامل

// main.ts
import { createApp } from "vue"
import { TracioPlugin } from "@tracio/vue"
import App from "./App.vue"
createApp(App)
  .use(TracioPlugin, { publicKey: import.meta.env.VITE_TRACIO_KEY })
  .mount("#app")

<script setup lang="ts">
import { useVisitorId } from "@tracio/vue"
const { data: visitorId, isLoading, error } = useVisitorId()
</script>
<template>
  <span v-if="isLoading">Loading…</span>
  <span v-else-if="error">Error: {{ error.message }}</span>
  <span v-else>Visitor: {{ visitorId }}</span>
</template>

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

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