heatmappheatmapp
Back to Installation Guides

Add heatmapp via Google Tag Manager

Follow these steps to integrate heatmapp analytics through Google Tag Manager. Important: You must use Custom HTML tag type and include the data-website-id attribute.

Create a Custom HTML tag in GTM

Add heatmapp tracking through Google Tag Manager:

  1. Open your Google Tag Manager account
  2. Go to Tags and click New
  3. IMPORTANT: Choose Custom HTML as the tag type (do NOT use "Script URL" or other tag types)
  4. Paste your complete heatmapp tracking script:
Code
<script  
  defer  
  data-website-id="YOUR_WEBSITE_ID"  
  data-domain="your_domain.com"  
  src="https://heatm.app/js/script.v2.min.js"  
></script>

Critical: Replace `YOUR_WEBSITE_ID` with your actual Website ID from heatmapp. Replace `your_domain.com` with your website's root domain. 5. Set trigger to All Pages 6. Click Save 7. IMPORTANT: Click Submit and Publish your container (Preview mode is not enough - you must publish for tracking to work)

Common Mistakes to Avoid

DO NOT use these methods - they will NOT work:

  • Using "Script URL" tag type (it won't include the required `data-website-id` attribute)
  • Only pasting the script URL without the full script tag
  • Forgetting to include `data-website-id` attribute
  • Only testing in Preview mode without publishing
  • Using a different website ID than the one in your heatmapp dashboard

The script tag MUST include both `data-website-id` and `data-domain` attributes for tracking to work.

Verify installation on your live site

After publishing your GTM container, verify the installation:

  1. Visit your live website (not GTM Preview mode)
  2. Open browser Developer Tools (F12 or Right-click → Inspect)
  3. Go to the Elements tab
  4. Press Ctrl+F (or Cmd+F on Mac) and search for `script.v2.min.js`
  5. Find the script tag and verify it has:
  • `src="https://heatm.app/js/script.v2.min.js"`
  • `data-website-id="YOUR_ACTUAL_WEBSITE_ID"` (must match your dashboard)
  • `data-domain="your_domain.com"`
  1. Go to the Console tab and check for errors:
  • Good: No errors related to heatmapp
  • Bad: If you see `Heatm.app: Missing data-website-id on script tag` - the script tag is missing the attribute
  1. Go to the Network tab, filter by `send-events`
  2. Interact with your page (click, scroll)
  3. Verify you see requests to `/.netlify/functions/send-events`
  • Good: Requests appear with status 200
  • Bad: No requests = script not working
  • Bad: Requests with 500 status = check website ID exists in your dashboard

Troubleshooting

If you see no events in your dashboard:

  • Check browser console for `Heatm.app: Missing data-website-id` error
  • Solution: The script tag is missing `data-website-id`. Go back to GTM and ensure you used Custom HTML tag with the complete script tag including the attribute.
  • Check Network tab - no `send-events` requests appear
  • Solution: Script may not be loading. Verify the script tag appears in Elements tab. Check if ad blockers or browser extensions are blocking it.
  • Check Network tab - `send-events` requests return 500 errors
  • Solution: Your website ID may not exist. Verify the ID in your heatmapp dashboard matches exactly what you pasted in GTM.
  • Events appear in console but not in dashboard
  • Solution: Wait 2-3 minutes for data to process. Refresh your dashboard. Check that you're viewing the correct website in your dashboard.

Still having issues? Contact support@heatm.app with:

  • Your website ID
  • Screenshot of the script tag from Elements tab
  • Screenshot of Console errors (if any)
  • Screenshot of Network tab showing send-events requests

For advanced configuration options like localhost tracking, custom API endpoints, or cross-domain setup, see the script configuration reference.