Skip to content

How to Track UTM Parameters in Heap Analytics

Heap Analytics is built around events, which makes it strong at showing how people use a product. What it does not do out of the box is capture UTM parameters, so you cannot easily segment users by the campaign or channel that brought them in. This guide walks through a four-step setup for getting UTM parameters and related attribution data into Heap, then using that data to answer acquisition questions.

Why UTM data matters in Heap

Without campaign data, Heap reports can tell you what users did but not where they came from. Adding UTM parameters and attribution fields lets you connect behaviour to acquisition source. Once the data is in Heap, you can build reports that answer questions such as: how many signups came from LinkedIn ads; what the signup-to-customer conversion rate is for Google Ads traffic; how many customers a Facebook ad generated; and how retention compares between Google Ads and Facebook Ads visitors. The same data supports many other channel and campaign comparisons.

What the attribution script does

The setup described here relies on Attribution Analytics, a small script added to your website. The script watches how visitors arrive, assigns each one to a channel such as Organic Social, Organic Search or Paid Search, and stores that organised data in a cookie in the visitor's browser. When a visitor submits a form, the script passes the UTM parameters and other attribution information into Heap Analytics for reporting. The capabilities described on this page are the intended configuration for Attribution Analytics; confirm that your installed product provides them before you rely on them.

Four steps to get UTM parameters into Heap

The process has four stages: tag your ads, install the script, pass the data into Heap, and build reports. Each stage is described below.

Step 1: Add UTM parameters to every ad and campaign

Start by tagging every ad and campaign with UTM parameters. This is what allows the attribution script to understand where traffic comes from. Places to apply UTM tags include search engine ads on Bing and Google, social ads on LinkedIn, Twitter and Facebook, and bespoke campaigns in trade publications, email newsletters and similar outlets.

Step 2: Install the attribution script on your site

Installation begins with the code snippet supplied through the signup process at the account registration page. Treat it like any other marketing or analytics tag: place it on every page where visitor arrival and form activity need to be observed. Content management systems such as WordPress and Wix commonly include a settings field for custom header or footer scripts, and a tag management service such as Google Tag Manager can also deploy the snippet. If the placement is unclear, consult the vendor's installation documentation. Before relying on the setup, verify that the snippet loads on the pages you expect and that the account provides the code delivery described here.

Step 3: Pass the attribution data into Heap Analytics

With the script running, it monitors how visitors reach your site and stores the information in a cookie. You then need to send that information to Heap. There are two methods:

  • Hidden fields in forms. Add a series of hidden fields to your signup form. The script writes the UTM parameters and other attribution information into those fields. When the form is submitted, the hidden-field data is sent into Heap, for example as User Properties, alongside the name, email, company name and other details the visitor entered.
  • Read the cookie directly. Add a short line of JavaScript to your site to retrieve the UTM parameters and attribution information from the cookie and pass it into Heap as User Properties. This method is especially useful when visitors sign up with Google or Facebook buttons and never fill in a form.

Step 4: Build reports in Heap Analytics

Once the attribution data is in Heap, you can run reports and build dashboards that show key customer acquisition metrics such as signups, activations and customers, broken down by marketing channel and campaign. Typical questions these reports can answer include: how many signups came from Google Ads; which Twitter Ad campaigns drove the most signups; how many activated users came from Facebook Ads; what the retention rate is for LinkedIn ad visitors; how many customers came from blogging; and how many customers came from SEO efforts. Many other breakdowns are possible.

Why this approach beats capturing raw UTM parameters alone

Several methods can get UTM parameters into Heap. The approach described here adds four capabilities beyond simply recording raw UTM strings.

It captures all traffic, not only tagged campaigns

In addition to UTM parameters, the script can collect channel information for visitors who arrive through channels where UTM parameters are absent, such as Organic Search, Paid Search, Direct and Referral. That means you can see where every visitor came from, rather than only those who arrived through a tagged campaign.

It remembers the data across pages

Many UTM capture methods require the UTM parameters to be present in the URL of the page where the form is completed. That fails when the signup page is not the page the visitor first landed on. Take a visitor who arrives from a paid search result on a comparison page, then moves to a pricing page and finally to a standalone checkout screen. A URL-only method sees no UTM parameters on the checkout screen, because the tagged URL was left behind several steps earlier. With cookie-based storage, the parameters stay available in the visitor's browser and are passed into Heap no matter which page the registration happens on.

It produces cleaner channel data

UTM data can become messy, particularly when ads have been managed by different people or agencies over time. For example, some Google Ad campaigns might be tagged with UTM_Source=Google and others with UTM_Source=adwords. A tool that simply passes raw UTM parameters into Heap would show these as two separate signup sources, and you would have to stitch them together manually. The script described here is designed to account for this kind of inconsistency and still assigns those signups to the correct channel, Paid Search, regardless of the inconsistent UTM usage.

It captures landing page data as well

Many digital product companies invest in blogging and content marketing to grow user acquisition, but measuring whether those efforts drive signups and customers is harder. The script also collects the landing page (for example, https://roipaths.com/blog/capture-utm-parameters) and its category (for example, /blog). With landing page data in Heap, you can see how different sections of your website perform in terms of signups and customers, and you can examine how individual blog posts perform from an acquisition perspective.

Choosing between hidden fields and cookie retrieval

Use this checklist to decide which Heap data-passing method fits your signup flow:

  • If your signup form is a standard HTML form and you can edit its fields, hidden fields are usually the simplest route. The script writes attribution values into the fields, and Heap receives them with the rest of the form submission.
  • If visitors can sign up with Google or Facebook buttons and never complete a form, use the cookie retrieval method. A short JavaScript snippet reads the attribution data from the cookie and sends it to Heap as User Properties.
  • If you use both standard forms and social signup buttons, you may need both methods so that no signup path loses its attribution data.
  • In either case, confirm that the values arrive in Heap as User Properties so they can be used as report breakdowns.

Getting started

A complete attribution setup does more than record UTM strings. It should account for visitors from untagged channels, keep source information available after the visitor moves between pages, reconcile inconsistent UTM naming, and record the landing page that started the visit. Those four capabilities make Heap reports more useful for comparing signups and customers across marketing efforts. Before adopting a tool for this purpose, check its current trial terms, signup process and documentation directly, since commercial details can change.

Frequently asked questions

Does Heap Analytics capture UTM parameters automatically?

No. Out of the box, Heap does not capture UTM parameters. You need to add a capture method, such as a script that stores attribution data in a cookie and passes it into Heap through hidden form fields or a JavaScript call.

What is the difference between hidden fields and reading the cookie?

Hidden fields work when a visitor submits a standard form: the attribution values are written into the form and sent to Heap with the submission. Reading the cookie works without a form submission, which makes it suitable for social signup buttons. The cookie method requires a short JavaScript snippet on your site.

Why do UTM parameters get lost when the signup page is different from the landing page?

Methods that read UTM parameters only from the current page URL lose the data once the visitor navigates away from the original landing page. Storing the parameters in a cookie keeps them available for later pages, including the signup page.

Can I report on channels that do not use UTM parameters?

Yes, if your capture method also records channel information for untagged traffic such as Organic Search, Paid Search, Direct and Referral. That lets you report on all visitors, not only those from tagged campaigns.