> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanova.io/llms.txt
> Use this file to discover all available pages before exploring further.

# الأحداث المخصصة

> تتبّع إجراءات محددة على موقعك باستخدام scanova('track', ...): النقر على الأزرار، وإتمام التسجيل، وتشغيل الفيديو، وأي تفاعل آخر يهمّك في نشاطك.

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

## الصيغة

```javascript theme={null}
scanova('track', 'event_name', { key: 'value' });
```

* **`event_name`** — نص يصف الإجراء. استخدم صيغة `snake_case`.
* **`metadata`** — كائن اختياري يضم أي بيانات مفتاح-قيمة تخص الحدث. بحد أقصى 10 كيلوبايت.

يمكنك استدعاء `scanova('track', ...)` في أي وقت بعد تنفيذ `scanova('init', ...)` — من مستمعي الأحداث، أو الاستدعاءات غير المتزامنة، أو أي سياق JavaScript آخر.

<Note>
  عند الإرسال، يضبط SDK الحقل `event_type` على `custom` ويضع اسمك في حقل `event_name` في المستوى الأعلى — لا داخل `metadata`. ويختلف ذلك عن استدعاء `POST /ct` مباشرةً، حيث يحمل `event_type` الاسم الدلالي نفسه. راجع [مرجع نموذج الحدث](/ar/conversion-tracking/event-model).
</Note>

## أمثلة

### النقر على زر

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

```javascript theme={null}
document.getElementById('start-trial-btn').addEventListener('click', () => {
  scanova('track', 'cta_click', {
    button_text: 'Start Free Trial',
    section: 'hero',
    plan: 'pro'
  });
});
```

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

أرسل هذا بعد تأكيد إرسال نموذج التسجيل من جهة العميل:

```javascript theme={null}
scanova('track', 'signup_completed', {
  method: 'email',
  plan: 'free'
});
```

<Note>
  لتأكيدات الشراء أو التسجيل التي تتم **من جهة الخادم**، استخدم [أحداث الخادم](/ar/conversion-tracking/server/send-events) بدلًا من ذلك. فهي أكثر موثوقية ولا يمكن لإضافات المتصفح حجبها.
</Note>

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

```javascript theme={null}
video.addEventListener('play', () => {
  scanova('track', 'video_play', { video_id: 'intro-tour' });
});

video.addEventListener('ended', () => {
  scanova('track', 'video_complete', { video_id: 'intro-tour' });
});
```

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

```javascript theme={null}
document.querySelectorAll('.product-card').forEach(card => {
  card.addEventListener('click', () => {
    scanova('track', 'product_click', {
      product_id: card.dataset.productId,
      product_name: card.dataset.productName,
      position: card.dataset.position
    });
  });
});
```

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

```javascript theme={null}
document.querySelectorAll('.tab-btn').forEach(btn => {
  btn.addEventListener('click', () => {
    scanova('track', 'tab_click', { tab_name: btn.textContent.trim() });
  });
});
```

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

```javascript theme={null}
document.querySelectorAll('a[href^="http"]').forEach(link => {
  link.addEventListener('click', () => {
    scanova('track', 'external_link_click', { destination: link.href });
  });
});
```

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

| الحالة                                                | استخدم                  |
| ----------------------------------------------------- | ----------------------- |
| تتبّع كل النقرات على الروابط والأزرار بأقل إعداد ممكن | `autoClicks: true`      |
| تتبّع زر محدد ببيانات وصفية خاصة                      | `scanova('track', ...)` |
| تتبّع كل عمليات إرسال النماذج                         | `autoForms: true`       |
| تتبّع نموذج محدد مع سياق الحقول (دون بيانات شخصية)    | `scanova('track', ...)` |
| أي تفاعل لا يغطيه التتبع التلقائي                     | `scanova('track', ...)` |

يمكنك الجمع بين الاثنين — `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

```javascript theme={null}
// Good
scanova('track', 'download_click', {
  file_name: 'product-guide.pdf',
  section: 'resources'
});

// Avoid
scanova('track', 'download_click', {
  user_email: 'john@example.com',  // never include PII
  data: { nested: { too: { deep: { for: 'queries' } } } }
});
```

## When to use server events instead

Use [Server-Side Events](/ar/conversion-tracking/server/send-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)