Skip to main content
تتيح لك الأحداث المخصصة تتبّع إجراءات المستخدم التي تهم نشاطك تحديدًا — بما يتجاوز ما يلتقطه التتبع التلقائي. أنت تحدد اسم الحدث وبياناته الوصفية، ويرسله SDK مع نسبة كاملة إلى رمز QR.

الصيغة

  • event_name — نص يصف الإجراء. استخدم صيغة snake_case.
  • metadata — كائن اختياري يضم أي بيانات مفتاح-قيمة تخص الحدث. بحد أقصى 10 كيلوبايت.
يمكنك استدعاء scanova('track', ...) في أي وقت بعد تنفيذ scanova('init', ...) — من مستمعي الأحداث، أو الاستدعاءات غير المتزامنة، أو أي سياق JavaScript آخر.
عند الإرسال، يضبط SDK الحقل event_type على custom ويضع اسمك في حقل event_name في المستوى الأعلى — لا داخل metadata. ويختلف ذلك عن استدعاء POST /ct مباشرةً، حيث يحمل event_type الاسم الدلالي نفسه. راجع مرجع نموذج الحدث.

أمثلة

النقر على زر

تتبّع نقر المستخدم على دعوة إلى إجراء محددة:

إتمام التسجيل

أرسل هذا بعد تأكيد إرسال نموذج التسجيل من جهة العميل:
لتأكيدات الشراء أو التسجيل التي تتم من جهة الخادم، استخدم أحداث الخادم بدلًا من ذلك. فهي أكثر موثوقية ولا يمكن لإضافات المتصفح حجبها.

التفاعل مع الفيديو

التفاعل مع المنتجات

التفاعل مع التبويبات أو الأكورديون

النقر على رابط خارجي

الاختيار بين الأحداث المخصصة والتتبع التلقائي

يمكنك الجمع بين الاثنين — autoClicks: true مع أحداث مخصصة منتقاة للإجراءات عالية القيمة.

Event naming best practices

  • Use snake_case: cta_click, not ctaClick or CTAClick
  • Be specific enough to be self-explanatory in reports: signup_completed is better than completed
  • Be consistent: pick one name and stick to it. Changing event names later fragments your historical data
  • Do not include user-identifying information in the event name

Metadata best practices

  • Keep metadata flat where possible — deeply nested objects are harder to query
  • Max object size: 10 KB
  • Max nesting depth: 5 levels
  • Never include raw email addresses, phone numbers, or other PII — use server events with user_identifiers for that
  • Use stable keys — changing key names later fragments your data

When to use server events instead

Use Server-Side Events rather than custom browser events when:
  • The action happens on your server (payment confirmation, CRM creation, email verification)
  • You need to pass a conversion value (order total, subscription price)
  • You want to include hashed user identifiers for identity matching
  • You need guaranteed delivery (server events cannot be blocked by ad blockers)