Custom Events

Track user actions and interactions beyond page views

Overview

Custom events in Vemetric allow you to track any user interaction on your website. While page views are tracked automatically, custom events give you deep insights into button clicks, form submissions, video plays, purchases, and any other action that matters to your business.

What are Custom Events?

Custom events represent specific user actions:

• Button clicks (“Add to Cart”, “Download”, “Sign Up”)
• Form submissions (contact forms, newsletter signups)
• Media interactions (video plays, audio starts)
• Purchases and transactions
• Feature usage (search, filters, settings changes)
• Any custom action you want to track

Unlike page views which are automatically tracked, custom events require you to implement tracking code in your application.

Tracking Custom Events

Implement event tracking using the Vemetric SDK:

// Basic event tracking
vemetric.trackEvent('Button Clicked');

// Event with properties
vemetric.trackEvent('Product Added to Cart', {
  product_id: '12345',
  product_name: 'Premium Widget',
  price: 49.99,
  category: 'Widgets',
  quantity: 1
});

Event Naming Conventions

Follow these best practices for event names:

Use descriptive names

Choose names that clearly describe the action: “Purchase Completed” instead of “Event 1”

Be consistent

Use the same naming pattern across your application (e.g., “Verb + Noun” like “Button Clicked”, “Form Submitted”)

Use past tense

Name events as completed actions: “Downloaded” instead of “Download”

Avoid special characters

Stick to letters, numbers, and spaces for better compatibility

Event Properties

Enrich your events with additional context using properties:

vemetric.trackEvent('Video Played', {
  video_title: 'Product Demo',
  video_duration: 180, // seconds
  video_id: 'demo-v1',
  autoplay: false,
  player_version: '2.1.0'
});

Property Data Types

Event properties support multiple data types:

• Strings: Text values ("Product Demo", "mobile")
• Numbers: Integers or decimals (42, 19.99)
• Booleans: True/false values (true, false)
• Dates: ISO date strings ("2024-03-15T10:30:00Z")

Property values should be simple types. Avoid nested objects or arrays - flatten your data structure instead.

Common Property Patterns

E-commerce

vemetric.trackEvent('Purchase Completed', {
  order_id: 'ORD-12345',
  total: 149.97,
  currency: 'USD',
  items_count: 3,
  payment_method: 'credit_card',
  shipping_method: 'express'
});

Forms

vemetric.trackEvent('Form Submitted', {
  form_name: 'contact_form',
  form_location: '/contact',
  fields_count: 5,
  submission_time: new Date().toISOString()
});

Content

vemetric.trackEvent('Article Read', {
  article_title: 'Getting Started Guide',
  article_category: 'tutorials',
  word_count: 1200,
  read_time: 360, // seconds
  scroll_depth: 95 // percentage
});

Features

vemetric.trackEvent('Search Performed', {
  search_query: 'analytics dashboard',
  results_count: 24,
  filter_applied: true,
  search_category: 'documentation'
});

Events Page

The Events page shows a real-time stream of all events happening on your website:

Live Event Stream

View events as they occur:

• Real-time updates: New events appear automatically every 5 seconds
• Live indicator: Green “Live” badge shows the stream is active
• Chronological order: Most recent events appear at the top
• Date separators: Events grouped by day for easy navigation

Event Card Information

Each event card displays:

• Event name: The action that was tracked
• Timestamp: Exact date and time (with “time ago” indicator)
• User information: Avatar and display name/identifier
• Page context: Which page the event occurred on
• Device info: Browser, OS, and device type
• Event properties: Custom data attached to the event

Click on any event to expand and see all event properties in detail.

Event Properties View

Expanded event cards show all properties:

{
  "product_id": "SKU-789",
  "product_name": "Premium Widget",
  "price": 49.99,
  "currency": "USD",
  "category": "Widgets",
  "in_stock": true,
  "discount_applied": false
}

Navigating to User Journey

From any event card:

• Click the user avatar or name to view their complete journey
• See all events from that user in chronological order
• Understand the context around this specific event

Filtering Events

Narrow down the event stream to find specific events:

1. Click Add Filter

   Open the filter menu from the Events page

2. Select Event Type

   Choose “Event” from the filter types

3. Choose Events

   Select one or more event names to display

4. Add More Filters

   Optionally filter by country, city, browser, device, or OS

Filter Combinations

Combine multiple filters for precise analysis:

• Event + Geography: See “Purchase Completed” events from United States
• Event + Device: Track “Sign Up” events on mobile devices
• Event + Browser: Find events from specific browser versions
• Multiple Events: Show several related events together

Filters on the Events page use OR logic within the same filter type and AND logic across different filter types.

Dashboard Event Analytics

Events also appear in your dashboard:

Events Card

The dashboard Events card shows:

• Total event count for the selected time period
• Event breakdown by event name
• Event counts per event type
• Trend indicators comparing to previous period

Event Chart Overlay

Add event volume to your dashboard chart:

1. The chart shows events as bars overlaid on your metrics
2. See how event frequency correlates with user activity
3. Toggle events on/off using the chart controls
4. Identify traffic spikes and their relationship to user actions

Event Properties Analysis

Click any event in the dashboard card to:

• View all properties tracked with that event
• See property value distribution
• Click a property to see all unique values
• Analyze how property values change over time

Event in Funnels

Use custom events as funnel steps:

// Track funnel steps with events
vemetric.trackEvent('Sign Up Started');
vemetric.trackEvent('Email Verified');
vemetric.trackEvent('Profile Created');
vemetric.trackEvent('Onboarding Completed');

Then create a funnel using these events to track conversion rates.

Events are more reliable than page views for funnel tracking in single-page applications where URLs don’t change.

Use Cases

E-commerce Tracking

Track product views, add-to-cart, checkout initiation, and purchase completion.

Form Analytics

Monitor form starts, field interactions, validation errors, and successful submissions.

Feature Usage

Understand which features users engage with and how often.

Content Engagement

Track article reads, video plays, downloads, and social shares.

Error Tracking

Log when users encounter errors or issues.

A/B Testing

Track which variant users see and their subsequent actions.

Event Pagination

The Events page loads events in batches:

• 50 events per page initially loaded
• “Load More” button to fetch older events
• Infinite scroll capability
• Real-time updates at the top

Real-Time Updates

The event stream updates automatically:

• New events appear at the top every 5 seconds
• No manual refresh needed
• Live indicator shows connection status
• Smooth animations for new events

The event stream will pause updates if you scroll down to review older events. Scroll back to the top to resume real-time updates.

Event Best Practices

1. Track meaningful actions

   Focus on events that provide business value or insights into user behavior.

2. Use consistent naming

   Establish naming conventions and stick to them across your application.

3. Include relevant properties

   Add context that helps you analyze and segment events, but avoid over-tracking.

4. Test your implementation

   Verify events are firing correctly before deploying to production.

5. Document your events

   Maintain a list of all events and their properties for your team.

Common Implementation Patterns

Button Click Tracking

document.querySelector('#signup-button').addEventListener('click', () => {
  vemetric.trackEvent('Sign Up Button Clicked', {
    button_location: 'hero_section',
    button_text: 'Get Started Free'
  });
});

Form Submission Tracking

document.querySelector('#contact-form').addEventListener('submit', (e) => {
  e.preventDefault();
  
  vemetric.trackEvent('Contact Form Submitted', {
    form_id: 'contact',
    email_provided: !!e.target.email.value,
    message_length: e.target.message.value.length
  });
  
  // Continue with form submission
});

Video Play Tracking

video.addEventListener('play', () => {
  vemetric.trackEvent('Video Started', {
    video_id: video.dataset.id,
    video_title: video.dataset.title,
    current_time: video.currentTime
  });
});

Debugging Events

Troubleshoot event tracking issues:

1. Check browser console: Look for Vemetric SDK errors
2. View Events page: Confirm events appear in real-time
3. Verify properties: Expand events to check property values
4. Test in isolation: Track test events to verify SDK connection
5. Check network tab: Ensure event requests are sent successfully

Next Steps

Installation

Set up the Vemetric SDK to start tracking events

User Journeys

See how events build complete user journey timelines

Funnels

Use events as funnel steps for conversion tracking

Filtering

Filter events by user attributes and properties