عن المشروع

Visitor Analytics SDK هي مكتبة تحليلات TypeScript مصممة لتطبيقات الويب. تعمل مع أي إطار عمل للواجهة الأمامية مثل React وVue وSvelte وSolid وAstro، وكذلك JavaScript الخام. تركز المكتبة على الخصوصية: لا تجمع معلومات تعريف شخصية أبدًا، ويتم إخفاء هوية جميع البيانات. الميزات الرئيسية تشمل: - عمل مستقل عن الإطار مع حزم تكامل مخصصة لأطر العمل الكبرى. - بنية معيارية قائمة على الإضافات تتيح جامعات بيانات مخصصة، ومحوّلات تخزين، وإضافات. - واجهة برمجة آمنة النوعيًا مع تعريفات TypeScript صارمة وبدون أنواع any. - وحدات ESM قابلة لتقليل الشجرة بحيث يتم حزم الأجزاء المطلوبة فقط. - أصفار تبعية runtime وأداء محسّن باستخدام مستمعين سلبيين، وrequestIdleCallback، ومعالجات مثبوطة، وقراءات DOM مجمعة. - دعم عدم الاتصال بوساطة طابور يتم مزامنته عند توفر الشبكة، بالإضافة إلى.retrys بالتراجع الأسّي وحشو sendBeacon عند إغلاق الصفحة. - خيارات قابلة للتخصيص مثل حجم الدفعة، وفاصل التصريف، وحدود إعادة المحاولة، والضغط، وإزالة التكرار، وفاصل الجلسة، και حقول بيانات مخصصة. توفر المكتبة دالة أساسية createAnalytics تُرجع كائن تحليلات. يقدم الكائن طرقًا لبدء التشغيل، والإيقاف، والتصريف، والمزامنة، وإعادة محاولة عمليات الرفع الفاشلة، وإضافة أو إزالة الجامعات، وتثبيت الإضافات، واستعلام السجلات المخزنة، وتصدير البيانات، وتتبع تغييرات المسار يدويًا، والاشتراك في الأحداث، وتدمير الكائن. جامعو البيانات يجمعون مجموعة واسعة من البيانات: اسم المتصفح وإصداره، ونظام تشغيل الجهاز ومنصته، وأبعاد الشاشة، ومقاييس الأداء (مواعيد التنقل، ومواعيد الرسم، وLCP، وCLS، وINP)، وتفاصيل البيئة (المنطقة الزمنية، واللغة، ونظام الألوان)، ودعم الميزات (WebGL، WebGPU، WASM، Service Worker)، وتفاعلات المستخدم (مدة الجلسة، وعمق التمرير، وعدد النقرات، وتغييرات المسار، ومعلمات UTM). جميع الجامعات اختيارية ويمكن توسيعها بتطبيقات مخصصة. يتم توفير محوّلات تخزين لـذاكرة الوصول العشوائي وlocalStorage وIndexedDB، مع إمكانية دمج خلفيات مخصصة مثل محوّل Redis. تجمع وحدة الرفع السجلات في دفعات، وتتعامل مع إعادة المحاولة بالتراجع الأسّي، وتزيل تكرار الدفعات، ويمكنها ضغط حمولات البيانات عندما يدعم المتصفح CompressionStream. تغطي أمثلة التكامل React (AnalyticsProvider، useAnalytics، usePageView)، وVue (createAnalyticsPlugin، useVueAnalytics)، وSvelte (createAnalyticsStore)، وSolidJS (AnalyticsProvider، createAnalyticsHook)، وAstro، والJavaScript العادي. توضح كل عملية تكامل كيفية تهيئة المكتبة، والوصول إلى البيانات المجموعة، وتنفيذ عمليات الرفع اليدوية. تشمل المكتبة نظام إضافات. يمكن للإضافات تسجيل جامعات إضافية أو تعديل السلوك أثناء التثبيت والتنظيف عند الإلغاء. مثال على ذلك إضافة اختبار A/B التي تضيف متجربة التجربة الحالية إلى كل سجل. الضمانات الصريحة للخصوصية: لا يتم جمع أسماء، أو بريد إلكتروني، أو كلمات مرور، أو محتوى ملفات تعريف الارتباط، أو مدخلات النماذج، أو عناوين IP الصحيحة، أو إحداثيات GPS، أو ضغوط المفاتيح، أو إحداثيات النقر، أو أي معرفات بصمة دائمة أبدًا. معرفات الجلسات هي UUIDs عشوائية يتم إنشاؤها لكل كائن ولا يتم الحفاظ عليها عبر الجلسات. القيود المعروفة تشمل إيقاف مؤقت للجلسة مبني على النشاط، والكتابات غير الذرية عند استخدام LocalStorage في سيناريوهات متعددة التبويبات (يُنصح بـIndexedDB)، والضغط بالgzip الاختياري الذي يتطلب دعم متصفح حديث. تتحسن الأداء بواسطة مستمعي الأحداث السلبيين، وrequestIdleCallback للأعمال الثقيلة، ومعالجة التمرير وتغيير الحجم بالمثبّط، والتهيئة المتأخرة للجامعات، وقراءات DOM المجمعة عبر requestAnimationFrame، والتوصيل الموثوق عبر navigator.sendBeacon عند الإغلاق. ترخص المكتبة بموجب رخصة MIT.