مرجع إعداد SDK

يُضبَط SDK باستدعاء واحد هو scanova('init', siteId, options). توثّق هذه الصفحة كل خيار متاح.

الصيغة

scanova('init', 'YOUR_SITE_ID', {
  // options here
});

مرجع الخيارات

الخيار	النوع	الافتراضي	الوصف
`autoPageview`	boolean	`false`	يرسل تلقائيًا حدث `pageview` عند كل تحميل للصفحة.
`autoClicks`	boolean	`false`	يتتبّع تلقائيًا النقرات على الروابط والأزرار وعناصر `[role="button"]`.
`autoForms`	boolean	`false`	يتتبّع تلقائيًا عمليات إرسال النماذج.
`autoScroll`	boolean	`false`	يتتبّع عمق التمرير عند العلامات 25% و50% و75% و90%.
`debug`	boolean	`false`	يطبع نشاط SDK في وحدة تحكم المتصفح. مفيد أثناء التطوير.
`endpoint`	string	`https://t.scanova.io/ct`	يستبدل نقطة نهاية جمع الأحداث. لا تغيّره إلا بتوجيه من دعم Scanova.

تفاصيل الخيارات

`autoPageview`

يُطلق حدث pageview في كل مرة يُهيَّأ فيها SDK على صفحة، وهو ما يحدث تلقائيًا عند التحميل الكامل للصفحات. وفي تطبيقات الصفحة الواحدة، يشرح دليل SPA كيفية إطلاق أحداث مشاهدة الصفحة عند تغيّر المسار.

scanova('init', 'YOUR_SITE_ID', { autoPageview: true });

يتضمن كل حدث pageview الحقول page_url وreferrer وscan_session_id إضافةً إلى سياق الجهاز والزائر. راجع الأحداث التلقائية للاطلاع على الحمولة الكاملة.

`autoClicks`

يستمع إلى النقرات على:

وسوم <a>
وسوم <button>
العناصر التي تحمل role="button"

يتضمن حدث النقر الملتقَط الحقول element_type وelement_text، وللروابط destination_url اختياريًا. نصيحة: أضف data-scnv-name="My Button" إلى أي عنصر لتجاوز التسمية الملتقَطة:

<button data-scnv-name="Pricing CTA">Start Trial</button>

`autoForms`

يستمع إلى حدث submit في عناصر <form>. يلتقط form_name وform_action. أما قيم الحقول فـلا تُلتقط أبدًا — يُلتقط معرّف النموذج فقط. نصيحة: أضف data-scnv-name="Contact Form" إلى نموذج لمنحه اسمًا مقروءًا في التقارير.

`autoScroll`

يُطلق أحداث عمق التمرير عندما يتجاوز الزائر 25% و50% و75% و90% من ارتفاع الصفحة. وتُطلَق كل علامة مرة واحدة فقط لكل تحميل، وتتضمن scroll_depth في البيانات الوصفية.

`debug`

يفعّل التسجيل في وحدة التحكم. استخدمه أثناء التطوير للتأكد من أن SDK يُهيَّأ ويلتقط الأحداث ويرسلها بشكل صحيح.

scanova('init', 'YOUR_SITE_ID', { debug: true });
// Console output:
// [QCG SDK] Initialized with Site ID: YOUR_SITE_ID
// [QCG SDK] Loaded version 1.x.x

عطّل debug في بيئة الإنتاج — فالخيار false افتراضيًا.

الإعداد الموصى به للإنتاج

scanova('init', 'YOUR_SITE_ID', {
  autoPageview: true,
  autoClicks: true,
  autoForms: true,
  autoScroll: true,
  debug: false
});

الإعداد الأدنى (مشاهدات الصفحة فقط)

scanova('init', 'YOUR_SITE_ID', {
  autoPageview: true
});

الإعداد اليدوي فقط (دون تتبع تلقائي)

استخدم هذا إن أردت تحكمًا كاملًا فيما يُتتبَّع — عندها تُرسل كل حدث صراحةً عبر scanova('track', ...).

scanova('init', 'YOUR_SITE_ID', {
  autoPageview: false,
  autoClicks: false,
  autoForms: false,
  autoScroll: false
});

مهم: استدعاء init مرة واحدة لكل تحميل للصفحة

استدعِ scanova('init', ...) مرة واحدة لكل دورة حياة للصفحة. فالاستدعاء المتكرر يسجّل مستمعي تتبع مكرّرين ويؤدي إلى مضاعفة الأحداث. في تطبيقات الصفحة الواحدة، استدعِ init مرة واحدة عند إقلاع التطبيق، لا عند كل تغيّر للمسار. واستخدم دليل SPA لتتبع تغيّرات المسار.

تعطيل التتبع لمستخدمين محددين

لا يتضمن SDK دالة disable() مدمجة. ولمنع تتبع مستخدمين محددين (موظفين مسجّلي الدخول، أو من انسحبوا، أو الروبوتات)، تجنّب تحميل النص البرمجي شرطيًا من الأساس:

<script>
  // Example: skip tracking for your own team
  const isInternalUser = document.cookie.includes('internal_user=true');

  if (!isInternalUser) {
    (function(w,d,s,o,f,js,fjs){
      w['ScanovaTrackingObject']=o;w[o]=w[o]||function(){(w[o].q=w[o].q||[]).push(arguments)};
      js=d.createElement(s),fjs=d.getElementsByTagName(s)[0];
      js.id=o;js.src=f;js.async=1;fjs.parentNode.insertBefore(js,fjs);
    })(window,document,'script','scanova','https://cdn.scanova.io/ct/js/qcg.min.js');
    scanova('init', 'YOUR_SITE_ID', { autoPageview: true });
  }
</script>

ينطبق النمط نفسه على موافقة اللائحة العامة لحماية البيانات — لا تحمّل SDK إلا بعد منح الزائر موافقته على التتبع. راجع الخصوصية واللائحة العامة لحماية البيانات للتفاصيل.

نظرة عامة

SDK المتصفح

جهة الخادم

مرجع الواجهة

الموارد

الصيغة

مرجع الخيارات

تفاصيل الخيارات

`autoPageview`

`autoClicks`

`autoForms`

`autoScroll`

`debug`

الإعداد الموصى به للإنتاج

الإعداد الأدنى (مشاهدات الصفحة فقط)

الإعداد اليدوي فقط (دون تتبع تلقائي)

مهم: استدعاء init مرة واحدة لكل تحميل للصفحة

تعطيل التتبع لمستخدمين محددين

​الصيغة

​مرجع الخيارات

​تفاصيل الخيارات

​autoPageview

​autoClicks

​autoForms

​autoScroll

​debug

​الإعداد الموصى به للإنتاج

​الإعداد الأدنى (مشاهدات الصفحة فقط)

​الإعداد اليدوي فقط (دون تتبع تلقائي)

​مهم: استدعاء init مرة واحدة لكل تحميل للصفحة

​تعطيل التتبع لمستخدمين محددين

الصيغة

مرجع الخيارات

تفاصيل الخيارات

`autoPageview`

`autoClicks`

`autoForms`

`autoScroll`

`debug`

الإعداد الموصى به للإنتاج

الإعداد الأدنى (مشاهدات الصفحة فقط)

الإعداد اليدوي فقط (دون تتبع تلقائي)

مهم: استدعاء init مرة واحدة لكل تحميل للصفحة

تعطيل التتبع لمستخدمين محددين