Custom Events

Custom Events allow you to track meaningful user actions in your product and use them to target your onboarding content.

What are Custom Events?

Custom Events track specific user actions in your product. You can use them to:

• Track feature adoption (e.g., "User created first project")
• Monitor conversion actions (e.g., "User completed purchase")
• Measure engagement (e.g., "User exported report")

Setting up Custom Events

There are three ways to track custom events:

1. SDK Tracking (Code)

Track events programmatically using the Hopscotch SDK:

window.Hopscotch("track", "Feature Activated", {
  value: 100,
  category: "onboarding"
})

Auto-registration: When you track an event via the SDK that doesn't already exist, Hopscotch automatically creates it for you. The new event will appear in your Events dashboard. This makes it easy to start tracking without pre-registering events, but be mindful of typos as they'll create duplicate events.

See the Browser SDK documentation for full details.

2. Click Tracking (No-Code)

Track when users click specific elements:

1. Go to Events in your Hopscotch dashboard
2. Click New Event
3. Select Click as the trigger type
4. Enter a CSS selector for the element (e.g., #upgrade-button, .submit-btn)
5. Optionally add a page URL filter to only track clicks on specific pages

Tips for CSS selectors:

• Use IDs when possible (#my-button) for reliability
• Class selectors work too (.action-button)
• You can use attribute selectors ([data-action="submit"])

3. Page Visit Tracking (No-Code)

Track when users visit specific pages:

1. Go to Events in your Hopscotch dashboard
2. Click New Event
3. Select Page Visit as the trigger type
4. Enter a URL pattern (supports * wildcards)

URL pattern examples:

• https://app.example.com/dashboard - Exact match
• https://app.example.com/projects/* - Any project page
• */settings/* - Any settings page on any domain

Best Practices

Event Naming Conventions

Use clear, descriptive names for your events:

• Good: "First Project Created", "Upgrade Completed", "Report Exported"
• Avoid: "click1", "event_a", "test"

What to Track

Focus on meaningful actions that indicate user success:

• Activation events: First time using a key feature
• Conversion events: Completing a purchase or upgrade
• Engagement events: Using advanced features
• Retention signals: Returning to the product

Using Events for Targeting

Custom events can also be used to target your onboarding content. For example:

• Show a tour to users who haven't completed a specific event
• Target power users who have completed an event 10+ times
• Re-engage users who haven't triggered an event in 30 days

Individual Event Targeting

Use the Custom Event filter to target based on the current user's events:

Company-Level Event Targeting

If you've set up company identification, you can target based on events from any user in the same company using the Company Event filter.

This is powerful for multi-user products where you want to:

• Skip onboarding if a teammate has already completed setup
• Show upgrade prompts only to companies where no one has used a premium feature
• Target expansion content to companies that have adopted one feature but not another

Example use cases:

1. New team member onboarding: Show a "Getting Started" tour to users whose company has already set up the product (someone else completed "Setup Completed" event), but the current user hasn't seen the "Dashboard Tour".

2. Feature discovery: Show a tooltip about a premium feature to users at companies where no one has used it yet ("Premium Feature Used" has not occurred for company).

3. Expansion targeting: Target users at companies that have adopted Feature A but not Feature B to encourage broader adoption.

See How to Identify Users for setup instructions.