# Customize Tracking Settings ## Overview Our [**JavaScript tag**](https://docs.chartbeat.com/cbp/tracking/our-javascript#our-javascript-tracking-snippet) 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**](#sections-and-authors) 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](http://www).' prepended. | Field Name | Value Type | Default Value | Max Length | Example Value | | ---------- | ---------- | ------------- | ---------- | ------------- | | `domain` | text | *None* | *None* | `mysite.com` | Example usage: ```javascript _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**](mailto:support@chartbeat.com). | Field Name | Value Type | Default Value | Max Length | Example Value | | ---------- | ---------- | ------------- | ---------- | ------------- | | `uid` | integer | *None* | *None* | `12345` | Example usage: ```javascript _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**](#custom-path) 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 NameValue TypeDefault ValueMax LengthExample Value
Field NameValue TypeDefault ValueMax LengthExample Value
sectionstextNone10 sections max per page, 63 characters per sectionnews,sports
authorstextNone10 authors max per pagee, 63 characters per authorJane Doe
Example usage: ```javascript _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. ```javascript _sf_async_config.sections = 'News,Sports,Local'; _sf_async_config.authors = 'Megan Summers,Kevin Smith'; ``` {% hint style="warning" %} **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. {% endhint %} 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 `` 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: ```javascript _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**](https://support.google.com/webmasters/answer/139066?hl=en\&rd=1) 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. {% hint style="success" %} **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**](https://support.google.com/webmasters/answer/139066?hl=en\&rd=1). {% endhint %} 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. {% hint style="success" %} **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. {% endhint %} If you are unable or prefer to not use canonical links for your website, you may alternatively use our [**custom path variable**](#custom-path) 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**](#canonical-page-path) 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: ```javascript _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 `` tags in your page HTML). | Field Name | Value Type | Default Value | Max Length | Example Value | | ---------- | ---------- | ------------- | -------------- | ------------- | | `title` | text | *None* | 100 characters | `My Title` | Example usage: ```javascript _sf_async_config.title = 'Live Updates: 2020 Election'; ``` ### Content type Use this variable **only** if your team utilizes Advanced Queries or Data Lab 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: ```javascript _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. {% hint style="warning" %} **Important:** Chartbeat tracking for mobile apps is an add-on feature. Contact your Chartbeat Customer Success representative or [**support@chartbeat.com**](mailto:support@chartbeat.com) to learn more. {% endhint %} | Field Name | Value Type | Default Value | Max Length | Example Value | | ----------- | ---------- | ------------- | ---------- | ------------- | | `mobileApp` | boolean | `false` | *None* | `true` | Example usage: ```javascript _sf_async_config.mobileApp = true; ``` ### 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**](https://docs.chartbeat.com/cbp/tracking/alternative-integrations-web#implement-cookieless-tracking). | Field Name | Value Type | Default Value | Max Length | Example Value | | ----------- | ---------- | ------------- | ---------- | ------------- | | `noCookies` | text | `false` | *None* | `true` | Example usage: ```javascript _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: ```javascript _sf_async_config.alias = 'mysite.com/article-xyz.html'; ``` ### 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: ```javascript _sf_async_config.sponsorName = 'Spotify'; ``` ### 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: ```javascript _sf_async_config.scrollElement = true; ``` ```markup <div data-cb-scroll-element="1"> ``` ### 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**](https://help.chartbeat.com/hc/en-us/articles/4404408150171-August-12-2021-Change-in-scope-of-Chartbeat-s-first-party-cookies-on-customer-websites) 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: ```javascript _sf_async_config.cookieDomain = 'subdomain.mysite.com'; ``` ### 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: ```javascript _sf_async_config.pingServer = 'pong.chartbeat.net'; ``` ## Next steps Use the above guide to review your site's [**canonical URL**](#page-ids-canonical-urls-vs-custom-paths) implementation, and identify how best to configure our [**section and author**](#page-sections-and-authors) variables for your website. For sites that make use of [**virtual page change**](https://docs.chartbeat.com/cbp/tracking/standard-websites/single-page-apps) (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**](https://docs.chartbeat.com/cbp/tracking/standard-websites/subscriber-engagement) article or [**alternative implementations**](https://docs.chartbeat.com/cbp/tracking/standard-websites/alternative-integrations-web) article if your site does not allow users to subscribe or create user profiles. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.chartbeat.com/cbp/tracking/standard-websites/configuration-variables.md?ask=<question> ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.