Customize Tracking Settings
Use our JavaScript configuration variables to fine-tune your pageview tracking and send key page properties to Chartbeat.
Overview
Our JavaScript tag 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 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.
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:
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 support@chartbeat.com.
Field Name
Value Type
Default Value
Max Length
Example Value
uid
integer
None
None
12345
Example usage:
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.
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 useCanonical and useCanonicalDomain settings.
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:
These variables accept one or multiple string values parsed by comma, so the examples directly above and below would both be acceptable formats.
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:
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:
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 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.
If you are unable or prefer to not use canonical links for your website, you may alternatively use our custom path variable to assign custom Chartbeat page paths (more information below).
Additional fields and settings
Custom path
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.
Field Name
Value Type
Default Value
Max Length
Example Value
path
text
None
None
site.com/foo
Example usage:
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:
Content type
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.
Field Name
Value Type
Default Value
Max Length
Example Value
type
text
None
64 characters
video page
Example usage:
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.
Important: Chartbeat tracking for mobile apps is an add-on feature. Contact your Chartbeat Customer Success representative or support@chartbeat.com to learn more.
Field Name
Value Type
Default Value
Max Length
Example Value
mobileApp
boolean
false
None
true
Example usage:
No cookies
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 here.
Field Name
Value Type
Default Value
Max Length
Example Value
noCookies
text
false
None
true
Example usage:
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:
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:
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:
Cookie domain
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.
Field Name
Value Type
Default Value
Max Length
Example Value
cookieDomain
text
None
None
subdomain.mysite.com
Example usage:
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:
Next steps
Use the above guide to review your site's canonical URL implementation, and identify how best to configure our section and author variables for your website.
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.
Last updated