Svelte SDK

تغلّف حزمة @tracio/svelte النواة @tracio/sdk وتوفّر بدائيات (primitives) اصطلاحية خاصة بـ Svelte: استدعاء init لمرة واحدة، ومتاجر قابلة للقراءة (readable stores) تمنحك معرّف الزائر ونتيجة التعريف.

التثبيت

npm install @tracio/svelte @tracio/sdk

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

الإعداد

استدعِ Tracio.init({ publicKey }) مرة واحدة، قرب جذر تطبيقك — في +layout.svelte عند استخدام SvelteKit — محميًّا بـ browser حتى لا يعمل أبدًا أثناء التصيير من جهة الخادم (server-side rendering).

<!-- +layout.svelte -->
<script>
  import { Tracio } from "@tracio/svelte"
  import { browser } from "$app/environment"
  if (browser) Tracio.init({ publicKey: import.meta.env.VITE_TRACIO_KEY })
</script>
<slot />

المتاجر (Stores)

تُتاح حالة TRACIO على هيئة متاجر قابلة للقراءة (readable stores) في Svelte. كل قيمة متجر هي QueryState تحمل data وisLoading وerror. استهلك المتجر باستخدام البادئة $: ‏$visitor.data و$visitor.isLoading و$visitor.error.

قادم من React؟ يُسقِط QueryState في Svelte علَم isFetched الخاص بخطاطيف (hooks) React، كما أن useVisitorId() لا يوفّر طريقة جلب أمرية (imperative) — وحده useTracioResult() يحمل getData().

useVisitorId()

يُعيد متجرًا قابلاً للقراءة من { data, isLoading, error }، حيث تكون data هي معرّف الزائر المستقر (string | undefined).

<script>
  import { useVisitorId } from "@tracio/svelte"
  const visitor = useVisitorId()
</script>
{$visitor.data}

useTracioResult(opts?)

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

<script>
  import { useTracioResult } from "@tracio/svelte"
  const result = useTracioResult({ immediate: false })
  // $result.data / $result.isLoading / $result.error
  // result.getData(): Promise<void> — call to fetch on demand
</script>

useTracio()

مَخرج طوارئ (escape hatch) يُعيد TracioInstance الأساسية (أو undefined عندما لا يكون Tracio.init() قد عمل للشجرة الحالية) للاستخدام المتقدم. وهو يُعيد النسخة (instance) مباشرةً — لا يوجد متجر ولا كائن غلاف (wrapper) لتفكيكه.

<script>
  import { useTracio } from "@tracio/svelte"
  const tracio = useTracio()
</script>

مثال كامل

<!-- +layout.svelte -->
<script>
  import { Tracio } from "@tracio/svelte"
  import { browser } from "$app/environment"
  if (browser) Tracio.init({ publicKey: import.meta.env.VITE_TRACIO_KEY })
</script>
<slot />

<!-- AnyComponent.svelte -->
<script>
  import { useVisitorId } from "@tracio/svelte"
  const visitor = useVisitorId()
</script>
{#if $visitor.isLoading}Loading…{:else if $visitor.error}Error: {$visitor.error.message}{:else}Visitor: {$visitor.data}{/if}

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

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