> ## 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.

# Eigene Ereignisse

> Bestimmte Nutzeraktionen auf Ihrer Website mit scanova('track', ...) erfassen: Klicks auf Schaltflächen, Anmeldungen, Videostarts und beliebige weitere.

Mit eigenen Ereignissen erfassen Sie gezielt die Nutzeraktionen, die für Ihr Geschäft zählen — über das hinaus, was das Auto-Tracking abdeckt. Sie legen Name und Metadaten fest, das SDK sendet das Ereignis samt vollständiger QR-Zuordnung.

## Syntax

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

* **`event_name`** — eine Zeichenkette, die die Aktion beschreibt. Verwenden Sie `snake_case`.
* **`metadata`** — ein optionales Objekt mit beliebigen Schlüssel-Wert-Daten zum Ereignis. Maximal 10 KB.

Sie können `scanova('track', ...)` jederzeit nach `scanova('init', ...)` aufrufen — aus Event-Listenern, asynchronen Callbacks oder jedem anderen JavaScript-Kontext.

<Note>
  Auf der Leitung sendet das SDK jedes eigene Ereignis mit `event_type` gleich `custom` und Ihrem Namen im Feld `event_name` der obersten Ebene — nicht innerhalb von `metadata`. Das unterscheidet sich vom direkten Aufruf von `POST /ct`, wo `event_type` den inhaltlichen Namen selbst trägt. Siehe [Referenz zum Ereignismodell](/de/conversion-tracking/event-model).
</Note>

## Beispiele

### Klick auf eine Schaltfläche

Erfassen, wann eine Person auf einen bestimmten Call-to-Action klickt:

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

### Abgeschlossene Anmeldung

Senden Sie dies, nachdem die Absendung Ihres Anmeldeformulars clientseitig bestätigt wurde:

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

<Note>
  Für Kauf- oder Anmeldebestätigungen, die **serverseitig** erfolgen, verwenden Sie stattdessen [Server-Ereignisse](/de/conversion-tracking/server/send-events). Server-Ereignisse sind zuverlässiger und lassen sich nicht von Browser-Erweiterungen blockieren.
</Note>

### Video-Interaktion

```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' });
});
```

### Produkt-Interaktion

```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
    });
  });
});
```

### Interaktion mit Tabs oder Akkordeons

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

### Klick auf einen externen Link

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

## Eigene Ereignisse oder Auto-Tracking?

| Situation                                                                      | Verwenden Sie           |
| ------------------------------------------------------------------------------ | ----------------------- |
| Alle Link- und Schaltflächen-Klicks mit minimalem Aufwand erfassen             | `autoClicks: true`      |
| Eine bestimmte Schaltfläche mit eigenen Metadaten erfassen                     | `scanova('track', ...)` |
| Alle Formularabsendungen erfassen                                              | `autoForms: true`       |
| Ein bestimmtes Formular mit Feldkontext erfassen (ohne personenbezogene Daten) | `scanova('track', ...)` |
| Jede Interaktion, die das Auto-Tracking nicht abdeckt                          | `scanova('track', ...)` |

Sie können beides kombinieren — `autoClicks: true` plus gezielte eigene Ereignisse für besonders wichtige Aktionen.

## 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](/de/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)