Getting Started Guide
As a bit of background, Chartbeat code (around 3KB) is set to deploy in the
Other than that, the Chartbeat code adds a couple of event listeners for registering user engagement.
Part 1: Insert this right after the opening
Part 2: Insert this script right before the closing
Once this is implemented globally across your site, you might need to make a few configuration tweaks to better fit your site. All of these options are outlined in the rest of this guide.
window.onload function and should be placed at the end of the
UID & Subdomains
By default the UID variable should be automatically set to your Chartbeat Account number when adding a new site. To retrieve the correct Chartbeat code for your account, head on over to chart.bt/setup. It will look like this:
_sf_async_config.uid = #####;
If your site employs subdomains, you have the option of tracking with Chartbeat in one of two ways:
If you want to track a subdomain (e.g. "blog.yoursite.com") within an existing Dashboard, simply copy the exact same code that is on the existing domain and add it to the HTML of the subdomain.
If you want to track a subdomain separate from your other Chartbeat Publishing Dashboards, select "add site" from the Chartbeat settings page, and follow on-site instructions.
If you are adding a mobile subdomain, please refer to our Mobile Site Implementation for more information.
Does your site use query parameters for various tracking purposes, (e.g. seeing people who came from an email newsletter)? Or does your site have multiple URL structures for the same page/article (e.g. domain.com/section/artcle vs m.domain.com/12345)?
By default, Chartbeat is configured to use either the raw path or canonical links (when available). We strongly encourage implementing canonical links to ensure consistent tracking of pages and to prevent seeing multiple listings of the same page in the Chartbeat Dashboard. If you're not familiar with canonical links, check out Google's Guide to Canonical Links.
To utilize the canonical feature, you'll need to ensure that your site defines canonical links for each page (e.g
<link rel='canonical'.../>) and that the canonical variable is set to "true".
_sf_async_config.useCanonical = true;
Custom Path Variable
If you are unable or prefer to not use canonical links, you may alternatively set the Path Variable. The path must start with "/" (forward slash) and we highly recommend that you use a real path used to navigate to this page.
The value set for the Path Variable should be generated by your CMS or set to
window.location.pathname, so that the same piece of code can be used on all pages.
Examples of setting the Path Variable:
_sf_async_config.path = "/directory/path"; _sf_async_config.path = cms.path.variable; _sf_async_config.path = window.location.pathname;
If you are implementing Chartbeat on a separate mobile site (e.g. m.domain.com), please refer to our Mobile Site Implementation section.
Custom Page Titles
By default Chartbeat displays page titles by using
<title> tag in your sites header.
However, the title used for a page in Chartbeat can be overridden by setting the Title Variable. This can be useful in the cases where all pages have a common prefix (e.g. "Publication Name: Story Title"), or when most pages share a common site title.
You may manually set the Title Variable or populate them dynamically by tying them to a variable in your CMS.
Here you can set the title like this:
_sf_async_config.title = "Story Title"; _sf_async_config.title = cms.title.variable;
Sections & Authors
In Chartbeat Publishing you can filter your content by section or author. To implement this feature, you’ll need to set up section and author variables within the Chartbeat code. So if a page is written by Bob Johnson in the section US Politics, you would set:
_sf_async_config.sections = "US Politics"; _sf_async_config.authors = "Bob Johnson";
A page can both be in multiple sections and/or have multiple authors, therefore each variable accepts a comma separated list of values. So if a page is co-written by Megan Summers and Kevin Smith in the sections Fashion and Fashion News, you would set:
_sf_async_config.sections = "Fashion,Fashion News"; _sf_async_config.authors = "Megan Summers,Kevin Smith";
The sections variable does not need to reflect real sections on the site, but should be thought of as groupings of pages that can be filtered on. Our suggestion is to populate these fields dynamically by tying them to a variable in your CMS which globally represents your sections and authors, so they can be easily changed.
_sf_async_config.sections = cms.section.variable; _sf_async_config.authors = cms.author.variable;
You can also populate these variables by using page metadata, a tag that already exists in your code, or part of your URL structure which contains these values.
Mobile Site Implementation
If you have a separate mobile site (e.g. "m.site.com"), you’ll need to deploy Chartbeat code across all mobile pages. In order to track these pages within your existing Dashboard, just make sure to set the domain to the Desktop Domain name.
_sf_async_config.domain = 'site.com';
Canonical Links and Different Paths
Our best practice for combining mobile and desktop traffic for similar stories is to set the Path Variable on your mobile pages to the full canonical link of the desktop pages.
The line you will add to your mobile pages will look more or less like this:
_sf_async_config.path = '/matching-desktop-path';
No Canonical Links and Different Paths
To combine the mobile and desktop traffic for similar pages, you'll need to configure your Chartbeat implementation to identify the different versions as the same page.
The line you will add to your mobile pages should resemble:
_sf_async_config.path = 'site.com/matching-desktop-path';
If you are interested in having a separate Chartbeat Dashboard for your mobile site, please have your account administrator add an additional site to your account. Once this is done, you can set the Domain Variable to point to the new Dashboard.
AJAX & Infinite Scroll
If your site uses infinite scroll, serves up content dynamically via AJAX, or pages change without the URL subsequently changing or the DOM refreshing, you’ll need to do some additional implementation.
Anytime a visitor navigates to a new page or piece of content, you’ll need to call a custom variable called
pSUPERFLY. This variable is specifically designed for this kind of page change, and can be attached to click/swipe events, or to a pixel that is used to trigger content changes. Best practice would be to make sure the variable is linked to your AJAX call, so they always happen together.
You’ll need to setup logic to handle these lines of code:
_sf_async_config.sections="New Section"; _sf_async_config.authors="New Author"; pSUPERFLY.virtualPage("/newpath", "New title");
Simply put, you’re setting the author and section (if they change) ahead of time since we take that data as holdover information when we reload the page with
pSUPERFLY. If we are not passed the updated section and author information we’ll continue to register the original sections and authors from the previous page. If the new page has no section or author data, simply set that variable to "null". For example:
Next, when the page changes we’ll need to populate the path and title for the new page(s) within the
pSUPERFLY variable, so that the pings will reflect the new page the visitor is on.
pSUPERFLY should never be called when a user initially arrives on a page from an external source, and should only be called when a user navigates to subsequent pages without causing the DOM to be refreshed.
For pages with infinite scroll, any time a visitor is scrolling down to a new page, they will ping on each distinct URL they hit at least once.
The Heads Up Display and Path Aliasing Content
If your site changes URLs when a story is updated, moved into a storyline, or other section of the site, you may need to use the Alias Variable, as these can cause issues for the Heads Up Display. The Alias Variable is used to resolve these issues, which can be identified by incorrect referrer information.
Before we dive into how to use the
_sf_async_config.alias variable, let's first go over just what path aliasing does.
Think of aliasing as a list. This list has a title and content. The title is a path value, say,
/news/politics/article-name-123. That is the path value Chartbeat is receiving in pings from a piece of content. The list items are all of the URLs from which we've received a ping containing that path value. To illustrate the point:
alias = /news/politics/article-name-123 url = site.com/news/politics/article-name-123 url = site.com/article-name-123 url = site.com/news/politics/article-name-123?campaign=Facebook
These are all different URLs that lead to the exact same piece of content, and if your implementation is correct, the path value will be the same each time. These URLs should redirect to a single, primary URL, in which case path aliasing shouldn't be an issue.
You may have vanity URLs that are a bit less clunky and lead to the same content, or your site may use an infinite scroll layout, in which one story leads right to the next. These types of scenarios can cause issues for the Heads Up Display, for which path aliasing is relied upon to report clicks taking place from the homepage to another page on your site.
To implement path aliasing, simply set the
_sf_async_config.alias variable to the full URL of the link that will lead to it from the homepage, which most likely matches the primary URL. For instance, the alias variable of the example from above would be set to:
_sf_async_config.alias = "http://site.com/news/politics/article-name-123";
The Path Variable should only be used if you notice incorrect referrer data or click performance in the Heads Up Display. Please refer to Canonical Links and the Path Variable documentation for standard implementation instructions.
Chartbeat uses three first-party cookies.
_chartbeat2cookie is used to register if a user has visited the domain before and to calculate visitor frequency.
_chartbeat4cookie stores the state of the last ping when a page is unloaded and is used for accurately calculating engaged time.
_chartbeat5cookie is used by the Heads Up Display to assign traffic to the right link on the page from which someone clicked over.
_sf_async_congfig.noCookies = true;
Note: By using Chartbeat without cookies, you will be unable to see Visitor Frequency, Conversion Quality, and Return Rates.