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

# Événements personnalisés

> Suivez des actions précises sur votre site avec scanova('track', ...) : clics sur boutons, inscriptions, lectures de vidéo et toute autre interaction.

Les événements personnalisés vous permettent de suivre les actions qui comptent pour votre activité, au-delà de ce que capture le suivi automatique. Vous définissez le nom et les métadonnées, le SDK envoie l'événement avec l'attribution QR déjà jointe.

## Syntaxe

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

* **`event_name`** — une chaîne décrivant l'action. Utilisez le `snake_case`.
* **`metadata`** — un objet facultatif contenant les données clé-valeur de votre choix. 10 Ko maximum.

Vous pouvez appeler `scanova('track', ...)` à tout moment après l'exécution de `scanova('init', ...)` : depuis des écouteurs d'événements, des callbacks asynchrones ou tout autre contexte JavaScript.

<Note>
  Sur le réseau, le SDK envoie chaque événement personnalisé avec `event_type` à `custom` et votre nom dans un champ `event_name` de premier niveau, et non dans `metadata`. Cela diffère d'un appel direct à `POST /ct`, où c'est `event_type` qui porte le nom sémantique. Voir la [référence du modèle d'événement](/fr/conversion-tracking/event-model).
</Note>

## Exemples

### Clic sur un bouton

Suivre le clic sur un appel à l'action précis :

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

### Inscription terminée

Envoyez ceci une fois l'envoi de votre formulaire d'inscription confirmé côté client :

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

<Note>
  Pour les confirmations d'achat ou d'inscription qui ont lieu **côté serveur**, utilisez plutôt les [événements serveur](/fr/conversion-tracking/server/send-events). Ils sont plus fiables et ne peuvent pas être bloqués par les extensions de navigateur.
</Note>

### Engagement vidéo

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

### Interaction produit

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

### Interaction avec onglets ou accordéons

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

### Clic vers un site externe

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

## Choisir entre événements personnalisés et suivi automatique

| Situation                                                                           | Utilisez                |
| ----------------------------------------------------------------------------------- | ----------------------- |
| Suivre tous les clics sur liens et boutons avec un minimum de configuration         | `autoClicks: true`      |
| Suivre un bouton précis avec des métadonnées propres                                | `scanova('track', ...)` |
| Suivre tous les envois de formulaire                                                | `autoForms: true`       |
| Suivre un formulaire précis avec le contexte des champs (sans données personnelles) | `scanova('track', ...)` |
| Toute interaction non couverte par le suivi automatique                             | `scanova('track', ...)` |

Vous pouvez combiner les deux : `autoClicks: true` et des événements personnalisés ciblés pour les actions à forte valeur.

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