Get up and running with Chartbeat—full implementation guides for all our products.

Advanced Implementations

Additional Config Variables

In addition to the standard _sf_async_config variables documented in the Getting Started Guide, there are a few additional config variables that you may use to better collect and report on your data.

  1. _sf_async_config.mobileApp: A way to specify that a page is part of a web app, instead of a native app. Note: Only accepts boolean value.
  2. _sf_async_config.mobileApp = true;
  3. _sf_async_config.type: "Content Type" lets you group pages on your site that are returned in your report depending on how they're tagged on your site such as gallery or article. Note: this value only appears in the "Content Type" group in Advanced Queries
  4. _sf_async_config.type = 'some kind of type';
  5. contentType: A unique version of the type variable used exclusively in Chartbeat's AMP integration that is set in the vars dictionary. Note: this value only appears in the "Content Type" group in Advanced Queries.
  6. <amp-analytics type="chartbeat">
        <script type="application/json">
                "vars": {
                    "uid": "12345",
                    "domain": "",
                    "contentType": "some kind of type"
  7. canonicalPath: A version of the path variable used exclusively in Chartbeat's AMP integration that is set in the vars dictionary. Note: This variable should only be included in your Chartbeat markup to override the canonical link set within your AMP markup code.
  8. <amp-analytics type="chartbeat">
            <script type="application/json">
                "vars": {
                    "uid": "12345",
                    "domain": "",
                    "canonicalPath": ""
  9. _sf_async_config.sponsorName: You should treat the sponsorName value as a unique campaign ID that the sponsored piece of content belongs to, rather than simply defining which brand sponsored the content.
  10. _sf_async_config.sponsorName = 'Chartbeat_Awareness_Campaign_Fall_2015'
  11. Chartbeat uses zones as a way of understanding how a given ad slot/position performs on different parts of your site. The zone values that you use should match how you package and sell ad units across different sections and verticals
  12. = 'us/business/technology';
  13. _sf_async_config.videoPageGroups: Set to true to pass a page's section and author data to the Video Dashboard, as the section and author values for a video on that page.
    _sf_async_config.videoPageGroups = true;
  14. _sf_async_config.virtualReferrer: Allows you to set the referring domain for internal traffic, overwriting the default value we collect through document.referrer.
  15. _sf_async_config.virtualReferrer = '';
    _sf_async_config.virtualReferrer = '';

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 =
url =
url =

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

Important Notes:

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.

Because of the <meta>referrer tag, a full implementation requires that you set path aliases in _sf_async_config, as described above. If you are setting any of the following in your markup, you will need to implement aliasing for the HUD and other products to work correctly.

<meta name="referrer" content="origin">
<meta name="referrer" content="origin-when-cross-origin">
<meta name="referrer" content="none-when-downgrade">
<meta name="referrer" content="none">

Custom Metrics

Creating a Custom Metric

To create a Custom Metric you'll need to let us know the key, the type, and the label(s) for your metric(s). Simply email to get started. It's important to know that custom metrics are only available via our real-time API and are not present in the Chartbeat Publishing Dashboard. The explanations for these values are as follows:

  • Label: A human-readable name for this metric, e.g. user_account_type or product_name. The label of a metric may contain letters (A-Z, a-z) and underscores. This is used a label for the graphs that will appear on your dashboard.
  • Key: The key that will be reported to our servers. For example, if you are tracking user_account_type, you might use the key _acct or _utype. The shorter the better, but for a key to be reported it must begin with an underscore.
  • Type: What kind of metric you are tracking and any metadata associated with the given type. The types are:
    1. Number: A floating point, signed number. Use for reporting numerical stats, such as average, sum, min, max, etc. Optionally, you can define:
      • Buckets used for creating a histogram. For example, [1-10, 11-50, 51-100, 100+].
      • Clamping behavior. For example, a value over the Max would report as the maximum value.
      • Min Value
      • Max Value
    2. String: Any arbitrary string, e.g. "awesome" or "pelle". No interpretation of it is made. Reports are of number of visitors with a value, top 5 values, and number of unique values.
    3. Enum: Data is interpreted as one of the given enum values. Multiple strings can match one enum value (eg: "female", "f", "woman", "lady", etc all get mapped to one index). The report is an un-labeled array of counts for each enum-index, eg: [4, 0, 23, 3].

Reporting a Custom Metric

Once your Custom Metric has been created, you'll need to handle the implementation on your site. To report a Metric to Chartbeat, you'll need to add it to the _cbq object by providing the key you emailed Chartbeat about, and a value:

    var _cbq = window._cbq || [];
    _cbq.push(['_usr', 'pro']); // Good!
    _cbq.push(['name', 'Something or other']); // Bad! Should be _name

The above code will tell chartbeat.js to add &_usr=pro to all pings. Note that since name does not begin with an underscore, it will be ignored. You can update a Metric at any time during a user's interactions without waiting for them to reload the page or travel to a new page by merely calling _cbq.push again with the same key, and a new value. The change will be reported with the next ping.

Advanced Custom Metrics

You can use the same key for multiple metrics. For example, if you report a number under as_money, you could have two or different labels:

  • money_big_buckets with a histogram of [1000, 2000, 3000, 4000, 5000]
  • money_bigger_buckets with a histogram of [1000, 5000, 10000, 15000, 20000]

Both of these could be computed based off of the _money key reported from your site.

Custom Scroll Elements

Some sites have designs where the entire page does not scroll, but instead there is some element on the page — let’s call this a "scrollable div" (although it doesn’t necessarily have to be a <div> element). This element wraps most of the page content, and has its own scrollbars to scroll the content. You can mostly identify these scrollable divs by your CSS – there is most likely a "overflow" (or "overflow-y") CSS property set "auto" or "scroll."

On designs like this, unless you indicate that your site has a scrollable <div> that we should use to measure scroll depth, the scroll depth will always be reported as zero since the page itself never scrolls. To tell us about the scrollable <div>, you’ll need to do two things:

  1. Set _sf_async_config.scrollElement = true;
  2. Set a special marker attribute on your scrollable div so that we can find it. The marker attribute is named "data-cb-scroll-element" and and the value can just be set "1". it’s the presence of the attribute that matters. This should end up looking like this
  3. <div class="unique-div-class" data-cb-scroll-element="1">

Here are some ways to get in touch.