Track Events

UserPath automatically tracks many user interactions and also gives you full control over custom event tracking. Learn how to capture the events that matter most to your business.

Configuration

UserPath automatically tracks many user interactions. You can customize which events are tracked as follows:

Automatic Event Tracking

UserPath automatically captures comprehensive user interaction data when auto-tracking is enabled. Below is a complete reference of all automatically tracked events and their properties.

Click Events

Event Name: click
Triggered: When users click on interactive elements (buttons, links, etc.)
Properties:

• label - Extracted text or meaningful identifier from the clicked element
• element - HTML tag name (e.g., "button", "a", "input")
• id - Element ID if available

Scroll Events

Event Name: scroll
Triggered: When scroll depth exceeds 50% of page height (once per page)
Properties: None (basic scroll milestone tracking)

Form Interaction Events

UserPath tracks comprehensive form interactions to understand user engagement with your forms.

Event Names:

• input_fill - User fills out text inputs or textareas
• input_select - User selects from dropdown menus
• input_radio - User selects radio button options
• input_checkbox - User checks/unchecks checkboxes
• input_range - User adjusts range sliders
• form_submit - User submits forms

Video Events

Event Names:

• video_play - Video starts playing
• video_pause - Video is paused
• video_complete - Video playback completes

Properties: Comprehensive video metadata including:

• duration - Total video duration in seconds
• current_time - Current playback position in seconds
• src - Video source URL
• title - Video title attribute
• video_id - Video ID attribute
• watch_time - Time spent watching (pause/complete events only)
• aria_label - Accessibility label
• video_platform - Detected platform (youtube, vimeo, wistia)
• video_domain - Domain hosting the video
• nearby_text - Descriptive text near the video element
• Plus any data-* attributes on the video element

Page Visibility & Time Tracking Events

Event Names:

• page_visibility - Page visibility changes (tab switch, minimize)
• page_exit - User leaves the page

Properties:

• visible - Current visibility state (visibility events only)
• total_time - Total time on page in seconds
• visible_time - Time page was actually visible in seconds

User Activity & Inactivity Events

Event Names:

• user_inactive - User becomes inactive (60+ seconds without interaction)
• user_active - User becomes active again after inactivity

Properties:

• inactive_duration - How long user was inactive in seconds (active events only)
• url - Current page URL (active events only)
• title - Current page title (active events only)

Error Events

Event Name: error
Triggered: JavaScript errors and unhandled promise rejections
Properties:

• message - Error message
• stack - Error stack trace
• source - Error source ("client", "window.onerror", "unhandledrejection")
• filename - File where error occurred
• lineno - Line number of error
• colno - Column number of error

Performance Events

Event Names:

• page_load - Page load performance metrics
• core_web_vitals - Core Web Vitals measurements (LCP, FID, CLS)

Page Load Properties:

• page_load_time - Total page load time in milliseconds
• dom_content_loaded_time - DOMContentLoaded time in milliseconds
• time_to_first_byte - TTFB in milliseconds
• dom_interactive_time - DOM interactive time in milliseconds
• connect_time - Connection time in milliseconds
• dns_lookup_time - DNS lookup time in milliseconds
• navigation_type - Navigation type (0=navigate, 1=reload, 2=back/forward)
• redirect_count - Number of redirects

Core Web Vitals Properties:

• metric - Metric type ("LCP", "FID", or "CLS")
• value - Metric value (milliseconds for LCP/FID, score for CLS)
• rating - Performance rating ("good", "needs-improvement", "poor")

Custom Event Tracking

While UserPath automatically captures comprehensive user interactions, custom events let you track business-specific actions that matter most to your success. Custom events provide the flexibility to measure exactly what drives your business forward.

Benefits of Custom Events

Business-Specific Insights: Track actions that align with your unique business model - from feature usage to conversion milestones.

Enhanced Attribution: Connect user actions to business outcomes with precise event timing and context.

Flexible Property Structure: Include any data that helps you understand user behavior - user IDs, product information, pricing details, and others.

Cross-Platform Consistency: Track the same events across web, mobile, and server-side for unified analytics.

Goal & Funnel Optimization: Combine native events with custom events to create multi-step goals and funnels to optimize user journeys.

Browser-Side Custom Events

Track custom events directly from your website using either the browser pixel or SDK.

Server-Side Custom Events

Track custom events from your backend for maximum accuracy and to capture server-only data. Server-side tracking is essential for business-critical events like purchases, user registrations, and API interactions.

Common Custom Event Patterns

Here are proven patterns for tracking business-critical events:

Server Events Best Practices

• Always wrap your track calls in a try/catch block to handle errors

• Wrap your calls with an IIFE to ensure the call is non-blocking

Server-Side Event Tracking

Track events from your backend for maximum accuracy:

UserPath will automatically set a _up.sid cookie in the user's browser.

Extract the _up.sid cookie value from the user's request and pass it to your track calls. This ensures:

• Event Deduplication: Prevents duplicate events when users trigger the same action from both client and server
• Session Continuity: Links server-side events to the user's browser session
• Cross-Device Tracking: Enables tracking users across multiple devices and sessions
• Accurate Attribution: Ensures conversion events are properly attributed to the correct user journey

Without the sid parameter, server-side events will be treated as separate sessions, leading to inflated metrics and broken user journeys.

HTTP API

Track events directly via HTTP requests for language agnostic integration.

Session ID Format

UserPath session IDs must follow the UUID v4 format for proper tracking and validation. The _up.sid cookie value must be valid UUID v4 strings.

Key Requirements:

• Format: 32 hexadecimal characters separated by hyphens in the pattern 8-4-4-4-12
• Length: Exactly 36 characters including hyphens
• Case: Lowercase letters (a-f) and numbers (0-9) only
• Separators: Must use hyphens (-) not underscores or other characters

Valid Session ID Format

Session IDs must be properly formatted UUIDs.

✅ Valid format: d34d0c34-4d8b-4a88-a9a6-331cdb7b9d73

❌ Invalid formats:

• abc123
• session_12345
• d34d0c34-4d8b-4a88-a9a6 (incomplete)
• d34d0c34_4d8b_4a88_a9a6_331cdb7b9d73 (wrong separators)

If you provide an invalid session ID format, the API will return an error with status code 400 and the following response:

Examples in Different Languages

See how to generate valid session IDs in different programming languages below:

Best Practices

Ensure your events are properly structured:

• Event names should be descriptive and consistent (use snake_case)
• Property values should be meaningful
• Keep property count reasonable (under 10 properties per event)
• Use consistent data types for the same property across events
• Ask our AI for help with event naming and property values