How to set up user event tracking in Heap for SaaS onboarding

Getting a new user to sign up is great. Getting them actually using (and sticking with) your SaaS app is a whole different beast. If you want to know where new users drop off, what onboarding steps actually get completed, and which parts of your flow are just confusing people, you need solid event tracking from the start. This guide is for hands-on SaaS folks who want to wrangle Heap to track real onboarding progress—without drowning in dashboards or buzzwords.

Let’s break down exactly how to set up user event tracking for onboarding, what’s worth measuring, and what’s just noise.

1. Get Heap Set Up on Your App

Before you can track anything, Heap needs to be collecting data on your site or app. Heap’s promise is “autocapture”—it grabs a lot out of the box. That’s both good and bad: you’ll get plenty of data, but you’ll need to teach Heap what’s actually important.

Step-by-step:

  • Sign up and create a project. If you haven’t already, make a Heap account and set up your project for your SaaS app.
  • Install the Heap snippet. Heap gives you a JavaScript snippet to add to your app (usually in the <head> tag). If you’re using a SPA (React, Vue, Angular, etc.), use their instructions for single-page apps. It’s just copy-paste, but double-check it’s loading on every page.
  • Verify data is coming in. Log in to Heap, pull up the Live data feed, and make sure it’s seeing pageviews and clicks. If not, fix this before doing anything else.

Pro tip: Don’t trust “it should be working.” Open your app, click around, and watch Heap’s live feed to see your own actions. You’ll save yourself a headache later.

2. Map Out Your Onboarding Flow

Before you track, actually write down (on paper or in a doc) what your onboarding flow is. It seems obvious, but most teams skip this and end up with a mess of “events” that don’t mean anything.

Ask yourself:

  • What do you consider a successful onboarding?
  • What are the key actions a new user needs to take? (E.g., invited teammates, created first project, finished profile, etc.)
  • Where do users typically stall out?

Example onboarding steps:

  • Signed up (created account)
  • Confirmed email
  • Completed onboarding checklist
  • Created first project
  • Invited teammates

You don’t need to track every possible click. Focus on the actions that mean a user is actually adopting your product.

3. Define The Events You Care About

Heap autocaptures a ton of stuff (clicks, page views, form submissions), but it doesn’t know what’s meaningful. You have to define events so you can report on them later.

Three types of events in Heap:

  1. Autocaptured events: Things Heap grabs automatically, like button clicks or pageviews.
  2. Defined events: Your own rules, built from autocaptured data (e.g., “Clicked ‘Create Project’ button”).
  3. Custom tracked events: Events you send manually from your app when autocapture isn’t enough.

How to define the key onboarding events:

  • Go to Heap’s “Events” section.
  • Click “Define Event.”
  • Use Heap’s point-and-click tool to select elements (like “Create Project” button).
  • Name each event clearly, e.g., “Onboarding: Created First Project.”
  • Save and test them—make sure the event fires when you do the action.

When to use custom events:
If something can’t be captured with clicks or page views—think in-app modals, server-side events, or complex flows—use Heap’s heap.track() method to send a custom event.

Sample code for a custom event (e.g., finished onboarding checklist):

javascript heap.track('Onboarding: Completed Checklist');

Drop this in your frontend code when that step finishes.

Keep it simple:
Don’t define 30 onboarding events. Start with 3-5 that actually matter. You can always add more later.

4. Attach User Properties (Identify Your Users)

If you want to know who did what, not just “someone did something,” you need to identify users in Heap. Otherwise, you’ll just see anonymous blobs.

How to do it:

  • Call heap.identify() after a user logs in or signs up, passing a unique user ID (usually your own app’s user ID or email).

javascript heap.identify('user_12345');

  • Attach properties like email, plan type, signup date, etc. using heap.addUserProperties():

javascript heap.addUserProperties({ email: 'user@email.com', plan: 'Pro', signup_date: '2024-06-12' });

Why bother?
This lets you segment onboarding data by user type, cohort, or plan—so you can see, for example, if paid users onboard faster than free ones.

5. Test Your Event Tracking (Don’t Skip This)

This is where most setups go off the rails. You have to test that your events are firing in Heap—and that they mean what you think they mean.

What to do:

  • Go through the onboarding flow yourself in a private/incognito window.
  • Trigger each key event (sign up, create project, etc.).
  • Watch the Heap live feed to see if your defined (and custom) events show up.
  • Check that user properties are attached and that your test user is being identified correctly.

Common gotchas:

  • Events only fire on production, not your dev domain (configure environments in Heap).
  • SPA navigation trips up Heap’s pageview tracking—make sure you’re calling Heap’s track or using their router integrations.
  • Some actions (like confirming email) might happen outside your frontend—send those events from your backend if needed.

6. Build Reports and Funnels That Actually Matter

Tracking events is pointless unless you do something with them. Start simple: build one or two reports or funnels to answer key questions.

For SaaS onboarding, try:

  • Onboarding funnel: See how many users complete each onboarding step (sign up → confirm email → create project → invite teammate).
  • Time to key event: How long does it take a new user to create their first project?
  • Drop-off analysis: Where do most users bail out of onboarding?

Heap’s query builder is drag-and-drop, but don’t get lost in the weeds. Pull up the funnel for your onboarding steps. Play with filtering by user properties (e.g., plan type, signup date).

What not to bother with (yet):

  • Tracking every single button or tooltip. It just fills up your reports with noise.
  • Building dashboards for execs if you don’t even know what matters yet.
  • Fancy attribution models. For onboarding, focus on action, not theory.

7. Keep Your Tracking Organized (Or Future You Will Hate You)

It’s easy to end up with a junk drawer full of random events (“Clicked Something,” “Button 12”), especially if your team grows. Do yourself a favor:

  • Use clear, consistent naming. Prefix onboarding events with “Onboarding:” so you can find them later.
  • Document what each event means in Heap’s description field.
  • Review your events every month or so—delete or merge ones you’re not using.

Pro tip:
If you don’t remember what an event is, nobody else will, either.

No Silver Bullets—Just Start, Learn, and Iterate

Setting up user event tracking in Heap for SaaS onboarding isn’t magic. Heap’s autocapture is handy, but you still need to decide what you care about, define it, and check your work. Don’t let “analysis paralysis” or dashboard FOMO slow you down. Start with the core onboarding steps, make sure the data’s trustworthy, and build from there.

You can always add more events or reporting later. Most teams get more value from fixing obvious onboarding problems than from slicing up the data a million ways.

Keep it simple, check your events, and use Heap to answer real questions—not just to look busy.