Chartbeat Troubleshooting & Debugging | Blue Frog Docs

Chartbeat Troubleshooting & Debugging

Troubleshooting playbook and diagnostics checklist for Chartbeat.

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
  1. Check domain configuration:
// Ensure domain matches your site
var _sf_async_config = {
  uid: 12345,
  domain: 'yourdomain.com',  // Should match your actual domain
  useCanonical: true
};
  1. 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>

  1. 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)

  2. 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');
}
  1. 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'
  });
}
  1. 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
  1. 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');
});
  1. 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
};
  1. 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:

  3. Documentation:

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
  }
});
↑ Back to top
// SYS.FOOTER