Tagging Instructions

Tagging Information


Version

1.9

Datum

21.02.2018

Author

Kantar Media Audiences

VersionChangeDateChanged by
1.0Initial22.02.2008Frank Kammann
1.1

Specifications expanded
Translation into English

03.03.2008
16.09.2009

Frank Kammann
Oliver Pischke

1.2

Change (setup)
Review

28.09.2009
09.04.2010

Oliver Pischke
Ralf Cornehl

1.2.1

Adding asynchronous Integration
Review

18.05.2011
18.05.2011

Christopher Wirtz
Frank Kammann

1.3

Multi Page Tagging
Change (setup)

13.12.2011

Christopher Wirtz
Ralf Cornehl

1.3.1Variables expanded16.05.2012Anja Herting
1.4

Review
Example for shortened Form
Content Path expanded
SSL Tagging in No-Script Part
Smaller Changes Content Path

11.12.2012



05.07.2013

Ralf Cornehl



Ralf Cornehl
1.5

Review
Integration Instructions expanded

10.09.2013Ralf Cornehl
1.6Troubleshooting jQuery13.03.2014Ralf Cornehl
1.7Multi Page Tagging (asynchronous)07.01.2014Ralf Cornehl
He Niu
1.8

FAQ

FAQ extended

23.07.2015

23.10.2015

Ralf Cornehl

Ralf Cornehl

1.9FAQ extended21.02.2018Ralf Cornehl


Integration of the Tagging Script

The following example shows the integration of the tagging script into a website:

Therefore, the script can be integrated synchronously or asynchronously.

  • In case of the synchronous integration the script should be placed in the body part see in Integration with JavaScript (synchronous)
  • In case of the asynchronous integration the script must be placed as described in Integration with JavaScript (asynchronous)
  • In case of the synchronous integration the request is sent directly when the page is loading.
    The disadvantage of the synchronous version is that the page load may be delayed up slightly.
  • In the case of the asynchronous integration the request is sent after the page is loaded.
    The disadvantage of the asynchronous version in case of larger websites may be that the user already navigates to the next page
    before loading the complete page, so the request cannot be sent.

 

Integration with JavaScript (synchronous)

<html>
<head>
</head>
<body>
<script src="spring.js">
</script>
<script language="Javascript">
            var sp_e0 = {
             "s":"testsite",
             "cp":"Path/to/your/page", //Please go to Chapter ContentPath(cp)
             "url": document.location.href
            };
            spring.c(sp_e0);

</script>
</body>
</html> 

 

Example for shortened Form

<script src="spring.js"></script>
<script>
spring.c( { s: "testsite", cp: "Path/to/your/page", url: document.location.href} );
</script>

 

Integration with JavaScript (asynchronous)

In the asynchronous version the variable “springq” must be defined

<html>
<head>
<script type="text/javascript">
    var springq =

     springq || [];
      springq.push({
            "s":"testsite", 
            "cp":"Path/to/your/page", //Please go to Chapter ContentPath(cp)
            "url": document.location.href
      });

 </script>
 </head>
<body>
<script type="text/javascript">

// some other script

</script>

<!-- some stuff goes here -->
 

<!-- end of page -->

<script type="text/javascript">  (function() {
    var scr = document.createElement('script');  
    scr.type = 'text/javascript'; scr.async = true;
    scr.src = 'spring.js';
    var s = document.getElementsByTagName('script')[0];  
    s.parentNode.insertBefore(scr, s);
    })();

</script>
</body>
</html>

 

Integration by using multiple Pagetags (synchronous)

 

<html>
<head>
</head>
<body>
      <script src="spring.js">
      </script>

      <script language="Javascript">
            var sp_s = {
              "s":"testsite",
              "r": document.referrer
            };
            var sp_e0 = [];

            sp_e0.push({
              "cp":"path/to/page/one", //Please go to Chapter ContentPath(cp)
              "url": document.location.href
            });
            sp_e0.push({
              "cp":"path/to/page/two", //Please go to Chapter ContentPath(cp)
              "url": document.location.href
            });
            // ...
            spring.c(sp_s,sp_e0);
      </script>
</body>
</html> 

When using multiple „cp“-attributes, a call to spring.c requires two arguments: the first containing information about the sitename and the document referrer for page-tracking purposes, the second an array with the „cp“-elements.

 

Integration by using multiple Pagetags (asynchronous)

 

<html>
<head>
<script type="text/javascript">
 
    var spring_asy = [];
    var sp_e0 = [];
    var springq = springq || [];
    var sp_s = {
              "s":"testsite",
              "r":document.referrer
            };
    sp_e0.push({
              "cp":"path/to/page/one", //Please go to Chapter ContentPath(cp)
              "url": document.location.href
            });
    sp_e0.push({
              "cp":"path/to/page/two", //Please go to Chapter ContentPath(cp)
              "url": document.location.href
            });
    spring_asy.push(sp_s);
    spring_asy.push(sp_e0);
    springq.push(spring_asy);
     
 </script>
</head>
<body>

 
<script type="text/javascript">
 
// some other script
 
</script>
 
<!-- some stuff goes here -->
  
 
<!-- end of page -->
 
<script type="text/javascript">  (function() {
    var scr = document.createElement('script'); 
    scr.type = 'text/javascript'; scr.async = true;
    scr.src = 'spring.js';
    var s = document.getElementsByTagName('script')[0]; 
    s.parentNode.insertBefore(scr, s);
    })();
 
</script>
</body>
</html>

 

Integration without JavaScript (noscript)

If you are using the „noscript“ variant, the variable „js“ must be added to the URL. The variable „js“ expects an URL-encoded JSON-object. Further information on JSON can be found here: http://json.org

The generation of the REQUEST is facilitated by a tool provided by spring under the following URL:

A specific URL will be delivered for each implementation

Example:

<noscript>
<img src="REQUEST"> # REQUEST can be defined via the above tool
</noscript>

Integration without JavaScript (noscript) for SSL-Measurement

The tag needs to be changed only in the noscript part. The request must be transformed into the following https-call.

<noscript>
<img src="https://ssl-sitename.[counting domain]/j0=,,,;+,,cp=test;;;;" alt="">
</noscript>


So in the noscript part of the tag the counting domain for those SSL clients contains always the following prefix: ssl-

Troubleshooting with jQuery

If problems with the jQuery-Library occur, please follow the information given below:

  • spring.c per default modifies the DOM to transport the call to the server
  • jQuery listens on these modifications and re-executes the contained scripts
  • which then modifies the DOM

To switch off DOM modifications, use a call like

spring.c({r:document.referrer},{
         "s": "testsite",
        "cp": "Path/to/your/page", //Please go to Chapter ContentPath(cp)
        "url": document.location.href
}, 2);

the "2" given as the third parameter to the call selects an Image.src-based transport

Interface of the Tagging Script

The interface of the tagging script provides a method „commit“ (short: c). With this method a JSON-object can be consigned which then calls the measurement system.

The Method "commit" (short: c)

The method expects one or two parameters. A call to this method directly generates a call to the measurement system.

Example (Page Impressions):

var sp_e0 = {
 "s":"testsite",
 "cp":"Path/to/your/page", //Please go to Chapter ContentPath(cp)
 "url": document.location.href
};

These variables are added to the object spring by the following call:

spring.c(sp_e0);

 

List of Variables

The following list describes all variables understood by the measurement system.

Site (s) [mandatory]

This variable contains the sitename under which your website is known to the system.

You must request your sitename at spring prior to tagging your website. For example the sitename “testsite” may be used which is then internally routed to testsite.[counting domain].

 

ContentPath (cp) [mandatory]

This is the path to your page (Path/to/your/page), which identifies your content. The value of this variable has to identify a unique site. It should not contain, for example any random values.

var sp_e0 = {
 "s":"testsite",
 "cp":"Path/to/your/page",
 "url": document.location.href
};

In general there is no limitation of the charset – conform to the JSON standard http://json.org – , but for having a better interpretation of pagepaths in scores we advice to use the described standards below.

The allowable character set for all values in the tagging is UTF-8. It is however recommended to limit to the following characters:

a-z

A-Z

0-9

comma “,”

point “.”

dash “-“

underscore “_”

 

If other characters are used as the above, these characters at the beginning of the measurement chain are replaced by a point. The semicolon ";" stands as the last character in the code and marks the end of the code.

 

Special chars that should be avoided are:

quotation marks " "question mark "?"number sign or hash "#"back slash "\"

If a question mark "?" or a hash "#" is used in code, so the code will be covered only until this special character. The special character itself and all subsequent characters are discarded.


If a backslash "\" is used within the code the browser will carry out a different modification depending on the browser in which the tag is called,.

Details, see the chart below:

Code                            Internet Explorer         Firefox

1bltest\test                   1bltestest                     1bltestest

2bltest\\test                  2bltest/test                   2bltest.test

3bltest\\\test                 3bltest/est                    3bltest.est

4bltest\\\\test                4bltest//test                  4bltest.test

5bltest\\\\\test               5bltest//est                   5bltest.est

 

The following table shows some examples, how the contentpath can be used to build up an hierarchical structure: 


 

PATH DEFINITION IN SCORES

ContentPath is CASE SENSITIVE.

 

 

 

 

 

 

ContentPath code

 

Level1

Level2

Level3

Level4

"cp":"<contentpath>"

1

Testsite

   

Testsite

2

Testsite

Media

  

Testsite/Media

3

Testsite

Media

Frontpage

 

Testsite/Media/Frontpage

4

Testsite

Media

Internet

 

Testsite/Media/Internet

5

Testsite

Media

Internet

Reporting

Testsite/Media/Internet/Reporting

6

Testsite

Media

Internet

Panelinformation

Testsite/Media/Internet/Panelinformation

7

Testsite

Media

News

 

Testsite/Media/News

8

Testsite

Media

News

Event1

Testsite/Media/News/Event1

9

Testsite

Media

News

Event2

Testsite/Media/News/Event2

10

Testsite

div

  

Testsite/div

11

Testsite

Div

  

Testsite/Div

The slash "/" is used as a seperator within the content path (cp) for creating different hierachy levels

Example:

cpHierachy
Testsite→ First Level
Testsite/Media→ Second Level
Testsite/Media/News→ Third Level

 

URL (url) [optional]

In this variable the URL of the page can be stored by using document.location.href.

var sp_e0 = {
 "s": "testsite",
 "cp": "Path/to/your/page", //Please go to Chapter ContentPath(cp)
 "url": document.location.href
};
spring.c(sp_e0);


To display the URL information in the scores URL report the "url" variable has to be set in the tagging.

FAQ

How does a tracking request look like?

The Kantar Media requests are HTTP-GET-requests. They contain all the information required for measurement.

Example
GET 302 Redirect to: /blank.gif    http://test.tns-cs.net/j0=,,,r=https%3A%2F%2Fwww.google.com;+,cp=test+url=www.test.com;;;?lt=ig36v70v&x=1600x900x24
GET 200 image/gif    http://test.tns-cs.net/blank.gif


See the explanation of the request elements in the below table.

Element of the requestDescription
http://test.tns-cs.net
call to counting domain
r=https%3A%2F%2Fwww.google.com
r-variable = referrer
cp=test

cp-variable = content path set to unify content

url=www.test.com
url-variable = URL where the content is placed
lt=ig36v70v
lt-variable = random parameter to avoid browser-caching
x=1600x900x24
x-variable = screen resolution

How can I control those requests?

Step-by-step Instructions for running an HTTP-Request-Analyser:

  • On a standard laptop / desktop device → Open the browser
  • Using Chrome: Press ”CTRL+SHIFT+i”. This will bring the information screen along the bottom of the browser screen
    (On other browser, you might need specific plug-ins. For example HttpFox on Firefox browser)
  • The info screen contains several tabs across the page, but the one that matters is “network”. Select “network”
  • In the main browser window → Open the website being tested, i.e. your web page
  • As soon as you load the web page, you will notice a stream of events occurring in the information screen along the bottom of the screen
  • Click in the information screen to make sure it has focus, now click on the filter icon.
    This will allow you to enter a value in the search box
  • Enter “tns-cs.net” (= the receiving server see example above) and click the option “filter”.
    You will now see only the requests going and coming to and from the website tracking project systems
  • If you return focus to the website you can now test the tracking function 
    and watch the results in the HTTP-request data scrolling along the information screen
  • This data is NOT captured automatically so you MUST copy and paste ALL HTTP-requests after the test has been completed;
    this data should be shared with us in order for the implementation to be signed off.

Why is a 302 redirect used?

When a request hits our servers, it is measured and then answered back with a http-302-redirect response (“temporarily moved”).
This 302-redirect forces caching mechanisms such as proxies or browser-cache, to request the resource anew from the server.

However, the related RFC2616 is not completely implemented here. In replying the redirect-URL to the client, only the URI-part is sent (host name of the server omitted).
This leads to a higher performance of the system and a reduction of the transfer volumes.
For repeated requests, the saving is about 10 bytes per response compared to full responses.

Additionally in the local client, only one copy of the blank.gif is allocated and processed.

How to define a page view?

A PageImpression/PageView describes the call of one Webpage by the user.
The following requirements have to be met before a PageImpression/PageView can be counted and referred to a special counting-ID:

  • The page has to meet the FQDN (https://en.wikipedia.org/wiki/Fully_qualified_domain_name) for the website (or alias/redirect).
  • The page has to belong to the site, either in look and feel or by a clear and obvious optical ID.
  • Each call of the page may be counted only once.
  • The call of the page has to be user-induced.

The following examples describe user-induced actions and substantial changes, which could either be counted or not counted.

User-induced actions: (counted)

  • Call of a new page or new parts of the page, caused by mouse click or keyboard entry.
  • Call of same page or same parts of the page (reloads), caused by mouse click or keyboard entry.
  • Open a browser.

Non user-induced actions: (not counted)

  • Call of a new page or new parts of the page by automatic forwarding (beside redirects and alias).
  • Call of the same page the same parts of the page by automatic reload (e.g. news ticker).
  • The call of a page by closing a window.
  • The call via robots/spiders and similar.

Substantial change: (counted)

  • Changes of text passages, whose context is in the main focus of the page.
  • Changes of visual, multimedia contents, whose context is in the main focus of the page.
  • Asking a new question in quiz games/surveys.
  • Loading of new picture within a picture gallery (slide-show).

Non substantial change: (not counted)

  • Changes of the page by crossing with the mouse (mouse-over)
  • Shift of monitor contents by aid of mouse or keyboard
  • Entry of single signs, whereas the content change is to represent the input characters
  • Selection of monitor contents by aid of mouse or keyboard (e.g. select box)
  • Scrolling with mouse or keyboard within one page
  • Change of color (text, picture, background etc.)
  • Change of layout of the page, without changing the content

Conclusion: User-induced means every action of a user which geared to call a page, in order to cause a substantial change of the site content.

How is the last page view handled?

When a client has more than one activity within a session, the "duration" (page viewtime) of the current activity is assumed to be ended by the next.
So the viewtime is not computable for all activities, because the last activity in a session has no successor in time.

To display figures for all activities in the system, a projection is used:

  • the average duration of all measurable activities (i.e. with successors) is computed
  • and that average duration is projected to all activities.

Assumption: the missing viewtimes are well represented by the existing ones.

Example:

  • a certain webpage has 100 pageviews and a measurable viewtime for 90 pageviews is counted
  • for 10 pageviews the vietime is missing
  • the system collected 180 seconds for those 90 pageviews

The average viewtime per measurable pageview is them 180/90 seconds = 2 seconds.
Which is - by assumption - the average of all 100 pageviews too. 

Conclusion: The total viewtime (sum) for the 100 pageviews is then 200 seconds.


How is a client defined?

In the first step, the presence of a cookie in the request is checked. Two types of cookies are possible, either a conventional, third-party http-cookie (i00) or
a cookie passed via URL-Parameter. The i00-cookie has a higher priority, i.e. it will always be used when present while the cookie set via URL is intended
to cope with low third-party cookie acceptance. It will be set if possible (e.g. html5 cookie) and used if no i00-cookie is available.
If no cookie can be set an "ident" as browser-"fingerprint" (combination of IP-address and user agent info) is created.

Two session containers are created, one for "idents" without cookies and one for those with a cookie. A client may move between the two types.
Keywords in this context are the evolving of a session (first contact without cookie, following by contacts with set cookie) and session uniqueness.

  • If no valid cookie is contained, a new session is established.
  • If a session that is assigned to a certain "ident" can be found, the event is added to this session.
  • Otherwise a new session is created and returned.

Conclusion: Client = the same cookie or same browser "fingerprint" (combination of IP-address and user agent info)

How is a session defined?

The metric “session” is used in our measurement system.

Difference to other system that count “visits”: The metric "session" is counted every single hour, whereas the metric "visit" is counted only once for the certain hour when the usage begins.


A session is a collection of events (like page impressions) with the same cookie or fingerprint (combination of IP-address and user agent info), if the cookie is missing.

Sessions can be computed:

  • Within a single web site (the standard)
  • Across all web sites (networks)

There is no logout, so a timeout is used. In a single session the time between two events is less than 30 minutes.
So after an idle time of 30 minutes a new session is initiated. (following international standards)

The following information is provided for every session

  • the start time of session,
  • the time of the last event in the session,
  • the signature of the session, formed as an MD5 hash of the user agent and the IP-address,
  • the cookie of the session, if available
  • the number of page impressions
  • the external referrer at beginning of the session
  • a list of (dimensional) properties of events (such as the pixel code)
  • a list of properties of the session (references to dimensions, which are stored once per session only, such as user agent, geo-location, screen resolution)
  • a list of dates of events

Conclusion: The session context is kept over the switch of the hour as long as the idle time between user interactions is not longer than 30 minutes

How to block the survey call?

QDS (Questionary Dispatching Server)

AFTER the FIRST request-transmission an additional script is sourced from a server (QDS) in the defined domain.
This is done by adding a script tag to the header of the document.
This behavior can be switched off by defining the springconfig variable before loading the JS library: 
var springconfig = {"survey":false};

Synchronous Tagging (Supported since version 1.6.3 of the sensor library):

<html>
<head>
</head>
<body>
	 <script type='text/javascript'>
	 	var springconfig = {"survey":false};
	 </script>
     <script src="spring.js">
	 </script>
     <script type='text/javascript'>
		  var sp_e0 = {
            "s":"testsite",
            "cp":"Path/to/your/page", //Please go to Chapter ContentPath(cp)
            "url": document.location.href
           };
        spring.c(sp_e0);
     </script>
</body>
</html> 

The synchronous mode will still support the spring.ns setting (which was introduced with version 1.6.0 of the sensor library, so full downward compatibility is given):

<html>
<head>
</head>
<body>
     <script src="spring.js">
	 </script>
     <script type='text/javascript'>
          spring.ns = true;
		  var sp_e0 = {
            "s":"testsite",
            "cp":"Path/to/your/page", //Please go to Chapter ContentPath(cp)
            "url": document.location.href
           };
        spring.c(sp_e0);
     </script>
</body>
</html> 


Asynchronous Tagging (Supported since version 1.6.3 of the sensor library):

<html>
<head>
<script type="text/javascript">
    var springq =
     springq || [];
      springq.push({
            "s":"testsite", 
            "cp":"Path/to/your/page", //Please go to Chapter ContentPath(cp)
            "url": document.location.href
      });

 </script>
 </head>
<body>
<script type="text/javascript">

// some other script

</script>

<!-- some stuff goes here -->
 

<!-- end of page -->

<script type="text/javascript">  (function() {
	springconfig = {"survey":false};
    var scr = document.createElement('script');  
    scr.type = 'text/javascript'; scr.async = true;
    scr.src = 'spring.js';
    var s = document.getElementsByTagName('script')[0];  
    s.parentNode.insertBefore(scr, s);
    })();

</script>
</body>
</html>

How will Adblock or similar tools influence the tracking?

What it is and how it operates:

Ad-blocker predominantly affects web browsers and runs as an extension in this environment:

http://en.wikipedia.org/wiki/Adblock_Plus

We can of course not be completely aware of every browser-addon or privacy-list out there that is blocking website tracking. 
The most important question in the context of Adblock Plus is if there is a domain entry in https://easylist-downloads.adblockplus.org/easyprivacy.txt which corresponds to your counting domain used for a project.

Hence, if there is an entry that serves to block everything to and from the domain that you use for counting no tagged data will be returned to the measurement system.


What can we do about this?

There is not currently a way to circumvent this issue, and all tracking systems will be affected similarly.
We do not have a feel for the levels of usage although we can point out, awareness of such programs is on the rise.
The most practicable solution to this would be changing to another domain name (to which we would send requests).
However, this might prove only temporary because the new domain may also be added to the list very quickly again.

In conclusion: we are aware that it happens, but there is very little we can do about it.