Skip to content
Features

Event Tracking

Track custom events to measure user interactions beyond page views.

What are Events?

Events allow you to track specific user interactions on your website that aren't captured by default pageview tracking. Common use cases include:

  • Button clicks (CTA buttons, download links)
  • Form submissions
  • Video plays
  • File downloads
  • External link clicks
  • Newsletter signups

Tracking Events

Use window.invoker?.trackEvent(name, payload?) to track events. The script loads with defer, so call it from user interactions or after page load, and use optional chaining (window.invoker?.trackEvent(...)) so nothing breaks if the script is blocked.

Basic Event
Track a simple user interaction
// Track a simple event
window.invoker?.trackEvent('button_click')
Event with Properties
Add custom properties for deeper insights
// Track an event with custom properties
window.invoker?.trackEvent('signup', {
  plan: 'Pro',
  source: 'pricing_page',
  value: 99
})

Automatic Events

The tracking script records three events without any code. Each can be turned off with a script attribute (see Tracking Script):

  • outbound_link — clicks on links to another hostname (data-outbound-links="false" to disable)
  • file_download — clicks on links to common file types such as PDF, ZIP or DMG (data-file-downloads="false"; customise with data-download-extensions)
  • 404_error — pages whose title contains "404" or "not found", or that include <meta name="invoker-status" content="404"> (data-404-errors="false")

Examples

<button onclick="window.invoker?.trackEvent('cta_click', {button: 'signup'})">
  Sign Up Now
</button>

// Or with JavaScript
document.getElementById('cta-btn').addEventListener('click', () => {
  window.invoker?.trackEvent('cta_click', {
    button_name: 'signup',
    page_section: 'hero'
  })
})

Event Properties

Properties allow you to add additional context to your events. Some guidelines:

  • Pass a flat object; property values should be strings or numbers
  • Keep property names short and descriptive
  • Use consistent naming conventions across events
  • Avoid storing personally identifiable information (PII)

Viewing Event Data

Event data is available in the Events section of your dashboard:

  1. Navigate to your site dashboard
  2. Click "Events" in the sidebar
  3. See total events, unique event types, and each event's count and unique visitors

Outbound links, file downloads and 404s have their own pages in the sidebar. To build a funnel from events, use the Funnel tab under Charts. Event properties are stored with each event and included in event exports and the API.

Limits

Custom and automatic events count toward your plan's monthly event allowance (shown on the Usage page). Events over the allowance aren't recorded until usage resets or you upgrade. Goals don't count toward it.

React Integration

// Create a tracking hook
function useTrackEvent() {
  const trackEvent = (name: string, props?: Record<string, string | number>) => {
    window.invoker?.trackEvent?.(name, props)
  }
  return trackEvent
}

// Use in components
function SignupButton() {
  const trackEvent = useTrackEvent()

  const handleClick = () => {
    trackEvent('signup_click', { location: 'header' })
    // ... handle signup
  }

  return <button onClick={handleClick}>Sign Up</button>
}

Best Practices

  • Name events clearly: Use short, action-oriented snake_case names like button_click or form_submit
  • Be consistent: Use the same event names for similar actions across your site
  • Don't over-track: Focus on meaningful interactions, not every click
  • Use properties wisely: Add context that helps you analyze the data
  • Test your events: Check the dashboard to verify events are being tracked correctly