heatm.app

heatm.app

Back to Installation Guides

Add heatm.app via Google Tag Manager

Follow these steps to integrate heatm.app 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 heatm.app 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 heatm.app 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 heatm.app. 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 heatm.app 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"`

6. Go to the Console tab and check for errors:

  • ✅ Good: No errors related to heatm.app
  • ❌ Bad: If you see `🔥 Heatm.app: Missing data-website-id on script tag` - the script tag is missing the attribute

7. Go to the Network tab, filter by `send-events`

8. Interact with your page (click, scroll)

9. 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 heatm.app 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.