عن المشروع

Tracker SDK هي مكتبة تحليلات ويب صغيرة الحجم مصممة للتكامل السريع في تطبيقات الويب الحديثة، خاصة تلك المُولَدة بأدوات المساعدة بالذكاء الاصطناعي مثل Vibe Coding. تركز على البساطة: استدعاء `init` واحد لإعداد نقطة نهاية المجمِّع، بعد ذلك تُسجَّل صفحات العرض تلقائياً ويمكن إرسال أحداث مخصصة عبر `track(eventName, data)`. **القدرات الرئيسية** - **بدء بدون إعدادات** – إضافة وسم نصي واحد أو استيراد npm يكفي لبدء جمع البيانات. - **اكتشاف تلقائي لصفحات العرض** – تستمع SDK لأحداث التنقل وترسل تحميل `pageview` بدون كود إضافي. - **تتبع الأحداث المخصصة** – يمكن للمطورين تسجيل أي تفاعل باستدعاء `track` مع اسم وحمولة اختيارية. - **بصمة الجهاز** – بصمة مبنية على Canvas تحدد الزوار بشكل فريد مع احترام الخصوصية. - **طابور عدم الاتصال** – الأحداث الفاشلة تُخزَّن في التخزين المحلي وتُعاد محاوَلتها لاحقاً لتقليل فقدان البيانات. - **إدارة الجلسات** – تُنشأ الجلسات تلقائياً وتنتهي بعد مهلة زمنية قابلة للتكوين (الافتراضي 30 دقيقة). - **تجميع قابل للتكوين** – تُجمَّع الأحداث في طلب واحد لتقليل الحمل الشبكي. **التثبيت** - **CDN** – أضف حزمة UMD مباشرة في HTML واستدعِ `WFTK.init({ endpoint: 'https://your-api.com/api/v1/collect/event', debug: true })`. - **npm** – `npm install @weavefox/tracker` ثم استورد الدوال: `import { init, track, setUserId } from '@weavefox/tracker';`. **واجهة البرمجة العامة** | الدالة | الغرض | |--------|---------| | `init(config)` | تهيئة الـ SDK بنقطة النهاية وappId والعلامات الاختيارية. | | `track(eventName, data)` | إرسال حدث مخصص. | | `trackPageview(data)` | تسجيل صفحة عرض يدوياً (مفعّل تلقائياً افتراضياً). | | `setUserId(userId)` | ربط مستخدم مسجل بالأحداث اللاحقة. | | `getFingerprint()` | استرجاع بصمة الجهاز المُولَّدة. | | `flush()` | إرسال الأحداث المكدسة فوراً. | **خيارات التكوين** ```javascript WFTK.init({ endpoint: 'required', // عنوان خدمة المجمِّع appId: 'optional', // معرِّف التطبيق autoPageview: true, // تتبع صفح العرض تلقائياً debug: false, // تفعيل تصحيح الأخطاء في وحدة التحكم enableQueue: true, // تخزين الأحداث دون اتصال عند فشل الشبكة sessionTimeout: 1800000, // مهلة خمول الجلسة بالمللي ثانية (الافتراضي 30 دقيقة) maxEventsPerSession: 1000 // الحد الأقصى للأحداث لكل جلسة }); ``` **تنسيق الحمولة** – يحتوي كل طلب على جسم JSON مع `appId` اختياري ومصفوفة `events`. كل حدث يتضمن اسماً إلزامياً `event` و`timestamp` و`nonce` (للتخلص من التكرار) و`fingerprint` وكائن `data` يحتوي على سياق مُجمَّع نظامياً (URL، العنوان، معلومات الجهاز، إلخ). الحقول التي يحددها المستخدم تتبع في كائن فرعي `biz` للفصل بين بيانات التحليلات والأعمال. **اعتبارات جانب الخادم** - **التحقق من الطابع الزمني** – رفض الأحداث الأقدم من 5 دقائق لمنع هجمات إعادة التشغيل. - **التخلص من تكرار الـ nonce** – تخزين nonces (مثل استخدام Redis) مع مدة صلاحية 24 ساعة لضمان التشغيل الأحادي. - **تقييد المعدل** – تطبيق حدود لكل عنوان IP وبصمة جهاز لكبح الإساءة. - **معرِّف التطبيق** – تفضيل `appId` صريح في الحمولة؛ العودة إلى host المرجع الطلب إذا لزم الأمر. - **مثال معالج Express** – يوفر ملف README قطعة كود Node.js مختصرة تحقق الطوابع الزمنية وتتحقق من nonces وتثبّت الأحداث. **الترخيص** – مُوزَّع تحت ترخيص MIT، مما يسمح بالاستخدام غير المقيد في المشاريع مفتوحة المصدر والتجارية. بشكل عام، offers Tracker SDK حلاً بسيطاً وواعياً بالخصوصية للمطورين الذين يحتاجون لتحليلات جانب العميل الموثوقة بدون عبء المنصات الثقيلة.