Custom Tags — Filter Heatmaps by Your Own A/B Test Variants

HeatMapX now supports custom tags. Add one line to your page and every click, scroll, and mouse-move event of that visitor carries the tag, so you can filter the heatmap in the dashboard by tag.

This came from a customer request: "Our A/B test already runs in our own code. We just want to see the heatmap per variant." It's not limited to A/B tests. Logged-in or not, which plan the member is on, which campaign they came from — anything your site already knows about the visitor can become a segment.

How to use it

Add the following to any page that has the tracking tag. It works before or after the tracking tag (calls made earlier are queued and applied once the tag loads).

<script>
  window.hmx = window.hmx || function(){ (window.hmx.q = window.hmx.q || []).push(arguments) };
  hmx('set', 'ab_variant', 'B');
</script>

If your server renders the HTML, you can also pass the tags in one go, before the tracking tag.

<script>window.heatmapxTags = { ab_variant: 'B', plan: 'pro' };</script>

Tags persist across page navigations within the same browser tab, so setting them once at the start of a visit is enough. hmx('unset', 'ab_variant') removes a tag.

Filtering in the dashboard

Open a site, then a page's heatmap. A "Tag" dropdown appears in the top-right filter row, next to the device filter. Each option shows the key, value, and session count, such as ab_variant = B (128). Pick one and the click, scroll, and mouse-move heatmaps re-render for that segment only.

The dropdown is hidden on sites with no tagged data yet. It becomes available as soon as the first tagged event arrives after installation.

Filtering through the MCP server

The MCP server, used from Claude and other AI tools, supports tags as well.

Pass tags: { "ab_variant": "B" } to get_heatmap_summary to get the summary for that segment. Several keys are combined with AND.
A new list_tags tool returns the keys and values observed on a site.

Rules

Keys: lowercase letters, digits, _, and -, 1 to 32 characters (uppercase is converted to lowercase). Values: 1 to 64 characters. Up to 10 keys at a time.
Don't put personal data in values, such as email addresses, user IDs, or order numbers. Values containing both @ and . are not stored.
Up to 50 distinct values per key over the last 30 days. New values beyond that are ignored.
If you don't use tags, nothing changes in what is sent.

Pricing

Available on all plans, including Free.

Scope of impact

Uses your existing tracking tag as-is. Sites that don't set tags are unaffected. The tracking script (tracker.js) is cached by browsers for up to 24 hours, so right after installation some returning visitors may pick up the change the following day.