عن المشروع

Clamp Analytics هي حزمة SDK خفيفة الوزن لـ JavaScript تتيح لك جمع بيانات استخدام المنتج بدون ملفات تعريف الارتباط أو المعرفات الشخصية. بعد تهيئة المكتبة باستخدام معرف المشروع الخاص بك، يتم تسجيل معاينات الصفحات ومعلومات الجلسة تلقائيًا، ويمكنك إرسال أحداث مخصصة، والتعرف على المستخدمين المسجلين، والتقاط معاملات الإيرادات، وتسجيل الأخطاء. التثبيت بسيط ومباشر: قم بإضافة الحزمة باستخدام npm أو قم بلصق علامة سكريبت واحدة تشير إلى CDN. يقرأ السكريبت معرف المشروع من سمة data-clamp-project ويبدأ التتبع فورًا. بالنسبة لأطر العمل مثل React وNext.js وVite وNuxt وSvelteKit وAstro وغيرها، توفر حزمة SDK أدلة مخصصة ومكون React يمكن وضعه في التخطيط الرئيسي (root layout). تتضمن واجهة برمجة التطبيقات (API) كلا من init وtrack وidentify وreset وrevenue وgetAnonymousId وgetUserId. تتيح لك دالة track تسجيل أي حدث مسمى باستخدام خصائص بسيطة مفتاح-قيمة. بينما تُعد revenue أداة مساعدة محددة النوع تُصدر أحداث اشتراك وشراء قياسية، وتقوم تلقائيًا بحساب فروق الإيرادات الشهرية المتكررة (MRR) بناءً على فترة الفوترة. وتعمل identify على ربط معرف مستخدم ثابت بالأحداث المستقبلية، بينما تقوم reset بإزالة هذا الربط عند تسجيل الخروج. يمكن تعريف خرائط الأحداث المحددة للأنواع في TypeScript، مما يمنحك إكمالًا تلقائيًا عند الترجمة والتحقق من صحة الأحداث المخصصة. وتتبع أحداث الإيرادات نوع اتحاد صارم يفرض المزيج الصحيح من الحقول للاشتراكات، والمشتريات لمرة واحدة، وعمليات الاسترداد. يمكن تمكين معالجة الأخطاء لالتقاط الاستثناءات غير المعالجة ووعود الرفض غير المعالجة كأحداث $error، والتي يتم تجميعها حسب البصمة الرقمية لتسهيل التحليل. تضيف التوسعات الاختيارية تتبعًا تلقائيًا للروابط الخارجية، وتنزيلات الملفات، وصفحات 404، والأحداث المدفوعة بسمات البيانات، ومؤشرات أداء الويب، ورؤية أجزاء الصفحة. يتم تحميل كل توسعة عند الطلب، مما يحافظ على حد أدنى لحجم الحزمة. يتم دعم الاستخدام على جانب الخادم من خلال إصدار منفصل يتطلب مفتاح API. يمكنك إرسال نفس الأحداث من خدمات الخادم الخلفية، أو خطافات الويب (webhooks)، أو إجراءات الخادم (server actions)، مما يضمن تدفقًا موحدًا للأحداث. تتم أرشفة جميع البيانات المجمعة في منصة Clamp Analytics، والتي توفر خطة مجانية تصل إلى 100 ألف حدث شهريًا وخادم Model Context Protocol مدمج. وهذا يجعل الأحداث قابلة للاستعلام مباشرة بواسطة وكلاء الذكاء الاصطناعي مثل Claude أو Cursor أو إضافات VS Code، مما يتيح إجراء تحليلات بلغة طبيعية والحصول على رؤى مؤتمتة. تم إصدار حزمة SDK بموجب ترخيص MIT ويتم صيانتها في مستودع clamp-sh/analytics.