Step by step process for configuring Heap to track feature adoption

So, you want to see if people are actually using that shiny new feature your team shipped. Good call. Tracking feature adoption isn't just for showing off in slide decks—it’s how you know if your product is working for real users. But setting up analytics can get messy fast. This guide walks you through exactly how to configure Heap to track feature adoption, without drowning in dashboards or buzzwords.

If you're a product manager, growth lead, or developer trying to get real answers about what users actually do (not just what they say), this is for you. Let’s get into it.


Before You Start: What You Actually Need to Track

Heap is powerful, but power can be dangerous if you overcomplicate things. Before you touch any settings, answer these three questions:

  • What’s the feature? Be brutally specific. (“Onboarding flow” is vague. “Upload a CSV on the import page” is better.)
  • What counts as adoption? Is it clicking a button? Completing a flow? Don’t obsess—pick something concrete.
  • Who are you measuring? All users? Only those in a certain plan? Filter out test accounts or internal folks.

Pro tip: Write these down. You’ll forget, and so will everyone else.


Step 1: Make Sure Heap Is Actually Installed (Don’t Skip This)

This sounds obvious, but you'd be surprised how often analytics tags get left out or break.

  1. Check your Heap snippet.
  2. Go to your site’s codebase and make sure the Heap JavaScript snippet is present, or that the Heap SDK is initialized in your app.
  3. Open your site in Chrome, hit F12, and check the Network tab for requests to Heap. If you see them, you're good.
  4. No snippet? Follow Heap’s official installation docs and get it in there.

  5. Double-check environments.

  6. Is Heap running in staging, production, both?
  7. Make sure you’re not tracking dev traffic as real users, or you’ll get garbage data.

What to ignore: Don’t bother with “advanced” install options unless you have a weird setup. The default install works for 99% of web apps.


Step 2: Map Out the Feature Journey

Don’t just tag a button and call it a day. To really track adoption, you need to know what “adoption” looks like for your feature.

  1. List the key actions.
  2. Example: For a “Download Report” feature, is it clicking the “Download” button? Actually getting the file?
  3. Be honest: What’s the minimum user action that counts as adoption?

  4. Identify the UI elements.

  5. Get the CSS selectors, text labels, or unique attributes for the relevant buttons/links/fields.
  6. If your UI changes often, try to use selectors that don’t break every sprint.

Pro tip: Take screenshots or notes as you go. You’ll thank yourself when you’re knee-deep in event setup.


Step 3: Create Events in Heap

Heap shines because you can define events retroactively (no code deploys needed). But it’s easy to get lost in the weeds.

  1. Go to the "Define" section.
  2. In Heap’s dashboard, click “Define” > “New Event”.

  3. Set up the adoption event.

  4. Use the visual event picker or manually enter a selector.
  5. Name the event something obvious: Clicked Download Report Button, not event_237.

  6. Add filters if needed.

  7. Want to track only paid users? Add a user property filter.
  8. Exclude internal traffic by filtering out emails/domains like @yourcompany.com.

  9. Save and test.

  10. Use Heap’s live view to perform the action and see if Heap grabs the event.
  11. If not, check your selector or ask a front-end dev for help.

What works: Heap’s visual picker is usually reliable, but always double-check. UI changes can silently break your events.

What doesn’t: Don’t define 10 different events for a single feature unless you have a real reason. You’ll create chaos.


Step 4: Set Up Properties and User Segments

Raw events are helpful, but to really see adoption patterns, you’ll want to slice the data.

  1. Add event properties.
  2. Capture extra details: Which plan was active? What was the feature setting chosen?
  3. Heap lets you add properties via selectors (for example, the value of a dropdown when a button is clicked).

  4. Define user segments.

  5. In Heap, segments = groups of users (e.g., “New Users”, “Power Users”, “Enterprise Plan”).
  6. Set these up so you can answer questions like “Do paid users adopt this feature faster?”

Pro tip: Don’t make segments for every random thing. Stick to 3-5 that actually matter to your team.


Step 5: Build an Adoption Funnel

Now for the fun part: seeing who actually uses your feature.

  1. Go to "Analyze" > "Funnels".
  2. Create a new funnel.
  3. Step 1: Some entry action (e.g., “Logged in” or “Visited Dashboard”).
  4. Step 2: Your adoption event (e.g., “Clicked Download Report Button”).

  5. Configure funnel settings.

  6. Set a reasonable window (e.g., 7 days between steps).
  7. Apply segments if you want to compare groups.

  8. Check the results.

  9. What’s the dropoff? Are new users getting stuck?
  10. Play with time ranges to spot trends after feature launches.

What works: Keep funnels simple. You only need 2-3 steps to learn a lot.

What doesn’t: Don’t obsess over “perfect” funnels. You’re after useful signals, not pixel-perfect reports.


Step 6: Set Up Dashboards and Alerts

Analytics don’t mean much if nobody sees them. Heap dashboards get stats in front of your team.

  1. Build a simple dashboard.
  2. Add your adoption funnel, total adoption count, and maybe a time trend.
  3. Avoid dumping every chart you can think of. Less is more.

  4. Share it with the team.

  5. Make it visible to product and engineering. Nobody likes analytics hidden in a silo.
  6. If your execs want a weekly update, set up an email report.

  7. Set alerts (optional).

  8. Heap can alert you if adoption drops suddenly. Don’t set these too tight or you’ll just get noise.

What works: Simple, focused dashboards. If people aren’t looking at it, it’s probably too complicated.

What doesn’t: Dashboards for vanity metrics. Track what you’ll actually act on.


Step 7: Review, Rethink, and Iterate

A week after you launch tracking, go check the data. Odds are, you’ll spot something weird—a spike from internal traffic, a missing event, or a funnel that looks off.

  • Fix what’s broken. Don’t assume your initial setup is perfect.
  • Update events when the UI changes. If your front end team moves a button, update the event definitions.
  • Clean up unused events. Heap can turn into a junk drawer if you’re not careful.

Pro tip: Schedule a quick analytics health check every month. It takes 10 minutes, saves you hours of cleanup later.


Common Pitfalls (And How to Dodge Them)

  • Tracking too much. You don’t need to log every click. Focus on actions tied to real user value.
  • Letting definitions drift. Features and UIs change. If you don’t update events, your data gets stale.
  • Ignoring internal traffic. Filter yourself and your team out or you’ll end up measuring your own dogfooding.
  • Chasing “perfect” data. Done is better than perfect. You can always refine later.

Wrapping Up: Keep It Simple, Fix as You Go

Heap is a solid tool for tracking feature adoption, as long as you keep your setup simple and focused. Don’t get sucked into overengineering your analytics or chasing unicorn metrics. Start with the basics, make sure you’re measuring what matters, and check your data regularly. If you’re not learning anything new from your dashboards, something’s probably off.

You’ll get the most value by iterating—set it up, see what you find, tweak as needed. That’s how you actually get answers, not just more charts.