الصيغة
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, notctaClickorCTAClick - Be specific enough to be self-explanatory in reports:
signup_completedis better thancompleted - 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_identifiersfor 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)