How to track product events

Overview

Product events are the actions users take inside your application that you want to measure and analyze. This guide covers how to use the Userorbit SDK to track these events effectively.

Using userorbit.track()

The track() method is the primary way to record events. It accepts an event name and an optional properties object:

userorbit.track('feature_activated', { featureName: 'dark_mode', source: 'settings' });

Call track() at the point in your code where the action completes successfully. For example, track a form submission after the server confirms it was saved, not when the user clicks the submit button.

Event naming best practices

Good event names are the foundation of useful analytics. Follow these patterns:

Object + action format — Pair a noun with a past-tense verb: project_created, invoice_paid, report_exported.
Keep names stable — Once you ship an event name, avoid changing it. Renaming events breaks historical comparisons.
Avoid dynamic values in names — Do not use plan_upgraded_to_pro. Instead, use plan_upgraded with a property { newPlan: 'pro' }.
Limit your event vocabulary — A focused set of 20-50 well-chosen events is more useful than hundreds of loosely defined ones.

Attaching properties

Properties transform raw event counts into rich analytical data. Every event should carry enough properties to answer follow-up questions.

Example — tracking a search:

userorbit.track('search_performed', { query: 'dashboard templates', resultsCount: 8, filterApplied: true, category: 'templates' });

Guidelines for properties:

Use camelCase for property keys.
Keep values flat — strings, numbers, and booleans only. Avoid nested objects or arrays.
Be consistent — If one event uses planName, do not use plan_name in another.
Include useful context — The page, component, or feature area where the event occurred is almost always worth including.

Tracking at the right moment

Timing matters for accurate analytics:

Success events — Track after the action succeeds. For API calls, track in the success callback, not before the request.
Page views — Track when the page fully loads or when the route changes in a single-page application.
Error events — Track in error handlers to capture failures. Include the error type and context as properties.

Debugging events

When events are not showing up or have incorrect data, use these techniques:

Live Events view — Open it in Userorbit and trigger the action. Events should appear within seconds.
Browser console — Add a console.log before your track() call to confirm the code path executes.
Network inspector — Check the browser's Network tab for outgoing requests to the Userorbit API. Look at the request payload to verify event names and properties.
Property validation — Click on an event in the Live Events view to inspect its properties. Verify types and values match your expectations.

Common mistakes

Tracking before identify — If you track events before calling identify(), they will not be linked to a user profile. Always identify the user first.
Duplicate tracking — Make sure your track() call is not inside a loop or a component that re-renders frequently.
Missing error handling — If the action can fail, make sure you only track successful completions unless you intentionally want to track failures too.

Help Center