تثبيت SDK الويب
SDK الويب ملف واحد حجمه تقريبًا 6 كيلوبايت بعد الضغط (gzip)، ويخدمه datacub بنفسه. أضفه بوسم سكربت، ويشتغل مع أي موقع أو إطار.
يسجّل مشاهدات الصفحات (ومنها التنقل داخل تطبيقات الصفحة الواحدة)، ومغادرة الصفحة مع وقت الظهور الفعلي وعمق التمرير، والنقرات على الأزرار والروابط، ومحاولات إرسال النماذج، والأحداث اللي تتتبّعها أنت، مع السياق المذكور في وش يجمعه الـ SDK. ويبدأ من أول مشاهدة صفحة، بدون خطوة موافقة. وإذا تبي تنتظر موافقة زوارك، شوف طلب الموافقة.
مو موجود على npm. لا تثبّت
@datacub/webولا أي شيء تحت@datacubمن npm: هذا الاسم في npm مو تابع لـ datacub.
وسم السكربت
للموقع اللي ما فيه خطوة بناء، الصق هذا قبل </head>. الخاصية data-key تشغّل الـ SDK أول ما ينزل الملف.
<script src="https://ingest.datacub.example/v1/sdk/datacub-0.4.0.min.js" data-key="pk_live_YOUR_PROJECT_KEY" defer></script>وإذا تبي ترسل عن طريق بروكسي على نطاقك أضف data-api-host.
داخل تطبيق
في تطبيقات React و Vue و Next.js وغيرها اللي فيها خطوة بناء، الصق هذا في <head> بدال اللي فوق. يعرّف المتغير العام x على طول، فكودك يقدر يستدعيه قبل ما ينزل الملف: الاستدعاءات تنتظر بالترتيب وتنفّذ أول ما يوصل. وين الـ head في كل إطار.
<script>
(function (w, d, src) {
var q = (w.datacub = w.datacub || [])
;['init', 'track', 'identify', 'reset'].forEach(function (n) {
q[n] = function () { q.push([n].concat([].slice.call(arguments))) }
})
var s = d.createElement('script'); s.async = true; s.src = src; d.head.appendChild(s)
})(window, document, 'https://ingest.datacub.example/v1/sdk/datacub-0.4.0.min.js')
datacub.init('pk_live_YOUR_PROJECT_KEY')
</script>بعدها استخدم x العام في أي مكان من كود الواجهة، مثلًا datacub.track('signup_completed'). استدعه في معالجات الأحداث والـ effects، مو في كود يشتغل على السيرفر، لأن x ما يكون موجود هناك.
TypeScript
احفظ ملف الأنواع في مشروعك. يعطي x العام أنواعه، ويصدّر أنواع الخيارات (import type { InitOptions } from './x'):
curl -o src/datacub.d.ts https://ingest.datacub.example/v1/sdk/datacub-0.4.0.d.tsالخيارات
مرّرها لـ datacub.init في الكود:
| الخيار | الافتراضي | وش يسوي |
|---|---|---|
apiHost | https://ingest.datacub.example | وين تروح الأحداث: خادم الاستقبال حق datacub أو البروكسي حقك. لازم يكون https (أو http://localhost) |
hashRouting | false | يعامل #/route كصفحات، للراوترات اللي تعتمد على الهاش |
autocapture | true | النقرات وإرسال النماذج. مشاهدات الصفحات ومغادرتها شغّالة دايم |
release | لا شيء | رقم إصدار تطبيقك أو معرّف النشر، ينرسل مع كل حدث |
datacub.init('pk_live_YOUR_PROJECT_KEY', { release: '2026.11.1', hashRouting: false })init يشتغل مرة وحدة؛ والاستدعاءات اللي بعده تنتجاهل.
بروكسي على نطاقك
بعض مانعات الإعلانات توقف الطلبات الرايحة لخوادم التحليلات. حوّل POST /v1/batch من مسار على نطاقك إلى خادم الاستقبال حق datacub، وبعدها وجّه الـ SDK له:
datacub.init('pk_live_YOUR_PROJECT_KEY', { apiHost: 'https://www.example.sa/datacub' })كذا الـ SDK يرسل إلى https://www.example.sa/datacub/v1/batch. مرّر الطلب زي ما هو بدون تعديل.
وش يجمعه الـ SDK
فوق مشاهدات الصفحات ومغادرتها والنقرات، الإصدار 0.2.0 يجمع السياق اللي يفسّرها:
- نص الأزرار والروابط اللي ينقر عليها الزائر: النص الظاهر في العنصر نفسه، بحد أقصى 100 حرف، بعد إزالة الإيميلات وأرقام الجوال والمعرّفات والتوكنات. وما ينجمع أبدًا نص مكتوب داخل حقول الإدخال أو مربعات النص أو القوائم المنسدلة أو المناطق القابلة للتحرير. وإذا ما فيه نص قصير على الزر، ياخذ
aria-labelأوtitleأوaltالصورة. - عناوين الصفحات، بعد تنظيفها، بحد أقصى 200 حرف.
- قيم الرابط (query) اللي تشبه رموز يحطها موقعك في الرابط، مثل
?sort=price_descأو?category=shoes. وما ننجمع أبد اللي كتبه الشخص: البحث والأسماء والعناوين والرسائل، وأي قيمة فيها مسافة أو أطول من 40 حرف، والمفاتيح الحساسة مثلtokenوcodeوkeyوsecretوpasswordوotpوstateوsession، وأي قيمة يعلّمها الكاشف، كلها يبقى مفتاحها وقيمتها فاضية. والقيم اللي تشبه المعرّفات تصير:id. - أخطاء JavaScript: الرسالة (بعد تنظيفها) وأعلى 5 إطارات من مكدس الاستدعاءات، والروابط مختصرة إلى النطاق والمسار.
- طلبات
fetchو XHR الفاشلة والبطيئة (3 ثواني أو أكثر): الطريقة، والنطاق مع المسار بعد استبدال المعرّفات، والحالة، والمدة. بدون الـ query أو الترويسات أو المحتوى. - تفاعل النماذج: أي حقول بدأ الزائر يعبّيها أو لمسها أو فيها خطأ، والوقت اللي قضاه في كل حقل. بدون القيم أو أطوالها أو ضغطات المفاتيح.
- سياق الجهاز والمتصفح، مرة لكل دفعة: حجم الشاشة، ونسبة البكسل، والمنطقة الزمنية، وأنوية المعالج، وذاكرة الجهاز، واللمس، والمؤشر، ونمط الألوان، وتقليل الحركة، والاتصال. وفي متصفحات Chromium أيضًا موديل الجهاز وإصدار النظام.
- مؤشرات Web Vitals والمهام الطويلة وإجمالي الموارد، عن طريق وحدة insights.
ما ينجمع أبدًا: القيم اللي تُكتب في النماذج، وكلمات المرور، وبيانات الدفع، وبيانات الدخول. وسمات الجهاز ما تُستخدم أبدًا لتحديد هوية الزائر: معرّف الزائر يبقى عشوائي. وعناوين IP كما هي ما تنحفظ أبدًا. اذكر هذي الفئات في إشعار الخصوصية عندك.
لو تبي تستثني منطقة كاملة، أضف data-datacub-no-capture لأي عنصر (و class datacub-no-capture تشتغل بعد): كل اللي داخله ما ينجمع.
اختر وش ينجمع
في الإعدادات، جمع البيانات للمشروع ستة مفاتيح، كلها مشغّلة افتراضيًا: نص الأزرار والروابط، عناوين الصفحات، قيم الرابط (query)، أخطاء JavaScript، الطلبات الفاشلة، تفاعل النماذج. لما يكون واحد منها مطفأ، datacub يشيل هذي الحقول عند الاستقبال، حتى لو الموقع لسا يرسلها.
والموقع يقدر بعد يمنع الـ SDK عنده من إرسالها بخيار التهيئة capture: اضبط أي واحد من text و title و query و errors و network و forms على false، مثلًا datacub.init('pk_live_YOUR_PROJECT_KEY', { capture: { text: false, query: false } }). وسم السكربت ما فيه خاصية لهذا؛ استخدم datacub.init.
والخيار insights: false ما يحمّل وحدة insights أبدًا (مؤشرات Web Vitals، والمهام الطويلة، وإجمالي الموارد، وتفاصيل حقول النماذج، وموديل الجهاز).
سياسة أمان المحتوى (CSP)
إذا موقعك يستخدم Content Security Policy، لازم script-src يسمح لخادم الاستقبال عندك بالملفين datacub-0.4.0.min.js و insights-0.2.0.min.js (الوحدة تنحمّل من https://ingest.datacub.example/v1/sdk/insights-0.2.0.min.js)، ولازم connect-src يسمح لنفس الخادم.
وش ما يرسله الـ SDK أبد
قيم الحقول، وكلمات المرور، وبيانات الدفع، وبيانات الدخول، وأجزاء الهاش في الرابط، وأي شيء داخل عنصر عليه class="datacub-no-capture" أو data-datacub-no-capture. المعرّفات اللي في المسارات تنستبدل (/orders/1234 تصير /orders/:id). والقيم اللي تشبه إيميل أو رقم جوال أو هوية وطنية أو رقم بطاقة أو توكن تنحجب على الجهاز، ومرة ثانية على السيرفر. التفاصيل في الخصوصية.