Événements personnalisés

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

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.

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.

Exemples

Clic sur un bouton

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

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 :

scanova('track', 'signup_completed', {
  method: 'email',
  plan: 'free'
});

Pour les confirmations d’achat ou d’inscription qui ont lieu côté serveur, utilisez plutôt les événements serveur. Ils sont plus fiables et ne peuvent pas être bloqués par les extensions de navigateur.

Engagement vidéo

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

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

Interaction produit

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

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

Clic vers un site externe

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

// 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 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)

Vue d'ensemble

SDK navigateur

Côté serveur

Référence API

Ressources

Syntaxe

Exemples

Clic sur un bouton

Inscription terminée

Engagement vidéo

Interaction produit

Interaction avec onglets ou accordéons

Clic vers un site externe

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

Event naming best practices

Metadata best practices

When to use server events instead

​Syntaxe

​Exemples

​Clic sur un bouton

​Inscription terminée

​Engagement vidéo

​Interaction produit

​Interaction avec onglets ou accordéons

​Clic vers un site externe

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

​Event naming best practices

​Metadata best practices

​When to use server events instead

Syntaxe

Exemples

Clic sur un bouton

Inscription terminée

Engagement vidéo

Interaction produit

Interaction avec onglets ou accordéons

Clic vers un site externe

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

Event naming best practices

Metadata best practices

When to use server events instead