LogoLogo
Help CenterStatusContact
  • Chartbeat Documentation
  • Implement Tracking
    • Standard Websites
      • Adding chartbeat.js to Your Site
      • Customize Tracking Settings
      • Tracking Virtual Page Change
      • User Subscriber Status
      • Alternative Site Integrations
      • Integration QA Steps: Website
      • Additional Page Metadata
    • Google AMP
      • Chartbeat Code for AMP
      • AMP Configuration Variables
      • Alternative AMP Integration
      • Integration QA Steps: AMP
    • Mobile App SDKs
      • Intro to Mobile App Tracking
      • Android SDK
      • iOS SDK
      • Integration QA Steps: Mobile Apps
  • Feature Integrations
    • Headline and Image Testing
      • Adding chartbeat_mab.js to Your Site
      • Image Compatibility
      • Flicker & Flicker Control
      • mab.js Specifications
      • Integration QA Steps: Headline and Image Testing
    • Video Engagement
      • Adding chartbeat_video.js to Your Site
      • Supported OVP Integrations
      • Custom Player Integration SDK
      • Configure Video Tracking Settings
      • Integration QA: Video Tracking
    • Conversion
      • Adding subscriptions.js to Your Site
      • Conversion Events
      • Integration QA Steps: Conversion
      • Supported Conversion Flows
  • API Docs
    • Real-Time API
      • Getting Started with our Real-Time API
      • Traffic Data
      • Video Engagement Data
    • Historical API
      • Getting Started with our Historical API
      • One-time Queries
      • Recurring Queries
      • Metrics, Dimensions, and Filters
    • Headline Testing API
      • Getting Started with our Headline Testing API
      • Raw Data
      • Summary Report
      • Variant Report
    • Conversion API
      • Getting Started with our Conversion API
      • Top Articles
    • Data Lab API
      • Getting Started with Data Lab API
  • Help Center
  • Contact Support
  • Datastream Docs
  • Back to Chartbeat.com
Powered by GitBook
On this page
  • Overview
  • Required fields
  • Domain
  • UID
  • Recommended fields and settings
  • Sections & authors
  • Canonical page path
  • Additional fields and settings
  • Custom path
  • Page title
  • Content type
  • Mobile app
  • No cookies
  • Path alias
  • Sponsor name
  • Scroll element
  • Cookie domain
  • IP truncation
  • Next steps

Was this helpful?

  1. Implement Tracking
  2. Standard Websites

Customize Tracking Settings

Use our JavaScript configuration variables to fine-tune your pageview tracking and send key page properties to Chartbeat.

PreviousAdding chartbeat.js to Your SiteNextTracking Virtual Page Change

Last updated 1 month ago

Was this helpful?

Overview

Our includes required and recommended configuration variables which determine how we will measure each pageview to your website. When chartbeat.js loads, it collects certain data about the page automatically, such as the page title from document.title. Other page properties such as a page's section or author will only be tracked by populating those values via our configuration variables in your Chartbeat tracking snippet.

Review the descriptions and example values for each of our required and recommended configuration variables listed below to determine the optimal tracking settings for your site.

Required fields

These variables must be set in your snippet for data to appear in your dashboard.

Domain

This value should be set to the Chartbeat site id (site name) for your website. This is usually the root domain without http or 'www.' prepended.

Field Name

Value Type

Default Value

Max Length

Example Value

domain

text

None

None

mysite.com

Example usage:

_sf_async_config.domain = 'mysite.com';

UID

A numerical id value associated with your Chartbeat account, three to six digits in length. A single organization in Chartbeat with multiple sites has only one UID that can be used in the JavaScript tag for all of the sites belonging to that account. If you do not know your organization's account id, you can request it from your Chartbeat Account Executive, Customer Success representative, or the Technical Solutions team at .

Field Name

Value Type

Default Value

Max Length

Example Value

uid

integer

None

None

12345

Example usage:

_sf_async_config.uid = 12345;

Recommended fields and settings

We recommend that all Chartbeat tracked websites utilize the following variables to pass consistent page URLs and section/author data into your Chartbeat tools: sections, authors, useCanonical, useCanonicalDomain.

Sections & authors

Our tools prominently feature section and author data and the ability to filter on these values so your users can easily focus on the data that matters for their roles. To make use of this feature, you will need to populate the sections and authors config variables in our snippet with data from your site's data layer.

Field Name

Value Type

Default Value

Max Length

Example Value

sections

text

None

10 sections max per page, 63 characters per section

news,sports

authors

text

None

10 authors max per pagee, 63 characters per author

Jane Doe

Example usage:

_sf_async_config.sections = 'US Politics';
_sf_async_config.authors = 'Bob Johnson';

These variables accept one or multiple string values parsed by comma, so the examples directly above and below would both be acceptable formats.

_sf_async_config.sections = 'News,Sports,Local';
_sf_async_config.authors = 'Megan Summers,Kevin Smith';

Tip: Chartbeat uses the "|" character for a splitting process when organizing section and author values, so it is recommend to avoid this character when defining these variables.

Additional detail:

You can populate these fields dynamically by tying them to a variable in your CMS which stores section and author data for all pages of your site. If your site uses a data layer that contains these values, you can assign those variables as well directly to the _sf_async_config.sections or authors fields in your Chartbeat tag.

Your team may also use DOM API methods like document.getElementsByClassName or document.location.href.split to parse these section and author values directly from existing metadata elements in your pages.

If there is no section or author tag needed on a page, set the variable to "no section", "no author", or a blank string (e.g. _sf_async_config.authors = "").

Canonical page path

Use these variables to have chartbeat.js collect your Chartbeat page paths from the canonical URL <link> element in your page HTML. useCanonical set to true tells our tracker to collect the path portion of your canonical URL for the Chartbeat page path. useCanonicalDomain set to true tells our tracker to collect the domain portion of your canonical URL as well for the Chartbeat page path.

Field Name

Value Type

Default Value

Max Length

Example Value

useCanonical

boolean

false

N/A

true

useCanonicalDomain

boolean

false

N/A

true

Example usage:

_sf_async_config.useCanonical = true;
_sf_async_config.useCanonicalDomain = true;

Additional detail:

Web analytics tools rely on a single value sent from each page of your site as the unique page identifier to enable traffic data aggregation at the page level. In Chartbeat, this field element is the Chartbeat page path which we collect from each page of your site where our tracking code is configured. Most often, the page path consists of the domain name and path portion of your website URLs. For example, yourdomain.com/index.html would be the expected Chartbeat page path we receive from a visitor who views this page in their browser:

 https://www.yourdomain.com/index.html?source=email

If you have a mobile site on a separate subdomain, m.domain.com for example, but you're setting canonical URLs on these pages to the desktop URL (not including the 'm.' subdomain), using these recommended canonical path variables in your Chartbeat configuration should ensure that we properly aggregate data for pages across your mobile and desktop instead of tracking them as separate pages with unique subdomains.

Tip: To prevent duplicate page entries in your Chartbeat reports, a unique article or landing page on your site should send us the same unchanging canonical URL across all Chartbeat-tracked platforms where a user can access that page.

Additional fields and settings

Custom path

Field Name

Value Type

Default Value

Max Length

Example Value

path

text

None

None

site.com/foo

Example usage:

_sf_async_config.path = 'domain.com/news/article-xyz.html';

Page title

By default, chartbeat.js collects page titles from document.title. Use this variable only if you need to override the default page title collected by our tracker (the value contained in the <title> tags in your page HTML).

Field Name

Value Type

Default Value

Max Length

Example Value

title

text

None

100 characters

My Title

Example usage:

_sf_async_config.title = 'Live Updates: 2020 Election';

Content type

Use this variable only if your team utilizes Advanced Queries or Data Lab and would benefit from audience engagement reports in Chartbeat segmented by your custom content-type values, such as 'gallery page', 'standalone video page', 'article page', etc. Note that this variable only accepts one value — it does not parse on commas like our section and author variables.

Field Name

Value Type

Default Value

Max Length

Example Value

type

text

None

64 characters

video page

Example usage:

_sf_async_config.type = 'photo gallery page';

Mobile app

Use this variable only if your mobile app for smartphone devices uses web views to display your mobile website content pages. mobileApp should be set to true for users of your webview mobile app in order to distinguish app users from mobile website visitors in your Chartbeat reports.

Field Name

Value Type

Default Value

Max Length

Example Value

mobileApp

boolean

false

None

true

Example usage:

_sf_async_config.mobileApp = true;

No cookies

Field Name

Value Type

Default Value

Max Length

Example Value

noCookies

text

false

None

true

Example usage:

_sf_async_config.noCookies = true;

Path alias

Use this variable only if the article URLs linked in your homepage HTML do not match the expanded URLs nor the Chartbeat page paths of those target article pages. Set alias on the article pages to the full URL as it appears in your homepage HTML to ensure proper referrer tracking as visitors move from your homepage to these article pages. This should only be needed to resolve missing pin issues in our Heads Up Display tool.

Field Name

Value Type

Default Value

Max Length

Example Value

alias

text

None

None

site.com/foo

Example usage:

_sf_async_config.alias = 'mysite.com/article-xyz.html';

Sponsor name

Use this variable only if your team utilizes our Advanced Queries tool and would benefit from audience engagement reports in Chartbeat segmented by your sponsored content (advertorial) campaign name IDs, such as 'Mercedes', 'Mastercard-Jun2020', 'Netflix-Q1-2021-CID123', etc. Note that this variable only accepts one value — it does not parse on commas like our section and author variables.

Field Name

Value Type

Default Value

Max Length

Example Value

sponsorName

text

None

64 characters

Mercedes

Example usage:

_sf_async_config.sponsorName = 'Spotify';

Scroll element

Use this variable only for pages with custom scrollable elements where our tracking script will not automatically measure scrolled pixel depth of a user scrolling through the embedded article. You will also need to need to add a special attribute to your scrollable div so our tracker can find it on the page: data-cb-scroll-element="1"

Field Name

Value Type

Default Value

Max Length

Example Value

scrollElement

boolean

false

None

true

Example usage:

_sf_async_config.scrollElement = true;
<div data-cb-scroll-element="1">

Cookie domain

If your site uses multi-level subdomains, like sub2.sub1.mysite.com, the cookie domain can be set to sub2.sub1.mysite.com but it cannot be set to sub1.mysite.com.

Field Name

Value Type

Default Value

Max Length

Example Value

cookieDomain

text

None

None

subdomain.mysite.com

Example usage:

_sf_async_config.cookieDomain = 'subdomain.mysite.com';

IP truncation

For clients in the EU, add this additional config value to your Chartbeat snippet in order to point traffic to our proxy layer that de-identifies IP addresses within the EU:

Field Name

Value Type

Default Value

pingServer

text

'pong.chartbeat.net'

Example usage:

_sf_async_config.pingServer = 'pong.chartbeat.net';

Next steps

If section or author variables are left unpopulated, your teams will not be able to utilize our section and author dashboard filters and site traffic reports. If your webpage templates do not contain canonical URLs, your team may choose to utilize our instead of the useCanonical and useCanonicalDomain settings.

Duplicate page tracking is a common issue for web analytics implementations, frequently caused by inconsistent page paths collected by the tracker across unique page views for the same article. This leads to inaccurate traffic reports as metrics for a single page of your site end up attributed across multiple separate pages in your analytics data. The useCanonical and useCanonicalDomain variables provide a simple mechanism for sending consistent URLs as your Chartbeat page paths across all pages of your site. To use these variables, your site HTML should already include for every page. It's important that a given page which can be accessed via multiple unique URLs maintain an unchanging canonical URL set in the HTML of that page and all its versions.

Tip: We strongly encourage implementing canonical links in your site HTML to ensure consistent tracking of pages and to prevent seeing duplicate listings of the same page in your reports. If you're not familiar with canonical links, check out .

If you are unable or prefer to not use canonical links for your website, you may alternatively use our to assign custom Chartbeat page paths (more information below).

Use this variable only if your team is unable or prefers to not use above. You may use this path variable to assign consistent page URLs in your Chartbeat data. We strongly recommend that you use standard, canonical page paths for your site instead of passing in custom page id values.

Important: Chartbeat tracking for mobile apps is an add-on feature. Contact your Chartbeat Customer Success representative or to learn more.

Use this variable only to prevent our JavaScript from using first-party cookies. Note that we only use first-party cookies, and disabling these will prevent headline testing functionality in addition to other Chartbeat measurements like visitor frequency. Learn more about using our cookieless mode on your site .

Use this variable only on a page using a subdomain (e.g. subdomain.mysite.com) when you want visitor cookies to be assigned to the subdomain and not the root domain (e.g. mysite.com). To learn more about whether this setting is right for your site, check out our on this topic.

Use the above guide to review your site's implementation, and identify how best to configure our variables for your website.

For sites that make use of (single page apps and sites with infinite scroll page change) use the instructions in the next article to implement our virtual page change tracking method. If your site does not make use of virtual page change, you may skip to our article or article if your site does not allow users to subscribe or create user profiles.

canonical links
Google's Guide to Canonical Links
support@chartbeat.com
Help Center article
virtual page change
subscriber engagement
alternative implementations
custom path variable
custom path variable
canonical URL variables
canonical URL
section and author
support@chartbeat.com
section and author
here
JavaScript tag