Customize Tracking Settings
document.title. Other page properties such as a page's section or author will only be tracked by populating those values via our section and author 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.
These variables must be set in your snippet for data to appear in your dashboard.
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.
_sf_async_config.domain = 'mysite.com';
_sf_async_config.uid = 12345;
We recommend that all Chartbeat tracked websites utilize the following variables to pass consistent page URLs and section/author data into your Chartbeat tools:
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 custom path variable instead of the
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.
_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';
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
authorsfields in your Chartbeat tag.
Your team may also use DOM API methods like
document.location.href.splitto 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 = "").
Use these variables to have chartbeat.js collect your Chartbeat page paths from the canonical URL
<link>element in your page HTML.
truetells our tracker to collect the path portion of your canonical URL for the Chartbeat page path.
useCanonicalDomainset to true tells our tracker to collect the domain portion of your canonical URL as well for the Chartbeat page path.
_sf_async_config.useCanonical = true;
_sf_async_config.useCanonicalDomain = true;
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.htmlwould be the expected Chartbeat page path we receive from a visitor who views this page in their browser:
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
useCanonicalDomainvariables 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 canonical links 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 Google's Guide to Canonical Links.
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.
Use this variable only if your team is unable or prefers to not use canonical URL variables 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.
_sf_async_config.path = 'domain.com/news/article-xyz.html';
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).
_sf_async_config.title = 'Live Updates: 2020 Election';
Use this variable only if your team utilizes our Advanced Queries tool 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.
_sf_async_config.type = 'photo gallery page';
Use this variable only if your mobile app for smartphone devices uses web views to display your mobile website content pages.
mobileAppshould 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.
_sf_async_config.mobileApp = true;
Use this variable only if you need to override the default referring page value collected automatically by our tracker via
document.referrer. This variable can only be used to override the referring page URL for internal referred pageviews — meaning the user was referred to their current page by another page on your site.
_sf_async_config.virtualReferrer = 'mysite.com/artice-xyz.html';
_sf_async_config.noCookies = true;
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
aliason 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.
_sf_async_config.alias = 'mysite.com/article-xyz.html';
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.
_sf_async_config.sponsorName = 'Spotify';
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:
_sf_async_config.scrollElement = true;
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 Help Center article on this topic.
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.
_sf_async_config.cookieDomain = 'subdomain.mysite.com';
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:
_sf_async_config.pingServer = 'pong.chartbeat.net';
For sites that make use of virtual page change (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 subscriber engagement article or alternative implementations article if your site does not allow users to subscribe or create user profiles.