Implementation requirements

We are looking forward to receiving the data from your website. Here's what we need from you.

PleaThe main purpose of this document is to provide information on all possible aspects of implementing smartocto scripts on clients' website/s: estimated time of arrival, the number of people involved, access to different services, and sharing valuable information.
As you probably know, smartocto consists of two components:
  • Insights script for historical statistics, AMP, FIA, and conversion tracking
  • Tentacles script for real-time tracking, headline A/B testing, Waves, and Smartify
Depending on the features covered by your contract, implementation of smartocto tracking scripts usually develops in four major stages:
  1. Insights script tracking
    1.1. Custom setup
    1.2. GTM setup
    Paywall setup
    SPA websites
    Testing the Insights script
  2. Tentacles & Real timeTentacles (real-time) script tracking
    2.1 Tentacles A/B-testing - script implementation
    2.2.1 Tentacles Photo A/B-testing - requirements
    2.2.2 Tentacles Photo A/B-testing - flickering
    Real time - Feed
    Real time - Newsletter
    Real time - Facebook
    Real time - LinkedIn
    Real time - Push notifications
    Real time - YouTube
    Real time - Video analytics
  3. AMP tracking
  4. FIA tracking
  5. Conversion script tracking
  6. Mobile app tracking

Stage 1 - Insights script implementation

Depending on the complexity and availability, this stage may be completed in a couple of hours, but it can also extend for a couple of days. Due to the nature of the Insights backend, the first results can be seen the next day, when all the data acquired during 24 hour period have been processed.
The implementation of the smartocto Insights script can be done in two ways:

1.1. Custom setup

It is usually done by in-house or third-party web developers by adding the script to the article template page on your CMS.
Please refer to this page for more details.

We will provide the four-digit id property for the Insights dashboard as soon as we create the account.
If you want to track AMP and FIA traffic please follow these instructions:

1.2. Google Tag Manager setup

Please refer to this page for more details.
If you have or plan to implement the GTM script, you can set the custom HTML tag with all required variables and a trigger to fire the Insights script.
Alternatively, you can grant Edit permissions to our Support team and we can set it up for you, but it has to be planned at least two weeks ahead since we're working by two-week sprints.
We will provide the list of personal email addresses if you choose this approach.
After we set the required tags, triggers, and variables in the GTM container, you will have to review and publish the changes. We don't want to publish anything even if we have Administrator permissions.

Paywall setup

If you have a paywall on your site, please create a temporary (one-month) account so we could access all content and check how it works, or test the implementation once it's done.
Please use this email for that purpose: supportmail@smartocto.com
Please refer to this page for information on how to properly adjust the Insights script in accordance with your paywall.

SPA and Infinite scroll websites

If your website is a single-page application (SPA), or it uses infinite scroll to load more than one article on a single page, please use these instructions with examples.

Testing the Insights script

After the setup has been done, here's how you can test the implemented script.

Stage 2 - Tentacles implementation

2.1 Tentacles script implementation

The second phase covers the implementation of the smartocto Real Time script, also called Tentacles.
Due to the complexity and availability of our staff, this stage requires a few days, since we have to configure a series of crawlers that will get the data from each website. We always do it in our staging environment at first, and after at least one day of testing, we deploy it on production.
Please refer to this page for more details.
It's also very important to emphasize if your website uses a single-page application (SPA).
From your end, you will just have to implement two lines of JavaScript code:
<script>window.tentacles = {apiToken:'API-TOKEN'};</script>
<script src="https://tentacles.smartocto.com/ten/tentacle.js"></script>

It can also be implemented using the GTM container.

Our Support team will provide the 32-character API_TOKEN which is unique for each website.

2.2.1 Tentacles Photo A/B-testing - requirements

In order to be able to perform an A/B-test for images on your overviewpages, you have to make sure that the image you want to test is included in the link-element (<a>).
Example that will work since the image-element (<img src="https://www.domain.org/image.jpg" />) is within the link-element (<a>):
<article>
<a href="https://www.yourdomain.org/path/to/story/">
<img src="https://www.yourdomain.org/path/to/teaser-image.jpg" />
<h1>John builds largest replica of an octopus in LEGO</h1>
</a>
</article>
Example that won't work since the headline is outside the link-element:
<article>
<img src="https://www.yourdomain.org/path/to/teaser-image.jpg" />
<a href="https://www.yourdomain.org/path/to/story/">
<h1>John builds largest replica of an octopus in LEGO</h1>
</a>

</article>
In the example above, the image is outside the link-element, so within Tentacles it won't be able to select and replace the image. Tentacles searches and replaces only images inside the link-element.

We support current standards and best practices of displaying images in modern web browsers. Although we will always be working to expand the methods of image display we support, the sheer breadth of variables prevents us from being compatible with every method.

Image paths

In order to be able to A/B-test a photo, the image-tags need to contain the full location of the image(s):

<!-- Unsupported -->
<img src="/relative/path/to/teaser-image.jpg">

<!-- Supported -->
<img src="https://www.yourdomain.org/path/to/teaser-image.jpg">

Supported image formats

We support testing on responsive <picture> elements with <source> and <img> children with srcset attributes.

Example

<picture>
    <div class="thumb-logo"></div>
    <source srcset="https://smartocto.com/images/large.jpg, https://smartocto.com/images/large-retina.jpg 2x" media="(min-width: 1200px)">
    <source srcset="https://smartocto.com/images/medium.jpg, https://smartocto.com/images/medium-retina.jpg 2x" media="(min-width: 976px)">
    <source srcset="https://smartocto.com/images/small.jpg, https://smartocto.com/images/small-retina.jpg 2x" media="(min-width: 576px)">
    <img srcset="https://smartocto.com/images/mobile.jpg" alt="A picture">
</picture>

We support testing on responsive <img> elements with src and srcset attributes.

Example:

<img src="https://smartocto.com/images/image.jpg" 
srcset="https://smartocto.com/images/image1x.jpg 1x,
https://smartocto.com/images/image2x.jpg 2x">

We support testing on non-responsive <img> elements with a single src attribute defined on page load.

Example: 

<img src="https://smartocto.com/images/image.jpg">

We support testing on images with lazy load source or source-set attributes for any of the above formats (i.e. data-src or any other attribute names that your website uses for this purpose).

Example:

<img data-src="https://smartocto.com/images/image.jpg"> 

<img data-img-sm="https://smartocto.com/images/image1.jpg"
data-img-lg="https://smartocto.com/images/image2.jpg">

Unsupported image formats

We do not support testing for <img> elements that are not descendants of an <a> tag (anchor element). Tests can only be initiated on <img> elements that are descendants of an anchor tag linking to the target article.

Example:

<!-- Unsupported -->
<article>
<img src="https://www.yourdomain.org/path/to/teaser-image.jpg">
<a href="test.com/article1">
<h3>Headline Text</h3>
<a>
</article> 


<!-- Supported -->
<article>
<a href="test.com/article1">
<img src="https://www.yourdomain.org/path/to/teaser-image.jpg">
</a>
<a href="test.com/article1">
<h3>Headline Text</h3>
<a>
</article>


<!-- Also supported -->
<article>
<a href="test.com/article1">
<img src="https://www.yourdomain.org/path/to/teaser-image.jpg">
<h3>Headline Text</h3>
<a>
</article>

We do not support testing for <picture> tags that do not properly have an <img> element as a child.

Example:

<picture>
<div class="background-css-image-here"></div>
</picture>

We do not support testing images that use the background-image CSS property.

Example:

<div style="background-image: url('https://www.yourdomain.org/path/to/teaser-image.jpg');"></div>

We do not support testing on responsive <img> elements that have their src attributes dynamically altered by JavaScript.

  • This can usually be determined by inspecting an <img> element at mobile and desktop breakpoints: if the srcs differ at each breakpoint, JavaScript is dynamically altering the src.

  • smartocto code does not have a way to determine whether this is or is not the case as the markup is indistinguishable from supported elements. In the rare case that your site uses this as well as supported formats, use caution when making a test.

We do not support testing on <picture> or <img> elements that are injected dynamically into the page by JavaScript dependent on user action.

Partial homepage compatibility

If your website uses both supported and unsupported formats for different positions on the homepage, the test will only run successfully on the supported formats. It will still be possible to run headline tests on positions with unsupported image formats. It is advisable for clients to do their own inspection of the page layouts to confirm if a image test can run in each section.

Access to images

To make it possible for the script to track the dimensions (width and height) and to display it in the form, the script on tentacles.smartocto.com and the archive-page must be allowed to read the images. To do so, make sure the CORS-headers are allowing *.smartocto.com.

2.2.2 Tentacles Photo A/B-testing - flickering

When incorporating flicker handling into your website, make sure to insert the following code into the <head> section of your site's HTML. This code should be positioned among the initial scripts loaded within your <head> tags.

window.tentacles = { 
apiToken: '###########',
...,
flickerHandling: true
};

Real time - setup

Real-time setup requires more work on our end because we have to configure the set of crawlers that will scrape the data from your articles.
For this purpose, we will need the following:

Real time - Feed

We need a link to the RSS feed in XML or JSON format to get the data about the recently published articles.

Real time - Newsletter

If you have one or more newsletters, please subscribe us with the following email: 

Real time - Facebook

Please add our account with the Analyst role to the Facebook page, or all pages you are using to distribute the content.
Our dedicated email for this purpose is facebook@smartocto.com
Alternatively, you can add it by the name Slimme Leeuw with the blue lion avatar:
Slimme Leeuw
If you are using URL shorteners, please provide which one you are using.

Real time - LinkedIn

The administrator of your LinkedIn page must make a connection to the smartocto API connector LinkedIn page: www.linkedin.com/in/smartocto-api-connector-610896100/

Please make sure you add our API connector profile with your company account, not your personal LinkedIn profile.

You need to send a request to make a connection as you do to other people.
Once the smartocto page administrator accepts the connection, please follow the next steps:
  • go to the Admin area of ​​the company page:
  • go to the part where you can add administrators to your page.
  • when adding the user, type 'SmartOcto' and add this user.
  • save the changes and the connection is made.
  • smartocto will follow up on the connection
  • smartocto Support team will configure the crawler which will get the data from the client's LinkedIn page
  • after that, you will start seeing the LinkedIn badges in the real-time dashboard for all stories that were published on LinkedIn from the moment the crawler becomes active

Please note that the post you publish on LinkedIn must contain the URL of the article from your website where our tracker is implemented.

Otherwise, the crawlers cannot detect any activity from this network.

 

Real time - Push notifications

If you're using push notifications in your browser or your mobile applications, our real-time dashboard can show the push-message icon in the story graph at the exact time it was pushed:
To achieve that, you have to provide that information in the existing RSS feed (Example 1) or create a dedicated feed only for pushed stories. It can be in XML (Example 2) or JSON format (Example 3).
Example 1: 
<item>
<title>Title of the story 123</title>
  <link>https://yourdomain.com/story-123</link>
  <pubDate>Wed, 02 Nov 2022 13:31:00 +0100</pubDate>
</item>
<item>
  <title>Title of the story 456</title>
<link>https://yourdomain.com/story-456</link>
<pubDate>Wed, 02 Nov 2022 17:42:00 +0100</pubDate>
<pushed>true</pushed>
</item>
<item>
<title>Title of the story 789</title>
<link>https://yourdomain.com/story-789</link>
<pubDate>Thu, 03 Nov 2022 12:34:56 +0100</pubDate>
</item>

Example 2:

<item>
<title>Title of the story 123</title>
  <link>https://yourdomain.com/story-123</link>
<pubDate>Wed, 02 Nov 2022 13:31:00 +0100</pubDate>
</item>
<item>
<title>Title of the story 456</title>
<link>https://yourdomain.com/story-456</link>
<pubDate>Wed, 02 Nov 2022 17:42:00 +0100</pubDate>
</item>

Example 3:

{
  "items": [
    {
    "title": "Title of the story 123",
    "link": "https://yourdomain.com/story-123",
    "pubDate": "Wed, 02 Nov 2022 13:31:00 +0100"
    },
    {
    "title": "Title of the story 456",
    "link": "https://yourdomain.com/story-456",
    "pubDate": "Wed, 02 Nov 2022 17:42:00 +0100"
  },
...
  ]
}

 

YouTube

We will need access to the associated YouTube channels.
Please add cleverlionseu@gmail.com to each channel as a Viewer.

Custom video tracking

Please follow this guide for implementing custom video tracking.

 

AMP tracking

If you have significant traffic from Google's Accelerated Mobile Pages and you would like to include it in the overall statistics, please follow these guidelines for AMP tracking.

 

FIA tracking

There is an option to follow the traffic from Facebook Instant Articles.

Please follow this page to have it implemented.

 

Stage 3 - Conversion script implementation

Please refer to this page for more details.

You have to define which conversions you would like to track.

For example, you can track newsletter subscriptions or the number of purchased subscriptions from premium articles.

This phase can be completed in a day, but since it's backed by the Insights tracker, the first results can be seen after several hours or the next day.

 

Stage 4 - Mobile app tracking

This is by far the most complex part and we always suggest doing it at the end of the implementation process, when your developers are already familiar with the tracking, because they have to implement the tracking from your mobile apps in the way to send a predefined set of parameters to our ingestion endpoint.

Depending on your app release cycle, it may require a couple of days, or even weeks to get it implemented and tested.

Please follow these guidelines for more details: Mobile app tracking


In case you have any questions or doubts regarding any part of the implementation, please contact our Support team. They will surely have to provide some details specified for each website, so feel free to get in touch with them. It won't hurt, we promise. OK, maybe just a little headache, in the worst-case scenario 🤕 😉