Umami Event Tracking: Complete Guide to Custom Events | OpsBlu Docs

Umami Event Tracking: Complete Guide to Custom Events

Everything you need to know about Umami event tracking. Track button clicks, form submissions, and custom conversions with data attributes and the...

Event Tracking Overview

Umami provides simple, privacy-focused event tracking through JavaScript, HTML data attributes, or server-side APIs. Track conversions, user actions, and custom goals without collecting personal data while maintaining full GDPR compliance.

Basic Event Tracking

Track events using the global umami object:

// Simple event
umami.track('button_clicked');

// Event with properties
umami.track('signup', {
  plan: 'pro',
  method: 'google'
});

// Event with multiple properties
umami.track('purchase', {
  product_id: 'PROD-123',
  amount: 99.99,
  currency: 'USD',
  quantity: 1
});

Data Attributes Method

Track events without JavaScript using HTML data attributes:

<!-- Basic event on click -->
<button data-umami-event="cta_clicked">Get Started</button>

<!-- Event with properties -->
<button
  data-umami-event="plan_selected"
  data-umami-event-plan="professional"
  data-umami-event-billing="annual">
  Choose Pro Plan
</button>

<!-- Track downloads -->
<a href="/guide.pdf"
   data-umami-event="download"
   data-umami-event-file="user_guide.pdf"
   data-umami-event-type="documentation">
  Download Guide
</a>

<!-- Track form submissions -->
<form data-umami-event="form_submitted"
      data-umami-event-form="contact_sales">
  <!-- form fields -->
</form>

<!-- Track outbound links -->
<a href="https://external.com"
   data-umami-event="external_link"
   data-umami-event-destination="partner_site">
  Visit Partner
</a>

Common Event Patterns

Conversion Events

// Lead generation
umami.track('lead_generated', {
  source: 'contact_form',
  form_type: 'demo_request'
});

// Signups
umami.track('signup_completed', {
  plan: 'starter',
  auth_method: 'email',
  source: 'homepage'
});

// Trial starts
umami.track('trial_started', {
  plan: 'business',
  trial_days: 14
});

// Subscription created
umami.track('subscription_created', {
  plan: 'professional',
  billing_cycle: 'annual',
  amount: 990
});

E-commerce Events

// Product views
umami.track('product_viewed', {
  product_id: 'SKU-789',
  product_name: 'Widget Pro',
  category: 'hardware',
  price: 299
});

// Add to cart
umami.track('add_to_cart', {
  product_id: 'SKU-789',
  quantity: 2,
  cart_value: 598
});

// Checkout progress
umami.track('checkout_started', {
  cart_value: 598,
  items_count: 2
});

umami.track('payment_info_entered');

// Purchase completed
umami.track('purchase_completed', {
  order_id: 'ORD-12345',
  total: 598,
  items: 2,
  payment_method: 'card'
});

Content Engagement

// Article reading
umami.track('article_read', {
  article_id: 'blog-456',
  category: 'tutorials',
  reading_time: 8
});

// Video interaction
umami.track('video_played', {
  video_id: 'demo-intro',
  duration: 180
});

umami.track('video_completed', {
  video_id: 'demo-intro',
  watch_percent: 100
});

// Downloads
umami.track('resource_downloaded', {
  resource_type: 'ebook',
  resource_name: 'Analytics Guide',
  format: 'pdf'
});

// Shares
umami.track('content_shared', {
  platform: 'twitter',
  content_type: 'blog_post',
  content_id: 'post-123'
});

Feature Usage

// Feature accessed
umami.track('feature_used', {
  feature_name: 'advanced_filters',
  usage_count: 'first_time'
});

// Export functionality
umami.track('data_exported', {
  format: 'csv',
  records: 1500,
  filter_applied: true
});

// Integration connected
umami.track('integration_enabled', {
  integration: 'zapier',
  trigger_type: 'webhook'
});

Server-Side Event Tracking

Track events from your backend using the Umami API:

// Node.js example
const fetch = require('node-fetch');

async function trackServerEvent(websiteId, eventName, eventData = {}) {
  await fetch(`https://your-umami-instance.com/api/send`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'User-Agent': 'YourApp/1.0'
    },
    body: JSON.stringify({
      type: 'event',
      payload: {
        website: websiteId,
        name: eventName,
        data: eventData,
        url: '/api/endpoint',
        hostname: 'yourdomain.com'
      }
    })
  });
}

// Track backend events
trackServerEvent('your-website-id', 'api_call_completed', {
  endpoint: '/api/users',
  method: 'POST',
  response_time: 145,
  status_code: 201
});

trackServerEvent('your-website-id', 'cron_job_executed', {
  job_name: 'daily_report',
  duration: 45,
  records_processed: 1000,
  success: true
});

Event Properties

Add custom properties for richer analytics:

umami.track('subscription_upgraded', {
  // User context
  from_plan: 'starter',
  to_plan: 'business',

  // Transaction details
  billing_cycle: 'annual',
  discount_code: 'SAVE20',
  discount_percent: 20,

  // Business metrics
  mrr_before: 49,
  mrr_after: 159,
  mrr_change: 110,

  // Metadata
  upgrade_source: 'feature_limit_notification',
  days_since_signup: 45
});

Event Naming Best Practices

Use Consistent Format

// Good - snake_case, descriptive
umami.track('newsletter_subscribed');
umami.track('checkout_completed');
umami.track('trial_converted');

// Avoid - inconsistent or vague
umami.track('Newsletter');
umami.track('checkout-done');
umami.track('event1');

// Onboarding flow
umami.track('onboarding_started');
umami.track('onboarding_profile_completed');
umami.track('onboarding_preferences_set');
umami.track('onboarding_completed');

// Account lifecycle
umami.track('account_created');
umami.track('account_verified');
umami.track('account_upgraded');
umami.track('account_downgraded');
umami.track('account_cancelled');

Funnel Tracking

Track multi-step conversion funnels:

// Step 1: Awareness
umami.track('pricing_page_visited', {
  source: 'homepage'
});

// Step 2: Interest
umami.track('plan_compared', {
  plans_viewed: ['starter', 'pro', 'business']
});

// Step 3: Consideration
umami.track('signup_started', {
  selected_plan: 'pro'
});

// Step 4: Conversion
umami.track('signup_completed', {
  plan: 'pro',
  payment_method: 'card'
});

// Step 5: Activation
umami.track('first_action_completed', {
  action: 'project_created',
  time_to_action: 120 // seconds since signup
});

// Analyze drop-off in Umami dashboard

Goals and Conversions

Define and track conversion goals:

// Set up goals in Umami dashboard, then track:

// Goal: Email signups
umami.track('goal_email_signup', {
  source: 'blog_footer',
  list: 'weekly_newsletter'
});

// Goal: Trial conversions
umami.track('goal_trial_conversion', {
  plan: 'professional',
  trial_length: 14,
  conversion_day: 12
});

// Goal: Feature adoption
umami.track('goal_feature_adoption', {
  feature: 'advanced_analytics',
  days_since_signup: 7
});

Event Validation and Testing

Verify events are tracking correctly:

// Check if umami is loaded
if (typeof umami !== 'undefined' && umami.track) {
  umami.track('test_event', {
    test: true,
    timestamp: new Date().toISOString()
  });
  console.log('Umami event tracked successfully');
} else {
  console.error('Umami not loaded');
}

// Check browser network tab for requests to /api/send
// Events appear in Umami dashboard in real-time

Privacy Considerations

Umami events are privacy-focused by default:

Safe to Track:

umami.track('purchase', {
  product_category: 'electronics',
  price_range: '100-200',
  payment_method: 'card',
  region: 'North America'
});

Avoid PII:

// Don't include personal information
umami.track('purchase', {
  user_email: 'user@example.com', // Don't do this
  customer_name: 'John Doe', // Don't do this
  ip_address: '192.168.1.1', // Don't do this
  credit_card: '****1234' // Don't do this
});

Framework Integration

React

import { useEffect } from 'react';

function SignupButton() {
  const handleSignup = () => {
    umami.track('signup_button_clicked', {
      location: 'header'
    });
  };

  return (
    <button
      Sign Up
    </button>
  );
}

Next.js

// pages/_app.js
import Script from 'next/script';

export default function App({ Component, pageProps }) {
  return (
    <>
      <Script
        src="https://your-umami.com/script.js"
        data-website-id="your-website-id"
        strategy="afterInteractive"
      />
      <Component {...pageProps} />
    </>
  );
}

// Track in components
umami.track('page_action', { action: 'button_click' });

Viewing Event Data

Access event data in Umami:

  • Events Tab: View all tracked events
  • Real-Time Dashboard: See events as they happen
  • Event Breakdown: Analyze event counts over time
  • Property Filtering: Segment by event properties
  • Goal Tracking: Monitor conversion goals
  • CSV Export: Download event data
  • API Access: Query events programmatically
Nach oben