Chartbeat Event Tracking | Blue Frog Docs

Chartbeat Event Tracking

Complete guide to Chartbeat event tracking and measurement

Chartbeat Event Tracking

Overview

Chartbeat is a real-time analytics platform focused on content engagement and audience attention. Unlike traditional analytics tools that emphasize pageviews and sessions, Chartbeat measures how people actually engage with your content - how long they stay, how far they scroll, and whether they're actively reading or just browsing.

Originally built for publishers and media companies, Chartbeat excels at measuring content performance in real-time. Its event tracking capabilities extend beyond standard pageviews to capture meaningful engagement signals like article recirculation, social sharing, and video playback. If your business depends on content engagement and audience attention, Chartbeat provides metrics that matter.

Event Model

How Chartbeat Events Work

Chartbeat automatically captures engagement metrics without extensive configuration, but also supports custom events for tracking specific interactions.

Core Engagement Metrics (Automatic):

  • Engaged Time: Time user is actively engaged (tab focused, scrolling, reading)
  • Scroll Depth: How far down the page users scroll
  • Recirculation: Clicks to other content on your site
  • Social Referrals: Traffic from social platforms
  • Read vs Idle: Distinguishes active reading from idle time

Custom Events: Custom events in Chartbeat track specific user actions beyond automatic engagement tracking.

Key Concepts

  • Engaged Time: Active attention (not just time on page)
  • Active vs Idle: User activity detection (mouse, keyboard, scroll)
  • Read: Content consumption measurement
  • Recirculation: Internal navigation tracking
  • Headlines: A/B testing for content titles
  • Custom Events: Specific interaction tracking

Standard Events

Chartbeat automatically tracks core engagement events.

Automatically Tracked Metrics

Pageviews:

// Automatic when Chartbeat script loads
// No additional code needed

Engaged Time:

  • Tracked automatically
  • Measures active attention (not passive time)
  • Requires user activity (mouse, scroll, keyboard)
  • Pauses when tab is inactive

Scroll Depth:

  • Percentage of page scrolled
  • Tracked in real-time
  • Shows engagement with content length

Recirculation:

  • Internal link clicks
  • Content-to-content navigation
  • Measures content discovery

Virtual Pageviews (SPA)

For single-page applications:

// Track virtual pageview
pSUPERFLY.virtualPage({
  path: '/new-page',
  title: 'New Page Title'
});

Chartbeat automatically tracks external link clicks:

  • Destination domain
  • Link text
  • Link position on page

Video Tracking

Chartbeat integrates with video players:

Supported Players:

  • YouTube
  • Vimeo
  • JW Player
  • Brightcove
  • Video.js

Automatic Metrics:

  • Video starts
  • Play/pause events
  • Completion rate
  • Time watched

Custom Events

Custom events track specific interactions beyond automatic tracking.

Tracking Custom Events

JavaScript API:

// Basic custom event
pSUPERFLY.trackEvent('Event Name');

// Event with value
pSUPERFLY.trackEvent('Button Click', {
  value: 'Signup CTA'
});

// Event with multiple properties
pSUPERFLY.trackEvent('Feature Used', {
  feature: 'Share',
  location: 'Article Body',
  type: 'Twitter'
});

Common Custom Events

Button Clicks:

// CTA clicks
pSUPERFLY.trackEvent('CTA Click', {
  button: 'Subscribe Now',
  location: 'Article End',
  article_id: 'post_12345'
});

// Navigation clicks
pSUPERFLY.trackEvent('Menu Click', {
  item: 'Pricing',
  position: 'Header'
});

Form Interactions:

// Form submission
pSUPERFLY.trackEvent('Form Submit', {
  form_type: 'Newsletter',
  location: 'Sidebar',
  success: 'true'
});

// Form abandonment
pSUPERFLY.trackEvent('Form Abandon', {
  form_type: 'Newsletter',
  fields_completed: '2'
});

Content Engagement:

// Social sharing
pSUPERFLY.trackEvent('Share', {
  platform: 'Twitter',
  content_type: 'Article',
  article_id: 'post_12345'
});

// Related content clicks
pSUPERFLY.trackEvent('Related Click', {
  source_article: 'post_12345',
  target_article: 'post_67890',
  position: '2'
});

// Comment posted
pSUPERFLY.trackEvent('Comment', {
  article_id: 'post_12345',
  comment_length: '250'
});

Media Interactions:

// Image gallery
pSUPERFLY.trackEvent('Gallery Navigation', {
  action: 'Next',
  image_number: '5',
  total_images: '12'
});

// Podcast player
pSUPERFLY.trackEvent('Podcast Play', {
  episode: 'Episode 42',
  timestamp: '300'
});

Subscription & Conversion Events

// Paywall interaction
pSUPERFLY.trackEvent('Paywall View', {
  article_type: 'Premium',
  user_status: 'Anonymous'
});

// Subscription started
pSUPERFLY.trackEvent('Subscription Start', {
  plan: 'Monthly',
  price: '9.99',
  trigger: 'Paywall'
});

// Trial signup
pSUPERFLY.trackEvent('Trial Signup', {
  duration: '14_days',
  source: 'Article_Paywall'
});

Ecommerce Events

While Chartbeat is primarily for content, it supports ecommerce tracking for content-driven commerce sites.

Product Engagement

// Product viewed
pSUPERFLY.trackEvent('Product View', {
  product_id: 'SKU_12345',
  product_name: 'Wireless Headphones',
  category: 'Electronics',
  price: '199.99',
  source: 'Article_Recommendation'
});

// Product click from content
pSUPERFLY.trackEvent('Product Click', {
  product_id: 'SKU_12345',
  source_article: 'post_67890',
  position: 'In_Article'
});

Commerce Actions

// Add to cart from content
pSUPERFLY.trackEvent('Add to Cart', {
  product_id: 'SKU_12345',
  source: 'Article_Link',
  article_id: 'post_67890',
  price: '199.99'
});

// Purchase attribution
pSUPERFLY.trackEvent('Purchase', {
  order_id: 'ORDER_123',
  revenue: '199.99',
  referral_article: 'post_67890',
  products: '1'
});

User Properties

Chartbeat tracks user segments and properties for audience analysis.

Setting User Properties

Reader Properties:

// Set user segment
_sf_async_config.userType = 'Subscriber';

// Set user status
_sf_async_config.userStatus = 'Premium';

// Custom user properties
_sf_async_config.customUserProperties = {
  subscription_tier: 'Gold',
  account_age: '6_months',
  article_views_this_month: '25'
};

Subscriber Tracking

// Identify subscribers
_sf_async_config.userType = 'Subscriber';

// Subscriber details
pSUPERFLY.trackEvent('Subscriber Action', {
  action: 'Article_View',
  subscription_type: 'Annual',
  account_value: 'High'
});

Engagement Segments

Chartbeat automatically segments users by:

  • New vs Returning: First visit vs repeat visitors
  • Loyal Readers: Frequency and recency
  • Engaged vs Idle: Activity level
  • Social vs Direct: Traffic source
  • Subscriber Status: Paid vs free

Author & Content Properties

// Set article metadata
_sf_async_config.authors = 'Jane Doe';
_sf_async_config.sections = 'Technology,AI';
_sf_async_config.type = 'Article';

// Custom content properties
_sf_async_config.customProperties = {
  word_count: '2500',
  read_time: '10',
  content_tier: 'Premium',
  published_date: '2024-01-15'
};

Event Parameters

Custom Properties in Events

pSUPERFLY.trackEvent('Video Complete', {
  video_id: 'vid_12345',
  video_title: 'Product Tutorial',
  duration: '180',
  quality: '1080p',
  source: 'Article_Embed',
  autoplay: 'false',
  completion_time: '175'
});

Content Context Parameters

// Include article context
pSUPERFLY.trackEvent('Social Share', {
  platform: 'Facebook',
  article_id: _sf_async_config.uid,
  article_title: _sf_async_config.title,
  article_author: _sf_async_config.authors,
  article_section: _sf_async_config.sections
});

Automatically Captured Context

Chartbeat includes with all events:

  • Page URL: Current page
  • Page Title: Document title
  • Referrer: Traffic source
  • Device Type: Desktop, mobile, tablet
  • Browser: Browser name/version
  • Location: Country, city (if enabled)
  • Time on Page: Engaged time
  • Scroll Depth: Current scroll position

Implementation Methods

1. JavaScript Snippet (Standard)

Basic Installation:

<script type="text/javascript">
  var _sf_async_config = _sf_async_config || {};
  _sf_async_config.uid = YOUR_ACCOUNT_ID;
  _sf_async_config.domain = 'yourdomain.com';
  _sf_async_config.useCanonical = true;

  (function(){
    function loadChartbeat() {
      window._sf_endpt = (new Date()).getTime();
      var e = document.createElement('script');
      e.setAttribute('language', 'javascript');
      e.setAttribute('type', 'text/javascript');
      e.setAttribute('src','//static.chartbeat.com/js/chartbeat.js');
      document.body.appendChild(e);
    }
    var oldonload = window.onload;
    window.onload = (typeof window.onload != 'function') ?
      loadChartbeat : function() { oldonload(); loadChartbeat(); };
  })();
</script>

With Content Metadata:

<script type="text/javascript">
  var _sf_async_config = _sf_async_config || {};
  _sf_async_config.uid = YOUR_ACCOUNT_ID;
  _sf_async_config.domain = 'yourdomain.com';
  _sf_async_config.useCanonical = true;

  // Article metadata
  _sf_async_config.sections = 'Technology,AI';
  _sf_async_config.authors = 'Jane Doe,John Smith';
  _sf_async_config.type = 'Article';
  _sf_async_config.title = 'Article Title';

  // Custom properties
  _sf_async_config.customProperties = {
    word_count: '2500',
    premium_content: 'true'
  };

  (function(){ /* Chartbeat loader code */ })();
</script>

2. Single-Page Applications

Track Route Changes:

// React Router example
import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';

function App() {
  const location = useLocation();

  useEffect(() => {
    // Track virtual pageview
    if (window.pSUPERFLY) {
      window.pSUPERFLY.virtualPage({
        path: location.pathname,
        title: document.title
      });
    }
  }, [location]);

  return <Routes>...</Routes>;
}

Vue.js:

// In router configuration
router.afterEach((to) => {
  if (window.pSUPERFLY) {
    window.pSUPERFLY.virtualPage({
      path: to.fullPath,
      title: to.meta.title || document.title
    });
  }
});

3. Video Player Integration

YouTube:

// Chartbeat automatically tracks YouTube videos
// Just ensure video iframe is on the page

Custom Video Player:

// Track video events manually
videoPlayer.on('play', function() {
  pSUPERFLY.trackEvent('Video Play', {
    video_id: videoPlayer.videoId,
    video_title: videoPlayer.title
  });
});

videoPlayer.on('ended', function() {
  pSUPERFLY.trackEvent('Video Complete', {
    video_id: videoPlayer.videoId,
    watch_time: videoPlayer.currentTime
  });
});

4. WordPress Plugin

Chartbeat offers an official WordPress plugin:

  1. Install "Chartbeat" plugin
  2. Enter account credentials
  3. Configure content tracking options
  4. Automatic tracking enabled

Custom events in WordPress:

jQuery(document).ready(function($) {
  $('.share-button').on('click', function() {
    pSUPERFLY.trackEvent('Social Share', {
      platform: $(this).data('platform'),
      article_id: chartbeat_config.post_id
    });
  });
});

Debugging & Validation

1. Chartbeat Dashboard (Real-Time)

Live Monitoring:

  1. Log into Chartbeat dashboard
  2. See real-time visitor count
  3. View active pages
  4. Monitor engagement metrics
  5. Check event firing in real-time

2. Browser Console

// Check if Chartbeat is loaded
console.log(typeof pSUPERFLY);

// Check configuration
console.log(_sf_async_config);

// Test event (sends to Chartbeat)
pSUPERFLY.trackEvent('Test Event', {
  source: 'Console',
  test: 'true'
});

// Check page tracking
console.log(window._sf_endpt); // Page load timestamp

3. Network Tab Inspection

DevTools Network Tab:

Filter: chartbeat.com
Look for: ping.chartbeat.net/ping
Check: Query parameters include event data

Request Parameters:

  • h: Host/domain
  • p: Page path
  • t: Page title
  • E: Engaged time
  • c: Custom events (encoded)

4. Chartbeat Dashboard - Historical

Check Event Data:

  1. Go to Dashboard > Engagement
  2. View custom events in reporting
  3. Check event volumes
  4. Validate event properties

5. Real-Time Widget

Use Chartbeat's real-time widget:

  1. Open Chartbeat dashboard
  2. Perform action on your site
  3. See event appear in real-time feed
  4. Validate event properties

Best Practices

Engagement Tracking

✅ Do:

  • Trust automatic engaged time tracking
  • Use scroll depth to measure content consumption
  • Track recirculation to measure content discovery
  • Monitor active vs idle time
  • Analyze real-time engagement during content launches

❌ Don't:

  • Override automatic engagement detection
  • Track pageviews as custom events (already tracked)
  • Ignore engaged time in favor of total time
  • Treat all time on page as equal (idle vs active)

Custom Event Strategy

✅ Do:

  • Track interactions not captured automatically
  • Use consistent event naming
  • Include relevant context in event properties
  • Focus on content engagement events
  • Track conversion actions (subscribe, share, comment)

❌ Don't:

  • Create hundreds of unique event names
  • Track every click (use selectively)
  • Include PII in event data
  • Duplicate automatic tracking

Content Metadata

✅ Do:

// Rich content metadata
_sf_async_config.sections = 'Technology,AI,Machine Learning';
_sf_async_config.authors = 'Jane Doe';
_sf_async_config.type = 'Article';
_sf_async_config.customProperties = {
  word_count: '2500',
  read_time: '10',
  content_tier: 'Free',
  published_date: '2024-01-15'
};

❌ Don't:

  • Leave metadata fields empty
  • Use inconsistent section names
  • Forget to update metadata on dynamic pages
  • Include sensitive information

Video Tracking

✅ Do:

  • Let Chartbeat auto-track supported players
  • Track custom players manually
  • Include video metadata (title, duration)
  • Measure completion rates
  • Track video source (embedded in articles)

❌ Don't:

  • Duplicate video tracking (auto + manual)
  • Track every second of playback
  • Ignore video engagement metrics

Real-Time Optimization

✅ Do:

  • Monitor real-time dashboard during content launches
  • Use headline testing for content optimization
  • Track social referrals in real-time
  • Respond to engagement patterns
  • Optimize content based on scroll depth

❌ Don't:

  • Ignore real-time insights
  • Only look at historical data
  • Miss engagement patterns during traffic spikes

Publisher-Specific Best Practices

For News & Media:

  • Track article recirculation paths
  • Monitor breaking news engagement
  • Measure social sharing virality
  • Track subscription conversions from content
  • Use headline testing

For Blogs & Content Sites:

  • Focus on engaged time per post
  • Track newsletter signups from content
  • Measure related content clicks
  • Monitor scroll depth to optimize content length

For Content Commerce:

  • Track product clicks from articles
  • Measure commerce attribution
  • Monitor affiliate link clicks
  • Track purchase paths from content

Privacy & Compliance

✅ Do:

  • Configure geographic data retention
  • Honor Do Not Track preferences
  • Implement consent management
  • Anonymize user identifiers
  • Document data collection practices

❌ Don't:

  • Collect PII without consent
  • Ignore GDPR/CCPA requirements
  • Track without user awareness

Performance Optimization

  • Chartbeat script loads asynchronously
  • Minimal performance impact (< 15KB)
  • Non-blocking page load
  • Real-time pings don't affect UX

Data Quality

Ensure Accurate Tracking:

  • Use canonical URLs for duplicate content
  • Set proper page types (Article, Video, Gallery)
  • Include all relevant metadata
  • Test on staging before production
  • Monitor for tracking errors in dashboard

Content Taxonomy:

  • Maintain consistent section names
  • Use hierarchical sections: Technology > AI > ML
  • Tag content accurately
  • Update taxonomy as site evolves

Additional Resources:

↑ Back to top
// SYS.FOOTER