Heap Analytics Troubleshooting & Debugging | Blue Frog Docs

Heap Analytics Troubleshooting & Debugging

Troubleshooting playbook and diagnostics checklist for Heap Analytics.

Overview

This guide helps you diagnose and resolve common Heap Analytics tracking issues. Heap uses automatic event capture with retroactive analytics, making proper configuration essential for accurate data collection.

Debug Mode

Enable Debug Mode

Enable debug mode to see detailed tracking information in your browser console:

// Enable Heap debug mode
heap.debug();

// Or configure on initialization
heap.load("YOUR_APP_ID", {
  debug: true
});

Check Heap Loading

Verify Heap is loaded correctly:

// Open browser console and check
if (typeof heap !== 'undefined') {
  console.log('Heap loaded successfully');
  console.log('App ID:', heap.appid);
  console.log('User ID:', heap.userId);
  console.log('Identity:', heap.identity);
} else {
  console.error('Heap not loaded');
}

Common Issues

No Data Appearing in Dashboard

Symptoms: Tracking code is installed but no data shows in Heap dashboard.

Solutions:

  1. Verify App ID is correct:
// Check your App ID
if (typeof heap !== 'undefined') {
  console.log('Heap App ID:', heap.appid);
}

// Should match the App ID in your Heap project settings
  1. Check script installation:
<!-- Heap tracking script should be in <head> -->
<script type="text/javascript">
  window.heap=window.heap||[],heap.load=function(e,t){window.heap.appid=e,window.heap.config=t=t||{};
  var r=document.createElement("script");
  r.type="text/javascript",r.async=!0,r.src="https://cdn.heapanalytics.com/js/heap-"+e+".js";
  var a=document.getElementsByTagName("script")[0];
  a.parentNode.insertBefore(r,a);
  for(var n=function(e){return function(){heap.push([e].concat(Array.prototype.slice.call(arguments,0)))}},
  p=["addEventProperties","addUserProperties","clearEventProperties","identify","resetIdentity","removeEventProperty","setEventProperties","track","unsetEventProperty"],
  o=0;o<p.length;o++)heap[p[o]]=n(p[o])};
  heap.load("YOUR_APP_ID");
</script>

  1. Verify network requests:

    • Open Developer Tools → Network tab
    • Filter by "heap"
    • Look for requests to heapanalytics.com
    • Status should be 200 (Success)

  2. Check for ad blockers:

    • Disable browser extensions
    • Test in incognito/private mode
    • Ad blockers often block Heap

  3. Verify environment:

// Check if Heap is in development mode
if (heap.config && heap.config.secureCookie === false) {
  console.log('Heap in development mode');
}

Auto-Captured Events Not Showing

Symptoms: Clicks and pageviews aren't being captured automatically.

Solutions:

  1. Verify auto-capture is enabled:

    • Go to Heap dashboard → Data → Auto-Capture
    • Ensure auto-capture is turned on
    • Check that specific events aren't disabled

  2. Wait for data processing:

    • Live view: Events appear within seconds
    • Historical analysis: Up to 2 hours for full processing
    • Retroactive definitions: Can take several hours

  3. Check element visibility:

// Heap only captures visible, interactive elements
// Verify element is:
// - Visible (not display:none or visibility:hidden)
// - Has clickable area
// - Not covered by another element
  1. Verify Hierarchy selector:
    • Use Heap's visual labeler
    • Check that element hierarchy is stable
    • Ensure selectors aren't too specific or too broad

Identity Not Working

Symptoms: User identification not associating events correctly.

Solutions:

  1. Call identify with user ID:
// Identify user when they log in
heap.identify('user_12345');

// Verify it was set
console.log('Heap Identity:', heap.identity);
  1. Add user properties:
// Set user properties
heap.addUserProperties({
  'email': 'user@example.com',
  'name': 'John Doe',
  'plan': 'premium',
  'signup_date': '2024-01-15'
});
  1. Check timing:
// Call identify BEFORE tracking events
heap.identify('user_12345');
heap.addUserProperties({ email: 'user@example.com' });
heap.track('signup_completed');
  1. Reset identity for testing:
// Reset identity to test as new user
heap.resetIdentity();

// Verify reset
console.log('Identity after reset:', heap.identity);

Custom Events Not Tracking

Symptoms: Manually tracked events aren't appearing.

Solutions:

  1. Verify track() syntax:
// Correct syntax
heap.track('Button Clicked', {
  'button_name': 'signup',
  'page': 'homepage'
});

// Check in console with debug mode
heap.debug();
heap.track('Test Event', { test: true });
  1. Check event name:
    • Event names are case-sensitive
    • Use consistent naming conventions
    • Avoid special characters
// Good event names
heap.track('Purchase Completed');
heap.track('Video Played');

// Inconsistent naming (creates separate events)
heap.track('purchase completed');  // Different case
heap.track('Purchase completed');  // Different case
  1. Verify properties:
// Properties must be simple types
heap.track('Event Name', {
  'string_prop': 'value',
  'number_prop': 123,
  'boolean_prop': true
});

// Don't use complex types
heap.track('Bad Event', {
  'function': function() {},  // Won't work
  'object': { nested: 'data' } // Won't work
});

Properties Not Showing

Symptoms: Event or user properties missing from reports.

Solutions:

  1. Set event properties globally:
// Add properties to all subsequent events
heap.addEventProperties({
  'app_version': '2.1.0',
  'environment': 'production'
});

// These will be included in all tracked events
  1. Check property types:
// Heap supports:
// - Strings
// - Numbers
// - Booleans
// - Dates (as ISO strings)

heap.addEventProperties({
  'plan': 'premium',           // String ✓
  'users': 50,                 // Number ✓
  'active': true,              // Boolean ✓
  'signup_date': '2024-01-15'  // Date string ✓
});
  1. Remove properties:
// Remove a specific property
heap.removeEventProperty('property_name');

// Clear all event properties
heap.clearEventProperties();
  1. Debug properties:
// Log current event properties
heap.debug();
heap.addEventProperties({ test: 'value' });
// Check console for confirmation

Session Recording Not Working

Symptoms: Session replays aren't capturing or playing back.

Solutions:

  1. Verify session capture is enabled:

    • Go to Heap dashboard → Settings → Session Capture
    • Check that recording is enabled for your environment
    • Verify capture rate settings

  2. Check privacy settings:

// Configure privacy settings
heap.load("YOUR_APP_ID", {
  disableTextCapture: false  // Enable text capture
});

// Or set after initialization
heap.config.disableTextCapture = false;
  1. Redact sensitive data:
<!-- Use data attributes to redact sensitive information -->
<input type="password" class="heap-redact-text" />
<div class="heap-redact-attributes">Sensitive content</div>

<!-- Or via CSS classes -->
<input class="heap-ignore" type="text" />
  1. Check browser compatibility:
    • Session recording requires modern browsers
    • Check browser console for errors
    • Test in different browsers

Debugging Techniques

Comprehensive Health Check

// Complete Heap diagnostic
function heapHealthCheck() {
  console.group('Heap Analytics Health Check');

  // 1. Check if Heap is loaded
  if (typeof heap === 'undefined') {
    console.error('❌ Heap not loaded');
    console.groupEnd();
    return;
  }
  console.log('✓ Heap loaded');

  // 2. Check App ID
  console.log('App ID:', heap.appid || 'Not set');

  // 3. Check identity
  console.log('User ID:', heap.userId || 'Anonymous');
  console.log('Identity:', heap.identity || 'Not identified');

  // 4. Test tracking
  heap.track('Health Check', {
    timestamp: new Date().toISOString()
  });
  console.log('✓ Test event sent');

  console.groupEnd();
}

heapHealthCheck();

Monitor Heap Calls

// Log all Heap method calls
const originalTrack = heap.track;
heap.track = function() {
  console.log('heap.track called:', arguments);
  return originalTrack.apply(this, arguments);
};

const originalIdentify = heap.identify;
heap.identify = function() {
  console.log('heap.identify called:', arguments);
  return originalIdentify.apply(this, arguments);
};

Verify Auto-Capture

// Test auto-capture
function testAutoCapture() {
  console.log('Click any element to see auto-capture');

  // Enable debug mode
  heap.debug();

  // Add event listener to log clicks
  document.addEventListener('click', function(e) {
    console.log('Element clicked:', e.target);
    console.log('Heap should auto-capture this');
  });
}

testAutoCapture();

Browser-Specific Issues

Safari ITP (Intelligent Tracking Prevention)

// Heap uses first-party cookies to minimize ITP impact
// Ensure proper domain configuration
heap.load("YOUR_APP_ID", {
  secureCookie: true,  // Use secure cookies
  disableTextCapture: false
});

Content Security Policy (CSP)

<!-- Add Heap domains to CSP -->
<meta http-equiv="Content-Security-Policy"
      content="script-src 'self' https://cdn.heapanalytics.com 'unsafe-inline';
               connect-src 'self' https://heapanalytics.com;">

Ad Blockers

// Detect if Heap is blocked
setTimeout(function() {
  if (typeof heap === 'undefined' || !heap.appid) {
    console.warn('Heap likely blocked by ad blocker');

    // Fallback tracking
    if (typeof alternativeAnalytics !== 'undefined') {
      alternativeAnalytics.track('heap_blocked');
    }
  }
}, 2000);

Performance Issues

Script Loading Impact

<!-- Heap script is async by default, but verify -->
<script type="text/javascript">
  window.heap=window.heap||[];
  heap.load=function(e,t){
    // Heap async loader code here
    var r=document.createElement("script");
    r.type="text/javascript";
    r.async=!0;  // Verify async is true
    r.src="https://cdn.heapanalytics.com/js/heap-"+e+".js";
    // ...
  };
  heap.load("YOUR_APP_ID");
</script>

Too Many Events

// Throttle high-frequency events
let scrollTimeout;
window.addEventListener('scroll', function() {
  clearTimeout(scrollTimeout);
  scrollTimeout = setTimeout(function() {
    heap.track('Scroll Event', {
      depth: window.scrollY
    });
  }, 1000); // Only track once per second
});

Data Quality Issues

Duplicate Events

// Prevent duplicate tracking
let eventTracked = {};

function trackOnce(eventName, properties) {
  const key = eventName + JSON.stringify(properties);
  if (!eventTracked[key]) {
    heap.track(eventName, properties);
    eventTracked[key] = true;

    // Clear after 5 seconds
    setTimeout(() => {
      delete eventTracked[key];
    }, 5000);
  }
}

// Use for critical events
trackOnce('Purchase', { orderId: '12345' });

Property Type Mismatches

// Validate property types before sending
function trackWithValidation(eventName, properties) {
  const validProperties = {};

  for (const key in properties) {
    const value = properties[key];
    const type = typeof value;

    if (type === 'string' || type === 'number' || type === 'boolean') {
      validProperties[key] = value;
    } else {
      console.warn(`Invalid property type for ${key}:`, type);
    }
  }

  heap.track(eventName, validProperties);
}

trackWithValidation('Event', {
  valid: 'string',
  invalid: { nested: 'object' }  // Will be filtered out
});

Getting Help

Check Heap Status

Visit Heap's status page to check for service interruptions.

Enable Maximum Debugging

// Enable all debug features
heap.debug();

// Log all Heap state
console.log('Heap State:', {
  appid: heap.appid,
  userId: heap.userId,
  identity: heap.identity,
  config: heap.config
});

// Test all major functions
heap.identify('test_user');
heap.addUserProperties({ test: true });
heap.track('Debug Test');
heap.addEventProperties({ debug: true });

Contact Support

If issues persist:

  1. Collect debug information:

    • Browser and version
    • Heap App ID
    • Console errors/warnings
    • Network request details
    • Steps to reproduce

  2. Contact Heap Support:

    • Email: support@heap.io
    • In-app chat (available in dashboard)
    • Include all debug information

  3. Heap Documentation:

Best Practices

Regular Testing

// Create test suite
function runHeapDiagnostics() {
  console.group('Heap Diagnostics');

  // 1. Verify loaded
  console.log('Loaded:', typeof heap !== 'undefined');

  // 2. Check configuration
  console.log('App ID:', heap.appid);

  // 3. Test identification
  heap.identify('test_user_' + Date.now());
  console.log('Identity test completed');

  // 4. Test event tracking
  heap.track('Diagnostic Test', {
    timestamp: new Date().toISOString()
  });
  console.log('Event test completed');

  // 5. Test properties
  heap.addEventProperties({ test_prop: true });
  console.log('Properties test completed');

  console.groupEnd();
}

// Run on page load
runHeapDiagnostics();

Monitor in Production

// Log Heap errors
window.addEventListener('error', function(e) {
  if (e.message && e.message.includes('heap')) {
    console.error('Heap error:', e);
    // Send to error tracking service
  }
});

// Monitor Heap availability
setInterval(function() {
  if (typeof heap === 'undefined') {
    console.error('Heap no longer available');
    // Alert monitoring service
  }
}, 60000); // Check every minute

Testing Checklist

  • Heap script loaded successfully
  • App ID is correct
  • Auto-capture working for clicks
  • Custom events tracking
  • User identification working
  • User properties being set
  • Event properties being added
  • Session recording enabled (if applicable)
  • No console errors
  • Network requests successful
↑ Back to top
// SYS.FOOTER