Quickstart guide

Tag Manager

Consent & Privacy

Analytics

Performance

API Reference

Add Custom Events

Custom events let you track specific user interactions beyond pageviews.

Basic Usage

// Track a button click
etiquetta.track('button_click', { button: 'signup' })
// Track a form submission
etiquetta.track('form_submit', { form: 'contact', source: 'footer' })
// Track a purchase
etiquetta.track('purchase', { plan: 'pro', amount: 99, currency: 'EUR' })
// Track a file download
etiquetta.track('download', { file: 'whitepaper.pdf', format: 'pdf' })
// Track with no properties
etiquetta.track('cta_viewed')

API

etiquetta.track(name, props)
ParameterTypeRequiredDescription
namestringYesEvent name (e.g. “signup“, “purchase“)
propsobjectNoKey-value properties (values can be strings, numbers, or booleans)

The name must be a non-empty string. The props object is serialized to JSON and stored with the event. Keep property names and values concise.

Practical Examples

E-commerce

// Product viewed
etiquetta.track('product_view', {
  product_id: 'SKU-123',
  category: 'shoes',
  price: 79.99
})
// Add to cart
etiquetta.track('add_to_cart', {
  product_id: 'SKU-123',
  quantity: 1
})
// Checkout completed
etiquetta.track('checkout', {
  order_id: 'ORD-456',
  total: 79.99,
  items: 1
})

SaaS

// Feature usage
etiquetta.track('feature_used', { feature: 'export', format: 'csv' })
// Onboarding step
etiquetta.track('onboarding_step', { step: 3, step_name: 'invite_team' })
// Upgrade prompt shown
etiquetta.track('upgrade_prompt', { trigger: 'feature_gate', feature: 'api_access' })

Content

// Article read
etiquetta.track('article_read', { slug: 'getting-started', category: 'tutorial' })
// Video play
etiquetta.track('video_play', { video_id: 'intro-tour', duration: 120 })
// Search performed
etiquetta.track('search', { query: 'analytics setup', results: 5 })

Forms

// Attach to a form
document.querySelector('#signup-form').addEventListener('submit', () => {
  etiquetta.track('signup_form_submit', { source: 'homepage' })
})
// Attach to a button
document.querySelector('#cta-button').addEventListener('click', () => {
  etiquetta.track('cta_click', { variant: 'blue', position: 'hero' })
})

React

function SignupButton() {
  return (
    <button onClick={() => etiquetta.track('signup_click', { source: 'nav' })}>
      Sign Up
    </button>
  )
}

Viewing Custom Events

Custom events appear in your dashboard under the Custom Events section. Each event name is listed with its total count and unique visitor count for the selected date range.

To filter by custom events, use the stats API:

GET /api/stats/events?domain=example.com&days=30