Events & Identification

The tracker auto-captures page views, clicks, scroll depth, errors, and more. Use track() for business-specific actions and identify() to link sessions to users.

Custom Events

usersesh.track(eventName: string, properties?: object)

Track business-specific actions with custom properties. The auto-tracker already captures generic clicks, so only use track() when you need specific properties attached to an event.

Examples by app type

SaaS

usersesh.track("signed_up", { method: "google" });
usersesh.track("onboarding_step", { step: 2, step_name: "connect_data" });
usersesh.track("onboarding_completed", { steps_completed: 4 });
usersesh.track("subscription_started", { plan: "pro", amount: 29, interval: "monthly" });
usersesh.track("plan_upgraded", { from: "free", to: "pro" });
usersesh.track("feature_used", { feature: "ai_insights" });
usersesh.track("invite_sent", { role: "editor" });
usersesh.track("limit_reached", { limit: "api_calls" });
usersesh.track("feedback_submitted", { type: "feature_request" });

E-commerce

usersesh.track("product_viewed", { product_id: "sku_123", price: 29.99, category: "shoes" });
usersesh.track("added_to_cart", { product_id: "sku_123", quantity: 1, price: 29.99 });
usersesh.track("checkout_started", { cart_value: 89.97, item_count: 3 });
usersesh.track("purchase_completed", { order_id: "ord_456", total: 89.97, payment_method: "stripe" });
usersesh.track("coupon_applied", { code: "SAVE20", discount: 17.99 });
usersesh.track("search_performed", { query: "running shoes", results_count: 24 });

Landing Pages

usersesh.track("cta_clicked", { name: "hero-signup", text: "Get Started Free", location: "hero" });
usersesh.track("cta_clicked", { name: "pricing-pro", text: "Choose Pro", location: "pricing" });
usersesh.track("section_viewed", { section: "pricing" });
usersesh.track("section_viewed", { section: "testimonials" });
usersesh.track("pricing_toggle", { interval: "yearly" });
usersesh.track("faq_expanded", { question: "How does billing work?" });
usersesh.track("form_submitted", { form: "signup", source: "hero" });

Best practices

  • Use snake_case for event names
  • Focus on the 10-15 most important actions, not every button click
  • Don't track generic clicks — the auto-tracker handles those
  • Include properties that help you segment (plan, source, category)

Data Attributes

The auto-tracker captures every click. To make click events more meaningful in the dashboard, add data-track attributes to key elements:

<button data-track="hero-signup">Get Started Free</button>
<a href="/pricing" data-track="nav-pricing">Pricing</a>
<button data-track="add-to-cart">Add to Cart</button>

The tracker also reads these attributes when present:

  • data-track — Primary tracking name, shows as elementTrackId in the dashboard
  • data-analytics — Alternative to data-track
  • data-testid — Also captured if present (useful if you already have these for testing)

User Identification

Identifying users

Call identify() after login or signup to link the anonymous session to a known user:

usersesh.identify("user_123", {
  email: "jane@example.com",
  name: "Jane Doe",
  plan: "pro",
  company: "Acme Inc"
});

The user ID should be a stable identifier from your system (database ID, auth provider ID, etc.). Traits are optional but help you filter and segment in the dashboard.

Updating user properties

Use people.set() to update properties without re-identifying:

// User upgrades their plan
usersesh.people.set({ plan: "enterprise", seats: 10 });

Resetting identity

Call reset() when the user logs out to clear the identity and start a fresh anonymous session:

// On logout
usersesh.reset();

Where to Add Calls

The usersesh object is available globally on window after the tracker loads. In frameworks with TypeScript, you may want to add a type declaration:

// globals.d.ts or types.d.ts
declare global {
  interface Window {
    usersesh?: {
      track: (event: string, properties?: Record<string, unknown>) => void;
      conversion: (options: {
        event: string;
        revenue?: number;
        currency?: string;
        metadata?: Record<string, unknown>;
      }) => void;
      identify: (userId: string, traits?: Record<string, unknown>) => void;
      people: { set: (properties: Record<string, unknown>) => void };
      reset: () => void;
      getVisitorId: () => string;
      getUserId: () => string | null;
      setRecordingEnabled: (enabled: boolean) => void;
      isIdle: () => boolean;
    };
  }
}

Use optional chaining (window.usersesh?.track()) to safely call methods before the script has loaded.

Next steps