Chartbeat Troubleshooting & Debugging

Overview

This guide helps you diagnose and resolve common Chartbeat tracking issues. Chartbeat provides real-time analytics for content publishers, and proper configuration is essential for accurate metrics.

Debug Mode

Enable Debug Mode

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

// Add to your Chartbeat configuration
var _sf_async_config = {
  uid: 12345,
  domain: 'yourdomain.com',
  useCanonical: true,
  debug: true  // Enable debug mode
};

Check Script Loading

Verify Chartbeat is loaded correctly:

// Open browser console and check
if (typeof _sf_async_config !== 'undefined') {
  console.log('Chartbeat config loaded:', _sf_async_config);
} else {
  console.error('Chartbeat config not found');
}

// Check if tracking object exists
if (typeof pSUPERFLY !== 'undefined') {
  console.log('Chartbeat tracker loaded');
} else {
  console.error('Chartbeat tracker not loaded');
}

Common Issues

No Data Appearing in Dashboard

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

Solutions:

1. Verify UID is correct:

// Check your UID matches your Chartbeat account
console.log(_sf_async_config.uid);

// Verify it matches the UID in your Chartbeat settings

2. Check domain configuration:

// Ensure domain matches your site
var _sf_async_config = {
  uid: 12345,
  domain: 'yourdomain.com',  // Should match your actual domain
  useCanonical: true
};

3. Verify script is loaded:

<!-- Chartbeat script should be in page -->
<script type="text/javascript">
  var _sf_async_config = { uid: 12345, domain: 'yourdomain.com' };
  (function() {
    function loadChartbeat() {
      var e = document.createElement('script');
      e.type = 'text/javascript';
      e.async = true;
      e.src = '//static.chartbeat.com/js/chartbeat.js';
      document.body.appendChild(e);
    }
    loadChartbeat();
  })();
</script>

4. Check network requests:

   • Open Developer Tools → Network tab
   • Filter by "chartbeat"
   • Look for requests to static.chartbeat.com and ping.chartbeat.net
   • Status should be 200 (Success)

5. Verify canonical URLs:

// If using canonical URLs, ensure they're properly set
var _sf_async_config = {
  uid: 12345,
  domain: 'yourdomain.com',
  useCanonical: true
};

// Check canonical tag exists
var canonical = document.querySelector('link[rel="canonical"]');
if (canonical) {
  console.log('Canonical URL:', canonical.href);
} else {
  console.warn('No canonical URL found');
}

Page Views Not Tracking

Symptoms: Some pages aren't appearing in Chartbeat.

Solutions:

1. Verify script on all pages:

// Check if Chartbeat config exists on problem pages
if (typeof _sf_async_config === 'undefined') {
  console.error('Chartbeat not initialized on this page');
}

2. Check for single-page app issues:

// For SPAs, manually trigger page view
if (typeof pSUPERFLY !== 'undefined' && pSUPERFLY.virtualPage) {
  pSUPERFLY.virtualPage({
    path: '/new-page-path',
    title: 'New Page Title'
  });
}

3. Verify sections and authors:

// Ensure sections and authors are properly set
var _sf_async_config = {
  uid: 12345,
  domain: 'yourdomain.com',
  sections: 'News,Politics',  // Categories for this page
  authors: 'John Doe'         // Author name
};

Real-Time Metrics Delayed

Symptoms: Real-time dashboard shows delays or missing recent data.

Solutions:

1. Check ping rate:

// Chartbeat pings every 15 seconds by default
// Verify pings in Network tab
// Look for requests to ping.chartbeat.net

2. Verify page is active:

// Chartbeat only tracks active pages
// Check if user interaction detected
document.addEventListener('mousemove', function() {
  console.log('User active - Chartbeat should be tracking');
});

3. Check for ad blockers:
   • Disable browser extensions
   • Test in incognito/private mode
   • Ad blockers often block Chartbeat

Video Tracking Not Working

Symptoms: Video engagement metrics not appearing.

Solutions:

1. Enable video tracking:

var _sf_async_config = {
  uid: 12345,
  domain: 'yourdomain.com',
  autoDetect: true  // Auto-detect video players
};

2. Manually track video events:

// For custom video players
if (typeof pSUPERFLY !== 'undefined' && pSUPERFLY.videoEvent) {
  // Track video play
  videoPlayer.on('play', function() {
    pSUPERFLY.videoEvent('play', {
      videoId: 'video-123',
      title: 'Video Title'
    });
  });

  // Track video complete
  videoPlayer.on('complete', function() {
    pSUPERFLY.videoEvent('complete', {
      videoId: 'video-123',
      title: 'Video Title'
    });
  });
}

Historical Data Discrepancies

Symptoms: Historical reports show inconsistent data.

Solutions:

1. Understand data processing delays:

   • Real-time: Instant
   • Historical: Processed hourly
   • Reports: May take 2-4 hours to finalize

2. Check for configuration changes:

   • Review when sections/authors changed
   • Check domain configuration history
   • Verify UID hasn't changed

3. Compare with other analytics:

// Export data from both platforms
// Compare key metrics:
// - Page views
// - Unique visitors
// - Time on site

Debugging Techniques

Verify Configuration

// Comprehensive configuration check
function checkChartbeatConfig() {
  console.group('Chartbeat Configuration Check');

  if (typeof _sf_async_config === 'undefined') {
    console.error('Chartbeat config not defined');
    console.groupEnd();
    return;
  }

  console.log('✓ Config exists');
  console.log('UID:', _sf_async_config.uid);
  console.log('Domain:', _sf_async_config.domain);
  console.log('Use Canonical:', _sf_async_config.useCanonical);
  console.log('Sections:', _sf_async_config.sections);
  console.log('Authors:', _sf_async_config.authors);

  if (typeof pSUPERFLY !== 'undefined') {
    console.log('✓ Chartbeat tracker loaded');
  } else {
    console.error('Chartbeat tracker not loaded');
  }

  console.groupEnd();
}

checkChartbeatConfig();

Monitor Network Requests

// Log Chartbeat network activity
function monitorChartbeat() {
  // Monitor ping requests
  setInterval(function() {
    console.log('Chartbeat ping should occur (every 15s)');
  }, 15000);

  // Check Network tab for:
  // - static.chartbeat.com (script load)
  // - ping.chartbeat.net (tracking pings)
}

monitorChartbeat();

Test Page Views

// Test page view tracking
function testPageView() {
  if (typeof pSUPERFLY === 'undefined') {
    console.error('Chartbeat not loaded');
    return;
  }

  console.log('Current page:', window.location.href);
  console.log('Page title:', document.title);

  // For SPAs, test virtual page view
  if (pSUPERFLY.virtualPage) {
    pSUPERFLY.virtualPage({
      path: '/test-page',
      title: 'Test Page'
    });
    console.log('Virtual page view sent');
  }
}

testPageView();

Browser-Specific Issues

Safari ITP (Intelligent Tracking Prevention)

// Chartbeat uses first-party cookies, less affected by ITP
// Ensure proper domain configuration
var _sf_async_config = {
  uid: 12345,
  domain: 'yourdomain.com',
  useCanonical: true
};

Content Security Policy (CSP)

<!-- Add Chartbeat domains to CSP -->
<meta http-equiv="Content-Security-Policy"
      content="script-src 'self' static.chartbeat.com;
               connect-src 'self' ping.chartbeat.net;">

Ad Blockers

// Detect if Chartbeat is blocked
setTimeout(function() {
  if (typeof pSUPERFLY === 'undefined') {
    console.warn('Chartbeat likely blocked by ad blocker');

    // Log to your analytics
    if (typeof yourAnalytics !== 'undefined') {
      yourAnalytics.track('chartbeat_blocked');
    }
  }
}, 2000);

Performance Issues

Script Loading Impact

<!-- Use async loading (already default) -->
<script type="text/javascript" async src="//static.chartbeat.com/js/chartbeat.js"></script>

<!-- For better performance, load at end of body -->

Reduce Ping Frequency

// Note: Ping frequency is controlled by Chartbeat
// Cannot be modified in standard implementation
// Contact Chartbeat support for custom configurations

Data Quality Issues

Incorrect Sections or Authors

// Validate metadata before setting
var _sf_async_config = {
  uid: 12345,
  domain: 'yourdomain.com',
  sections: getSections(),  // Function to get current sections
  authors: getAuthors()      // Function to get current authors
};

function getSections() {
  // Extract from page metadata
  var sections = document.querySelector('meta[name="article:section"]');
  return sections ? sections.content : 'Uncategorized';
}

function getAuthors() {
  // Extract from page metadata
  var author = document.querySelector('meta[name="author"]');
  return author ? author.content : 'Unknown';
}

Bot Traffic

// Chartbeat filters bot traffic automatically
// Check dashboard settings to verify bot filtering is enabled
// Review User Agents in reports for suspected bot patterns

Getting Help

Check Chartbeat Status

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

Enable Maximum Debugging

// Enable all debug options
var _sf_async_config = {
  uid: 12345,
  domain: 'yourdomain.com',
  debug: true,
  useCanonical: true
};

// Log all configuration
console.log('Full Chartbeat config:', _sf_async_config);

// Monitor tracker state
if (typeof pSUPERFLY !== 'undefined') {
  console.log('Tracker methods:', Object.keys(pSUPERFLY));
}

Contact Support

If issues persist:

1. Collect debug information:

   • Browser and version
   • Chartbeat configuration (_sf_async_config)
   • Console errors/warnings
   • Network request screenshots
   • UID and domain

2. Contact Chartbeat Support:

   • Email: support@chartbeat.com
   • Include all debug information
   • Provide example URLs showing the issue

3. Documentation:

   • Visit Chartbeat Help Center
   • Review implementation guides
   • Check video tutorials

Best Practices

Regular Testing

// Create a diagnostic function
function runChartbeatDiagnostics() {
  console.group('Chartbeat Diagnostics');

  // 1. Check configuration
  console.log('Config:', _sf_async_config);

  // 2. Check tracker loaded
  console.log('Tracker loaded:', typeof pSUPERFLY !== 'undefined');

  // 3. Verify canonical URLs
  var canonical = document.querySelector('link[rel="canonical"]');
  console.log('Canonical:', canonical ? canonical.href : 'Not set');

  // 4. Check metadata
  console.log('Sections:', _sf_async_config.sections);
  console.log('Authors:', _sf_async_config.authors);

  console.groupEnd();
}

// Run on page load
runChartbeatDiagnostics();

Monitor in Production

// Log Chartbeat errors
window.addEventListener('error', function(e) {
  if (e.message.includes('chartbeat') ||
      (e.filename && e.filename.includes('chartbeat'))) {
    console.error('Chartbeat error:', e);
    // Send to your error tracking service
  }
});