Smartocto Insights Script Setup

Instructions for the insights script implementation

Quick links:

• url
• id
• postid
• maincontent
• pubdate
• title
• authors
• sections
• tags
• user-needs tags
• page_type
• access_level
• article_type
• reader_type
• social
• channel

Smartocto Insights script (former Content Insights) is a component used to track the historical data (at least 24 hours old), while the Tentacle script is used for real-time tracking and A-B testing.

Smartocto Insights tracking code is a piece of JavaScript code that will send information about your web pages and reader behaviors to our servers.

Detailed and customized instructions are sent to each client once they agree to test the script on their site.
The Insights tracking script is asynchronous and it will not affect the speed of the website.

Before you start

• Make sure that your CMS does not load the tracking code in preview (draft) mode or on any temporary pages.
• A proven best practice is to omit our code when staff members are logged in. Be careful not to omit the code from all logged-in users if you have a subscription system or any other option where you allow your readers to register on your website.
• If you have a staging/test server please let us know and we'll assist you.
• The basic principle of the JavaScript tracking code is to search the page for the global _ain object and to send the information from its properties to the ingestion endpoint.
  You may find more information on How Insights tracking works page.
• Setting up a tracking code means making sure that the _ain object is populated with the correct metadata about the visited page.
• For SPA websites, please read the article about the SPA setup instructions.
• If you're also implementing the Tentacles (Real-time) tracking script, the specified _ain object may serve as a data layer for the real-time crawler as explained on this page.

Code snippet

This is an example of an empty tracking code that should load on all pages.

<script type="text/javascript">
/* CONFIGURATION START */
window._ain = {
  id: "DOMAIN_ID",
  page_type: ""
  postid: "",
  maincontent: "",
  title: "",
  pubdate: "",
  authors: "",
  sections: "",
  tags: "",
  access_level: "",
  article_type: "",
  reader_type: ""
};
/* CONFIGURATION END */
(function (d, s) {
  var sf = d.createElement(s);
  sf.type = 'text/javascript';
  sf.async = true;
  sf.src = (('https:' == d.location.protocol)
    ? 'https://d7d3cf2e81d293050033-3dfc0615b0fd7b49143049256703bfce.ssl.cf1.rackcdn.com'
    : 'http://t.contentinsights.com') + '/stf.js';
  var t = d.getElementsByTagName(s)[0];
  t.parentNode.insertBefore(sf, t);
})(document, 'script');
</script>

You can set this up however you like. It can be put directly on the page, it can be part of some JavaScript file that you already have or it can be set through Google Tag Manager.

Parameters

url (optional)
In most cases, sites use canonical URLs so you don’t have to specify this parameter, the tracker will add it automatically.

<link rel="canonical" href="https://contentinsights.com/blog/changing-the-way-we-approach-editorial-analytics/" />

If your site doesn’t have canonical links or og:url parameters, please specify it manually.
It needs to be a full URL, with the domain, like this:

url: "https://contentinsights.com/blog/changing-the-way-we-approach-editorial-analytics/",

It should be a unique, canonical link to the article.
Having variations in the URL of the same article can cause problems in calculations later.

id (required)

The DOMAIN_ID is a 4-digit number automatically created by the Insights application after our support team registers a new dashboard.
You can always see it in the application URL, it's "1234" in this example:

https://insights.smartocto.com/1234/overview

postid (required)

Post ID is a unique identification of the article. We will combine all the statistics for the articles with the same postid.
It doesn’t need to be numerical. You can use article ID from the CMS, slug, even the whole URL.

For example, WordPress sites have a shortlink tag with post ID:

<link rel='shortlink' href='https://contentinsights.com/blog/?p=123456' />

In this case, postid parameters should have this value:

postid: "123456"

page_type dependency:

If you implement the Insights script on landing pages, those pages usually don't have the unique ID as articles do. You may use any string value that will be unique for the specified page.

Examples: "home", "sport", "search-results", "404-page" and so on.

maincontent (required)

In Smarocto Insights, we have a metric called Read depth.

To calculate how far through an article a reader got, we look where the content is, calculate its height, count the number of words, and then we measure the time and how far the user scrolled while reading the article.

All these metrics are then put in the formula that tells us how much of the content is being read by the user for the given time.

To know where the content is so we can count the words and calculate the height and the position relative to the window, we need to know exactly what elements of the page contain the article's content.

To identify those elements, you must specify CSS selectors of those elements in the maincontent parameter.

Example:

maincontent: "#article-title, .article-body"

page_type dependency:

If you implement the Insights script on landing pages, you may use "body" as a CSS selector.

pubdate (required)

This is the date when the article is published. It has to be in ISO 8601 format with the correct time zone offset.

For example, if your website is Toronto-based, the time zone is UTC-4 (EDT).

Let's say the article was published on June 14th at 14:30 local time.

The correct pubdate format is this:

pubdate: "2023-06-14T14:30:00-04:00"

Z-format is also acceptable, but you have to specify it correctly as well.

For the same example, it would be like this:

pubdate: "2023-06-14T18:30:00Z"

page_type dependency:

If you implement the Insights script on landing pages, you may use some custom date, like the day you implemented the script or the first day of the current year.

If you don't specify it, the system will assign the default date "1970-01-01".

title (recommended)

This is a simple article title.

You can use the value from the <title> or the content from the <meta property="og:title"> tag, but you should remove the unnecessary characters if they are present.

If there are quotes in the title they need to be escaped.

title: "Did you watch new "Star Wars" movie?"

If you don't specify the title, the tracker will use the document.title value.

authors (recommended)

This is the author's name or comma-separated list of authors.

If authors sign articles differently each time (e.g. John Smith, J. Smith, J.S.) then it would be best if we find a way to always send us just one version. There is an option in the system to manually group them afterward, but it’s best if the data is clean from the start.

authors: "John Smith"

When multiple authors contributed to the article, it’s important that you send us authors as a comma-separated string. You cannot use a different separator.

Example:

authors: "Jack Black, Jane White"

Our system can work without authors, but valuable insights will be lost.

sections (recommended)

Sections are the primary way of organizing content in smartocto Insights so we highly recommend that you specify this value.

We use sections as containers for comparing articles with each other. This parameter should be filled with a single section, sections with the hierarchy, or multiple sections as comma-separated strings.

Sections in a hierarchy usually reflect the site structure, for example:

• News
• Sports
• Life
• Fashion
• Entertainment

Sections can be grouped (nested) with the > separator.

For example, if an article belongs to the section Football, which is part of the Sport section, you can send us this value:

sections: "Sport>Football"

If the article contains embedded video and, for example, you have a Video section, you can send us this value:

sections: "Sport>Football, Video"

page_type dependency:

If you implement the Insights script on landing pages, you may use some custom value for all landing pages, like "Landing" or something similar, but not applicable to any section that will be assigned to articles.

sections: "Landing"

 

tags (recommended)

Values from the tags parameter are called Topics in Smartocto Insights. Just like the sections, it should be a comma-separated string of topics.

tags: "EXIT Festival, Music, Concerts"

user-needs tags (optional)

In case you're using or you plan to use user-needs tags, they should be sent within the tags property explained above. One article should have only one user-needs tag.

Example:

tags: "EXIT Festival, Music, Concerts, Inspire me"

 

page_type (optional)

Accepted values: "article" and "landing".

This property enables tracking of landing pages.

The end user will be able to see the total number of pageviews for the entire website.

If not specified, the tracker will send "article" as a default value.

If you implement the tracker to load on all pages, you should make sure to send "landing" on all non-article pages (home, category, search, tag, author, 404, and so on).

page_type: "landing"

Please pay attention to other properties as their values will probably depend on the specified page_type: 

• postid
• pubdate
• sections
• maincontent

If your website offers premium content behind the paywall, then access_level and reader_type are important for your editors because they will enable filtering by these values in the Insights dashboard.

access_level (optional)

Represents the article access level type. The value can be one of the following standardized options: “free”, “preview”, “paid”

access_level: "free"

Please read the Paywall setup for further explanation.

reader_type (optional)

Represents the type of visitor/reader currently browsing your site.
The value can be one of the following standardized options: "anonymous", "registered", "subscribed"

reader_type: "anonymous"

Use "anonymous" for all guest visitors, "registered" for registered or logged-in visitors and "subscribed" for subscribed (premium) visitors.

Please read the Paywall setup for further explanation.

article_type (legacy, optional)

This represents the type of article as specified by publisher (e.g. "news", "gallery", "blog", "essay").

article_type: "news"

 

social (optional)

Provides an option to explicitly include or exclude the number of reactions from social networks for the visited article.

At this moment, three properties are supported in the Insights backend processing: Facebook, LinkedIn, and Pinterest.

social: {
  fb_count: 123,
  ln_count: 456,
  pn_count: 789
}

This parameter should be filled with the latest values for each article visit. 

The existence of a parameter for each network will override any other way of collecting data. Our system will always use the value set in the tracking code. This allows for the explicit exclusion of one or more networks by setting the appropriate value to "0" always, for each visit. The example below means you don't care about LinkedIn and Pinterest and you only want to send the data from Facebook:

social: {
  fb_count: 123,
  ln_count: 0,
  pn_count: 0
}

You don't need to use all the parameters. This is the example of the full tracking code where you send us information about Facebook data while allowing our system to collect Pinterest data on its own. Keep in mind that the value for fb_count should be updated with each visit:

<script type="text/javascript">
/* CONFIGURATION START */
var _ain = {
  id: "DOMAIN_ID",
  postid: "",
  maincontent: "",
  title: "",
  pubdate: "",
  authors: "",
  sections: "",
  tags: "",
  access_level: "",
  article_type: "",
  reader_type: "",
  social: {
    fb_count: 458
  }
};
/* CONFIGURATION END */
(function (d, s) {
  var sf = d.createElement(s);
  sf.type = 'text/javascript';
  sf.async = true;
  sf.src = (('https:' == d.location.protocol)
    ? 'https://d7d3cf2e81d293050033-3dfc0615b0fd7b49143049256703bfce.ssl.cf1.rackcdn.com'
    : 'http://t.contentinsights.com') + '/stf.js';
  var t = d.getElementsByTagName(s)[0];
  t.parentNode.insertBefore(sf, t);
})(document, 'script');
</script>

If you're using both Insights and Real-time, we can get the Facebook statistics via a Real-time crawler. In that case, it's best to explicitly set all values to zero:

social: {
  fb_count: 0,
  ln_count: 0,
  pn_count: 0
}

Please check this page to see how we get the data from Facebook.

channel (optional)

By default, all requests sent by the JavaScript tracker have an empty string value for this property.
However, if you have some kind of a wrapper app, or you would like to send requests from different sources, you may explicitly specify a channel property with one of the following values: "web", "app", "android", "ios", or "amp".

---

If you still have some questions or concerns please contact our Support Team via email: support@smartocto.com