How to Install a Heatmap with Google Tag Manager (No Code Edits, 5 Minutes)

TL;DR

With GTM you can install a heatmap without touching your site's code at all

Five steps: create a Custom HTML tag → attach an All Pages trigger → publish

Success means the numbers move on your HeatMapX dashboard — not just "no errors"

If your site already manages tags through Google Tag Manager (GTM), it's the cleanest way to add heatmap tracking: everything happens in the GTM interface, with zero code changes. This guide walks through it step by step.

Before you start: get your site key

Once you have it, you'll use a tag of this form — replace YOUR-SITE-KEY with your actual key:

<script src="https://heatmapx.com/tracker.js?key=YOUR-SITE-KEY" data-site-key="YOUR-SITE-KEY"></script>

Important: paste the entire tag, not just the URL. The data-site-key="..." attribute tells HeatMapX which site the data belongs to — if you drop it, or paste only the src URL, nothing will be tracked.

The GTM setup (5 steps)

Open the GTM console (tagmanager.google.com) and select your site's container (workspace)
Go to "Tags" → "New" in the left menu, and choose "Custom HTML" as the tag type
Paste the entire tag above into the HTML field
Under triggering, choose "All Pages (Page View)", give the tag a recognizable name (e.g. HeatMapX), and save
Hit "Submit / Publish" in the top right to push the change live

That's it — tracking now runs on every page of your site.

Want to check before publishing? (Preview mode)

Click "Preview" in GTM to test the tag in your own browser before going live. Open your site through the preview screen (Tag Assistant) — if your HeatMapX tag shows up under "Fired", it's working.

If the tag doesn't fire — checklist

Did you hit Publish? Saving alone doesn't push changes live. This is the most common cause
Is the trigger All Pages? A page-specific trigger means other pages won't be tracked
Is a cookie consent banner (consent mode) blocking it? With some consent management tools, Custom HTML tags are held back until the visitor consents. Check the tag's consent settings and how your CMP categorizes it
Is the data-site-key correct? Pasting another site's key sends your data into the wrong site

Let Claude Code walk you through it

If you'd rather not hunt through the GTM interface, you can ask an AI agent like Claude Code to guide you. Copy the prompt below, swap in your own site key, and paste it in.

I want to deploy the HeatMapX heatmap tracking tag via Google Tag Manager.
Walk me through the GTM interface one step at a time, waiting for my reply at each step.

The tag to use (Custom HTML, All Pages trigger):
<script src="https://heatmapx.com/tracker.js?key=YOUR-SITE-KEY" data-site-key="YOUR-SITE-KEY"></script>

If you're not using GTM and want the tag straight in your site's code, this version lets Claude Code do the file edits for you:

Install the HeatMapX heatmap tracking tag in this project.
Make sure the following tag is included right before </head> on every page, and tell me which files you changed.

<script src="https://heatmapx.com/tracker.js?key=YOUR-SITE-KEY" data-site-key="YOUR-SITE-KEY"></script>

HeatMapX is built so that pulling and analyzing your data also works from Claude Code (CLI integration) — see the "CLI & Skills" page on your dashboard once you're set up.

Verify it works: the numbers should move

After installing, browse a few pages of your own site, then open your HeatMapX dashboard. If "Sessions today" is climbing for your site, tracking is live.

The sign of success isn't "no errors" — it's numbers moving on the dashboard. If nothing moves, run through the checklist above in order.