Event Tracking
Track custom events to measure user interactions beyond page views.
Related Documentation
Looking for framework integration examples? Check out our JavaScript SDK guide for React, Vue, and Next.js examples, or our Platform Integrations for WordPress, Shopify, and more.
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.
// Track a simple event
window.invoker?.trackEvent('button_click')// 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 withdata-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
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:
- Navigate to your site dashboard
- Click "Events" in the sidebar
- 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_clickorform_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