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

Advanced Implementations

Native Mobile SDK

Chartbeat’s Mobile SDK is an integration meant to use Chartbeat analytics in your native iOS or Android app.

If instead you have a web app, visit this page for further instructions: Mobile Web App

Once a Chartbeat Dashboard is integrated with either SDK, a new field will appear under the Distribution section on the left-hand side of the Dashboard, called 'App'. This will display the percentage of concurrents that are engaging with your native app content.

Additionally, by selecting the app distribution channel you'll filter the entire Dashboard to only show you the concurrents who are engaging with your app content-as well as all the Chartbeat metrics specific to that group.


If you're interested in integrating Chartbeat into your native app to track real-time data on those readers, first be sure you’ve completed these prerequisites before moving forward:

Account ID

  1. You must be a current Chartbeat Publishing client with Chartbeat code already successfully implemented on your site.
  2. You must know your account ID number (also known as the "UID"). If you don't know your UID, head over to and enter the domain you're tracking into the field and select 'generate code'. In the generated code block, your UID will be auto-filled in line 4.


In general, the domain variable will match the `_sf_async_config.domain` from your Chartbeat publishing setup; this will send all of your app traffic to the same dashboard as your other traffic. In tracking each view of the app, you have two options:

  1. We recommend that you set the domain setting to match the _sf_async_config.domain setting from your Chartbeat Publishing (website) setup; this will send all of your native app traffic data to the same dashboard as your website traffic. This is normally the actual domain of your website (without any "www." at the front of it). For example, this might be something like "".


  1. If you don't want you native app traffic to roll up with your website traffic, you can set the domain setting in the SDK to some subdomain of your website top-level domain (this does not have to actually exist as a website, but you should own the top-level domain to ensure you choose a globally unique name). For instance, you may choose
  2. Also, if you are seeing the bundle ID as the domain in your requests, you can use the setSubdomain function to override that for the subdomain you're looking to use.

Views vs. Pages

In your mobile app you'll be tracking "views" (screens of content) instead of how we track "pages" on the web. In tracking each view of the app, you have two options:

  1. If you want your native app traffic to roll up with the traffic from the corresponding page on your website, you will need to set the viewID to the same string path that the corresponding page reports to from your website. For instance, if you implemented canonical URL’s for your website, your article may report with the path set to /sports/what-defines-me-ryan-lochte. For native app traffic for that article to rollup correctly in the dashboard with the website traffic, when you call trackView in the mobile SDK, you would set the viewID parameter to /sports/what-defines-me-ryan-lochte so it matches.
  2. If instead you’d like to track your app traffic as separate "pages" from your web traffic in your dashboard, you can set the viewID to some identifier which will not collide with any path reported by your website. For instance, you might want to set the viewID to something like /nativeapp/sports/what-defines-me-ryan-lochte — the /nativeapp prefix there will keep this traffic separate from the website page for the same article.

If a view (any "place" the user can be in your app) doesn't correspond to a page on your website, you can still track the user on that screen. Just choose an identifier (as in the second scenario above) that will not collide with any page path from your website, and the traffic will be tracked to a separate "page" in your dashboard. For instance, you could track users in the "table of contents" screen of your app to a viewID like /nativeapp/main-toc.

Our general recommendation is to track users through all views/screens of your app. After initializing the tracker, you just call trackView (preceded by setSections and setAuthors) each time the user navigates to a new screen.

Sections and Authors

In addition to viewID and title, you can set section and author data (an array of strings for each) for each view you track. To do so, call setSections and setAuthors immediately before calling trackView each time. If you are doing this, it's important to always do this, as any sections and authors you set will stay set until you set a different set of values, which may be unexpected as you track multiple views. For instance, in the above Example Scenario, each time we said "call trackView," you would actually call setAuthors, then setSections, then trackView.


Installing the library with CocoaPods

The easiest way to get Chartbeat into your iOS project is to use CocoaPods.

  1. Install CocoaPods using gem install cocoapods
  2. If this is your first time using CocoaPods, run pod setup to create a local CocoaPods spec mirror.
  3. Create a file in your Xcode project called Podfile and add the following line: pod 'Chartbeat'
  4. Run pod install in your Xcode project directory. CocoaPods should download and install the Chartbeat library, and create a new Xcode workspace. Open up this workspace in Xcode.

You can also get the library by downloading the latest version from Github from the link below and copying it into your project.


The below topics refer to the traditional javascript implementation

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.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
  2. _sf_async_config.type = 'some kind of type';
  3. 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.
  4. <amp-analytics type="chartbeat">
        <script type="application/json">
                "vars": {
                    "uid": "12345",
                    "domain": "",
                    "contentType": "some kind of type"
  5. _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.
  6. _sf_async_config.mobileApp = true;
  7. _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.
  8. _sf_async_config.sponsorName = 'Chartbeat_Awareness_Campaign_Fall_2015'
  9. 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
  10. = 'us/business/technology';
  11. _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;

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.