Custom Events

Custom events let you track specific user actions that matter to your business — beyond what auto-tracking captures. You define the event name and the metadata, and the SDK sends it with full QR attribution attached automatically.

Syntax

scanova('track', 'event_name', { key: 'value' });

event_name — a string that describes the action. Use snake_case.
metadata — an optional object with any key-value data relevant to the event. Max 10 KB.

You can call scanova('track', ...) at any point after scanova('init', ...) runs — from event listeners, async callbacks, or any other JavaScript context.

Examples

Button click

Track when a user clicks a specific call-to-action:

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

Send this after your sign-up form submission is confirmed (client-side):

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

For purchase or sign-up confirmations that happen server-side, use Server Events instead. Server events are more reliable and cannot be blocked by browser extensions.

Video engagement

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

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

Product interaction

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

Tab or accordion interaction

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

Link click to external site

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

Choosing between custom events and auto-tracking

Situation	Use
Track all link and button clicks with minimal setup	`autoClicks: true`
Track a specific button with custom metadata	`scanova('track', ...)`
Track all form submissions	`autoForms: true`
Track a specific form with field-level context (non-PII)	`scanova('track', ...)`
Any interaction the auto-tracker does not cover	`scanova('track', ...)`

You can use both together — autoClicks: true plus selective custom events for high-value actions.

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)

Overview

Browser SDK

Server-Side

API Reference

Resources

Syntax

Examples

Button click

Video engagement

Product interaction

Tab or accordion interaction

Link click to external site

Choosing between custom events and auto-tracking

Event naming best practices

Metadata best practices

When to use server events instead

​Syntax

​Examples

​Button click

​Sign-up completed

​Video engagement

​Product interaction

​Tab or accordion interaction

​Link click to external site

​Choosing between custom events and auto-tracking

​Event naming best practices

​Metadata best practices

​When to use server events instead

Syntax

Examples

Button click

Sign-up completed

Video engagement

Product interaction

Tab or accordion interaction

Link click to external site

Choosing between custom events and auto-tracking

Event naming best practices

Metadata best practices

When to use server events instead