Chartbeat Cross-Domain Tracking

Overview

Cross-domain tracking in Chartbeat enables you to measure user journeys that span multiple domains, subdomains, or related properties. This is essential for publishers with distributed content across different domains, partnerships, syndication arrangements, or separate mobile/AMP sites. Proper cross-domain configuration ensures engagement data remains unified and accurate across your entire content ecosystem.

Common Cross-Domain Scenarios

Multi-Domain Publishers:

• Main site: example.com
• Blog: blog.example.com
• Store: shop.example.com
• Regional sites: uk.example.com, de.example.com

Content Syndication:

• Original publisher site
• Syndicated content on partner sites
• White-label content distributions

Technical Variants:

• Desktop site: www.example.com
• Mobile web: m.example.com
• AMP pages: example-com.cdn.ampproject.org
• App WebViews embedding web content

Multi-Brand Networks:

• Parent company site
• Multiple brand sites under same ownership
• Shared content across brand portfolio

Configuration Fundamentals

UID and Domain Strategy

Chartbeat uses UID (User ID) and domain parameters to organize tracking:

Single UID Approach (Recommended for unified reporting):

// All properties use same UID, different domains
// Main site
var _sf_async_config = {
  uid: 12345,
  domain: 'example.com',
  // ... other config
};

// Subdomain
var _sf_async_config = {
  uid: 12345,  // Same UID
  domain: 'blog.example.com',  // Different domain
  // ... other config
};

Multiple UID Approach (Separate reporting per property):

// Each property has own UID
// Main site
var _sf_async_config = {
  uid: 12345,
  domain: 'example.com'
};

// Blog site
var _sf_async_config = {
  uid: 67890,  // Different UID
  domain: 'blog.example.com'
};

When to Use Each:

• Single UID: Unified reporting, shared content, consistent branding
• Multiple UIDs: Separate business units, different editorial teams, isolated reporting needs

useCanonical and useCanonicalDomain

These settings are critical for cross-domain tracking:

var _sf_async_config = {
  uid: 12345,
  domain: 'example.com',
  useCanonical: true,          // Use canonical URL path
  useCanonicalDomain: true,    // Use canonical domain
  // ... other config
};

What They Do:

• useCanonical: true - Use the path from <link rel="canonical"> tag instead of window.location.pathname
• useCanonicalDomain: true - Use the domain from canonical tag instead of current hostname

Why This Matters:

<!-- Page on m.example.com points to desktop canonical -->
<link rel="canonical" href="https://www.example.com/article/story">

<!-- With useCanonical and useCanonicalDomain -->
<!-- Chartbeat tracks as: www.example.com/article/story -->
<!-- NOT: m.example.com/article/story -->
<!-- Result: Mobile and desktop views counted together -->

Setup Steps

1. UID and Domain Mapping

Create a comprehensive mapping of all properties:

Documentation Template:

# Chartbeat Cross-Domain Configuration

## UID: 12345 (Unified Tracking)

### Domain Mappings:
- **www.example.com**: Main domain, `domain: 'example.com'`
- **blog.example.com**: Blog subdomain, `domain: 'blog.example.com'`
- **m.example.com**: Mobile web, `domain: 'example.com'`, `useCanonical: true`
- **AMP pages**: `domain: 'example.com'`, special AMP configuration

### Canonical URL Strategy:
- Mobile and AMP pages point to desktop canonical
- All tracking unified under primary domain
- Regional sites maintain separate domain parameters

2. Canonical URL Implementation

Ensure every page has proper canonical tags:

Desktop Page (www.example.com/article/story):

<link rel="canonical" href="https://www.example.com/article/story">

Mobile Page (m.example.com/article/story):

<!-- Points to desktop version -->
<link rel="canonical" href="https://www.example.com/article/story">

AMP Page (amp.example.com/article/story):

<!-- Points to desktop version -->
<link rel="canonical" href="https://www.example.com/article/story">

Subdomain (blog.example.com/post/story):

<!-- Self-referential if primary for this content -->
<link rel="canonical" href="https://blog.example.com/post/story">

3. Referrer Preservation

Maintain accurate referrer data across domain transitions:

Problem: Referrer lost during redirects or cross-domain navigation

Solution 1: Query Parameter Passing

// On source domain (before redirect)
const originalRef = document.referrer;
const targetURL = new URL('https://target.example.com/page');
targetURL.searchParams.set('ref', originalRef);
window.location.href = targetURL.toString();

// On target domain (after redirect)
const urlParams = new URLSearchParams(window.location.search);
const preservedRef = urlParams.get('ref') || document.referrer;

var _sf_async_config = {
  uid: 12345,
  domain: 'example.com',
  r: preservedRef  // Use preserved referrer
};

Solution 2: sessionStorage

// On source domain
sessionStorage.setItem('chartbeat_original_ref', document.referrer);

// On target domain
var originalRef = sessionStorage.getItem('chartbeat_original_ref') || document.referrer;

var _sf_async_config = {
  uid: 12345,
  domain: 'example.com',
  r: originalRef
};

4. Section and Author Alignment

Ensure taxonomy consistency across domains:

Challenge: Same content may have different section/author on different domains

Solution: Standardize metadata

// Define canonical section mappings
const sectionMap = {
  'blog/tech': 'Technology',
  'main/technology': 'Technology',
  'mobile/tech': 'Technology'
};

// Use consistent format
function getCanonicalSection(rawSection) {
  return sectionMap[rawSection] || rawSection;
}

var _sf_async_config = {
  uid: 12345,
  domain: 'example.com',
  sections: getCanonicalSection(pageSection)
};

5. Implementation Code Examples

Subdomain Configuration (blog.example.com):

var _sf_async_config = {
  uid: 12345,
  domain: 'blog.example.com',  // Separate domain for blog
  sections: 'Blog,Technology',
  authors: 'Jane Smith',
  title: 'Blog Post Title',
  path: '/post/my-blog-post',
  useCanonical: true,
  useCanonicalDomain: false  // Don't use canonical domain, keep as blog
};

Mobile Web Configuration (m.example.com):

var _sf_async_config = {
  uid: 12345,
  domain: 'example.com',  // Use main domain
  sections: 'News,Politics',
  authors: 'Jane Smith',
  title: 'Article Title',
  path: '/news/politics/article',
  useCanonical: true,
  useCanonicalDomain: true  // Unify with desktop
};

Regional Site Configuration (uk.example.com):

var _sf_async_config = {
  uid: 12345,
  domain: 'uk.example.com',  // Separate domain for regional
  sections: 'News,UK,Politics',
  authors: 'John Smith',
  title: 'UK News Article',
  path: '/news/uk/politics/article',
  useCanonical: true
};

AMP (Accelerated Mobile Pages) Integration

AMP requires special configuration via amp-analytics:

Basic AMP Configuration

<amp-analytics type="chartbeat">
  <script type="application/json">
  {
    "vars": {
      "uid": "12345",
      "domain": "example.com",
      "sections": "News,Politics",
      "authors": "Jane Smith",
      "title": "Article Title",
      "path": "/news/politics/article",
      "useCanonicalDomain": true
    }
  }
  </script>
</amp-analytics>

Dynamic AMP Configuration

Use AMP variables for dynamic content:

<amp-analytics type="chartbeat">
  <script type="application/json">
  {
    "vars": {
      "uid": "12345",
      "domain": "example.com",
      "sections": "${sections}",
      "authors": "${authors}",
      "title": "TITLE",
      "path": "CANONICAL_PATH",
      "useCanonicalDomain": true
    },
    "triggers": {
      "trackPageview": {
        "on": "visible",
        "request": "pageview"
      }
    }
  }
  </script>
</amp-analytics>

AMP Canonical Alignment

Ensure AMP canonical points to desktop:

<!-- On AMP page -->
<link rel="canonical" href="https://www.example.com/article/story">

<!-- AMP analytics will track as desktop domain -->

Content Syndication

Syndicated Content Tracking

When your content appears on partner sites:

Option 1: Track on Syndication Partner's Domain

// Content on partner-site.com showing your article
var _sf_async_config = {
  uid: 99999,  // Partner's UID
  domain: 'partner-site.com',
  sections: 'Syndicated,News',
  authors: 'Jane Smith',  // Your author
  title: 'Your Article Title',
  path: '/syndicated/your-article'
};

Option 2: Track on Your Domain (if allowed)

// Track as if on your site
var _sf_async_config = {
  uid: 12345,  // Your UID
  domain: 'example.com',  // Your domain
  sections: 'News,Politics',
  authors: 'Jane Smith',
  title: 'Article Title',
  path: '/news/politics/article',
  r: 'https://partner-site.com'  // Note partner referrer
};

White-Label Content

For white-label content distributed across multiple brands:

// Central content ID for cross-brand tracking
var contentId = 'article-12345';

// Brand A site
var _sf_async_config = {
  uid: 11111,
  domain: 'brand-a.com',
  sections: 'News',
  contentId: contentId  // Shared identifier
};

// Brand B site
var _sf_async_config = {
  uid: 22222,
  domain: 'brand-b.com',
  sections: 'News',
  contentId: contentId  // Same content ID for aggregation
};

Edge Cases

Iframe Embedded Content

When content is embedded via iframe:

Challenge: Iframe may have different domain than parent

Solution: Track in iframe context

// Inside iframe
var _sf_async_config = {
  uid: 12345,
  domain: 'example.com',
  sections: 'Widgets,EmbeddedContent',
  authors: 'Automated',
  title: 'Embedded Widget',
  path: '/widgets/embed',
  r: document.referrer  // Parent page URL
};

Paywall Redirects

Paywall systems that redirect users:

Issue: Redirect may change domain or lose referrer

Solution: Preserve original context

// Before paywall redirect
localStorage.setItem('chartbeat_pre_paywall', JSON.stringify({
  referrer: document.referrer,
  path: window.location.pathname,
  timestamp: Date.now()
}));

// After paywall (on return)
const prePaywall = JSON.parse(localStorage.getItem('chartbeat_pre_paywall') || '{}');

var _sf_async_config = {
  uid: 12345,
  domain: 'example.com',
  path: prePaywall.path || window.location.pathname,
  r: prePaywall.referrer || document.referrer
};

Third-Party Content Hubs

Content distributed through third-party platforms (Medium, LinkedIn, etc.):

Limitation: Usually cannot inject Chartbeat script

Alternative: Use canonical tags to consolidate reporting

<!-- On third-party platform -->
<link rel="canonical" href="https://www.example.com/original-article">

• Tracking happens on your domain
• Third-party views not captured in Chartbeat
• Consider supplementary tracking via platform's own analytics

Validation

Pre-Launch Testing

1. UID/Domain Matrix Verification

// Create test page on each domain
// Log configuration to console
console.table({
  'UID': _sf_async_config.uid,
  'Domain': _sf_async_config.domain,
  'Actual Hostname': window.location.hostname,
  'Use Canonical': _sf_async_config.useCanonical,
  'Use Canonical Domain': _sf_async_config.useCanonicalDomain
});

2. Canonical Tag Check

// Verify canonical tag present and correct
const canonical = document.querySelector('link[rel="canonical"]');
console.log('Canonical URL:', canonical ? canonical.href : 'MISSING');
console.log('Current URL:', window.location.href);
console.log('Match:', canonical && canonical.href === window.location.href);

3. Cross-Domain Journey Test

• Start on domain A
• Navigate to domain B
• Verify engagement continues
• Check referrer preserved
• Confirm metadata updates

Real-Time Dashboard Validation

Test Multi-Domain Setup:

1. Open Chartbeat Real-Time dashboard
2. Navigate to each domain/subdomain
3. Verify pages appear under correct domain filter
4. Check concurrent counts aggregate properly (if using single UID)
5. Confirm section/author metadata consistent

Domain Filter Testing:

Dashboard View: Real-Time
Filter: domain = "example.com"
Expected: Shows www, mobile, AMP (if using canonical domain)

Filter: domain = "blog.example.com"
Expected: Shows only blog content (if separate domain)

Network Request Inspection

Verify Ping Endpoints:

# Open DevTools Network tab
# Filter: chartbeat.net
# Check ping parameters:

# Main site ping
h=example.com&p=/article/story&u=12345

# Mobile site ping (should match if using canonical)
h=example.com&p=/article/story&u=12345

# Blog subdomain ping
h=blog.example.com&p=/post/story&u=12345

Engagement Timer Continuity

Cross-Domain Navigation Test:

1. Land on domain A, engage for 30 seconds
2. Click link to domain B (same UID)
3. Check if engagement timer:
   • Continues: Good for unified user journey (requires advanced setup)
   • Resets: Expected default behavior
4. For most setups, timer reset is normal and acceptable

Configuration Examples

Multi-Brand Network

// Parent company: holdings.example.com
var _sf_async_config = {
  uid: 10000,
  domain: 'holdings.example.com',
  sections: 'Corporate,Investor Relations',
  authors: 'Corporate Communications'
};

// Brand 1: brand1.example.com (shares content with parent)
var _sf_async_config = {
  uid: 10000,  // Shared UID
  domain: 'brand1.example.com',
  sections: 'Brand1,News',
  useCanonical: true
};

// Brand 2: brand2.com (separate domain, shared UID)
var _sf_async_config = {
  uid: 10000,  // Shared UID for network view
  domain: 'brand2.com',
  sections: 'Brand2,News',
  useCanonical: true
};

International/Regional Sites

// US site (primary)
var _sf_async_config = {
  uid: 12345,
  domain: 'example.com',
  sections: 'News,US,Politics'
};

// UK site
var _sf_async_config = {
  uid: 12345,  // Same UID for global reporting
  domain: 'uk.example.com',
  sections: 'News,UK,Politics'
};

// German site
var _sf_async_config = {
  uid: 12345,
  domain: 'de.example.com',
  sections: 'News,DE,Politik'  // Localized sections
};

Troubleshooting Table

Best Practices

1. Single UID Strategy: Use one UID for all related properties to enable unified reporting
2. Canonical Consistency: Implement canonical tags on all variant pages (mobile, AMP, etc.)
3. Document Everything: Maintain clear UID/domain mapping documentation
4. Standardize Taxonomy: Use consistent section and author names across all domains
5. Test Thoroughly: Validate tracking on each domain/subdomain before launch
6. Preserve Referrers: Implement referrer preservation for accurate traffic attribution
7. Monitor Regularly: Audit Real-Time dashboard to catch cross-domain issues early
8. Plan for Scale: Design taxonomy to accommodate future domains and properties

Checklist

• UID/domain mapping documented for all properties
• Canonical tags implemented on all pages
• useCanonical and useCanonicalDomain configured appropriately
• Referrer preservation implemented for cross-domain navigation
• Section/author taxonomy standardized across all domains
• AMP pages configured with amp-analytics
• Mobile web canonical points to desktop
• Subdomain tracking tested and validated
• Real-Time dashboard shows unified reporting (if single UID)
• Cross-domain navigation tested
• Network pings verified for each domain
• Documentation shared with stakeholders