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:

_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 support@chartbeat.com.

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.

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, 64 characters per section

news,sports

authors

text

None

10 authors max, 64 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';

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.

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

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:

_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

None

My Title

Example usage:

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

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

None

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.

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:

_sf_async_config.mobileApp = true;

Virtual referrer

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.

Field Name

Value Type

Default Value

Max Length

Example Value

virtualReferrer

text

None

None

site.com/foo

Example usage:

_sf_async_config.virtualReferrer = 'mysite.com/artice-xyz.html';

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.

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';

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">

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.