comscore.js - JavaScript foundation library for Tracking (Comscore) integration
Automatic (synchronous) tracking:
<script type="text/javascript">
document.write(unescape("%3Cscript src='" + (document.location.protocol == "https:" ? "https://sb" : "http://b";) + ".scorecardresearch.com/beacon.js'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
document.write(unescape("%3Cscript src='comscore.js'%3E%3C/script%3E"));
</script>
Manual (asynchronous) tracking:
<script type="text/javascript">
document.write(unescape("%3Cscript src='comscore.js'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
Libero.getTracking({ callDirectly: 1 });
<script>
comscore.js is the minimal JavaScript foundation library for tracking (Comscore) calls made from header/footer packages. Note that each package contains comscore_<sitename>.js.
comscore.js creates a global Libero object (if not already defined) with several properties and function.
Libero.StashLibero.Stash is an empty object intended for use by page JavaScript code.
Libero.getTracking( object ) (aka Libero.getComscore( object ))This function does the tracking (Comscore) call.
Note that the the Libero.getComscore function has been renamed to Libero.getTracking.
However, for backward compatibility, you can continue to use Libero.getComscore with the same API
even if we suggest to change the name to the new one.
The function takes a single argument object object. Within object you could set following properties:
url string
Passes current page URL. Default value is document.location.href.
path string
Passes current page URI. Default value is document.location.pathname.
cookie string
Passes current page cookies. Default value is document.cookie.
ajax string
Passes ajax target. Default value is undefined.
debug integer
Print on console.log some debug useful informations. Default value is libero_comscore_debug (if defined) or 0.
test boolean
Makes all tracking (Comscore) requests to test site. Default value is libero_comscore_test (if the variabile is defined in the page) or false.
Note that for development/stage/preproduction enviroment, you must set libero_comscore_test to a true value:
var libero_comscore_test = 1;
callDirectly boolean
Makes tracking (Comscore) calls directly (that is, not using COMSCORE.beacon()). Default value is false.
callJS boolean
Makes tracking (Comscore) calls using COMSCORE.beacon(). Default value is false.
https boolean
Uses https protocol when calling tracking (Comscore) directly (that is when callDirectly has been set to true).
Default value is current HTTPS status connection (that is, document.location.protocol value is checked).
log_prefix string
Set prefix for console.log() prints. Default value is [LT].
check_multiple_calls integer
Enables check for multiples comscore calls.
Set to the maximum calls allowed from the same page (that is, without reload and/or frame/iframe).
Default value is libero_comscore_check_multiple_calls (if the variabile is defined in the page)
or 0 (that means check disabled).
labels object
Adds custom labels to Comscore call. For example:
labels: {
lib_keyname1: 'key_value1',
lib_keyname2: 'key_value2'
...
}
Default value is undefined.
See Adding custom labels to Comscore call for more informations.
onLoadHandler function
Sets a callback that will be executed after the traking pixel is loaded (or there was an error on loading it).
This allows to send successfully the Comscore requests that are associated to events like clicks or form's submit and, more in general, when the browser's location changes.
In order to don't block handler execution (for example for network delays
or if Comscore servers are busy), the onLoadHandler function will be
executed anyway. See timeout argument above for more informations.
NB: The onLoadHandler argument has effect only if callDirectly is true.
For example:
Libero.getTracking({
callDirectly: 1,
onLoadHandler: function(){ document.myform.submit() }
})
or:
Libero.getTracking({
callDirectly: 1,
onLoadHandler: function(){ document.location.href='http://foo.baz.com' }
})
If you use these calls in onclick or onsubmit DOM events, be sure to
return always a false value:
<a href="http://foo.baz.com"; onclick=" return (Libero.getTracking({ callDirectly: 1, onLoadHandler: function(){ document.location.href='http://foo.baz.com' } }) && false) ">My link</a>
timeout integer
Sets timeout, in seconds, after which the onLoadHandler will be executed anyway.
Default value is 2.
The tracking (Comscore) calls behaviour could be also customized by setting an appropriate query string. In that case, the call will be always sychronous. The CGI parameters are:
cs_url string
Passes URL page. Default value is undefined.
cs_path string
Passes URI page. Default value is undefined.
cs_cookie string
Passes current cookies page. Default value is undefined.
cs_ajax string
Passes ajax target. Default value is undefined.
cs_debug integer
Print on console.log some useful debug informations. Default value is libero_comscore_debug (if defined on the page) or 0.
cs_test interger
Makes all tracking (Comscore) requests to test site. Default value is libero_comscore_test (if defined on the page) or 0.
Note that for development/stage/preproduction enviroment, you must set that parameter to a true value.
cs_https integer
All CGI paramenters must be URL-escaped.
Moreover, the tracking (Comscore) call will start only if at least one of the
cs_ajax, cs_path, cs_url or cs_cookie parameters
has been defined on the query string
http://mysite.libero.it/footer_on_iframe.html?cs_url=http%3A//mysite.libero.it&cs_test=1
The easiest way to add tracking code is to include a code in your footer like following:
<!-- Libero COMSCORE start - Version x.y.z -->
<script type="text/javascript">
document.write(unescape("%3Cscript src='" + (document.location.protocol == "https:" ? "https://sb" : "http://b";) + ".scorecardresearch.com/beacon.js'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
document.write(unescape("%3Cscript src='js/comscore.js'%3E%3C/script%3E"));
</script>
<noscript>
<img src="http://b.scorecardresearch.com/p?c1=2&c2=13259779&cj=1&name=libero.others&ns_site=libero"; />
</noscript>
<!-- Libero COMSCORE end -->
Please, include always the code provided in footer*.html files of header/footer distribution
since the <noscript> section can differ from a site to another.
Note that if your site run under HTTPS protocol, the <noscript>
section must changed in order to
<noscript>
<img src="https://sb.scorecardresearch.com/p?c1=2&c2=13259779&cj=1&name=libero.others&ns_site=libero" />
</noscript>
In order to do tracking (Comscore) asynchronous calls (for example, from AJAX applications
or any other situations that don't require the reload of the page), you should use Libero.getTracking() API.
The following code does a non-blocking JavaScript call, by using setTimeout:
<script type="text/javascript">
document.write(unescape("%3Cscript src='comscore.js'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
setTimeout('Libero.getTracking({ ajax: \'' + ajax_target + '\', callDirectly: 1 })',10)
</script>
The following example does a non-blocking JavaScript call (by using setTimeout) on the another frame:
<script type="text/javascript">
document.write(unescape("%3Cscript src='comscore.js'%3E%3C/script%3E"));
</script>
<iframe border="0" style="display: block" width="100%" id="comscore" src="footer.html"></iframe>
<script type="text/javascript">
setTimeout('document.getElementById(\'comscore\').contentWindow.Libero.getTracking({ ajax: \'' + ajax_target + '\', callDirectly: 1})',10);
</script>
Note that footer.html must include comcore.js and both page than iframe have to live under the same domain.
The tracking (Comoscore) call should be customized as follow.
For error pages, before to load js/comscore.js, you must set
libero_comscore_error JavaScript variable with the correspondent HTTP status code.
Currently, only 4xx and 5xx values are allowed.
For example:
<script type="text/javascript">
var libero_comscore_error = 404;
</script>
For stage, development and pre-production sites, before to load js/comscore.js, you must set
libero_comscore_test JavaScript variable as follow:
<script type="text/javascript">
var libero_comscore_test = 1;
</script>
In that way, the tracking (Comscore) calls will be done with a special test account.
Using JavaScript API (Libero.getTracking) alternatively you must set test key with a true value.
Using the CGI API alternatively you must set cs_test parameter with a true value:
cs_test=1
Note that js/comscore.js auto-detects test mode if the referer live under .st.libero.it and .pp.libero.it domain,
even if libero_comscore_test hasn't been defined.
The debug mode allows to print with browser console.log() method (if defined) some useful
informations.
In order to enable debug mode, you could alternatively:
before loading js/comscore.js, set libero_comscore_debug JavaScript statically as follow::
<script type="text/javascript">
var libero_comscore_debug = 1;
</script>
Using JavaScript Libero.getTracking() API, set debug key with a true value.
This is the fastest mode. For example, once you've loaded a page containing tracking code, turn on Javascript console (by pressing F12 key either on Firefox/Firefug-powered, Internet Explorer >= 7.x or Chrome), then type on the command line a line like following:
Libero.getTracking({ callDirectly: 1, debug:1, test: 1 })
You can also specify all parameters accepted by Libero.getTracking() as ajax or url:
Libero.getTracking({ ajax: 'http://posta.libero.it/rubrica/piu_contatti', callDirectly: 1, debug:1, test: 1 })
On the console panel, you'll see the debug informations. By default, all prints are
prefixed with [LT] string (it stands for ``Libero Tracking''). For example:
[LT] Matching ajax ^http:\/\/posta\.libero\.it\/leggi_mail\/cestino
On the Firebug Net tab (or in a equivalent panel, depending on the browser you are using), all the tracking (Comscore) calls are made to urls under http://b.scorecardresearch.com/ or https://sb.scorecardresearch.com/ domains.
Using the CGI API, set cs_debug parameter with a true value. For example.
http://mysite.libero.it/footer_on_iframe.html?cs_url=http%3A//mysite.libero.it&cs_debug=1
Set (locally) the value of the cookie LiberoTrackingDebug to 1 under .libero.it domain.
For example, it hf.js JavaScript library is loaded, you cloud type
in the browser Javascript console command line:
Libero.HF.setCookie('LiberoTrackingDebug',0,{day: 365},'/','.libero.it')
Note that this technique will work only wiht URLs that live under .libero.it domain. If you want to activate debug mode for different domain, you have to set another cookie for that domain.
Note: Do not enable debug mode in any production site.
In order to add custom labels to Comscore call (that is, CGI parameters), you can alternatively:
Define Libero.Stash.csLabels as anonymous object containing key/values pairs before Comscore call.
For example:
<script type="text/javascript">
Libero.Stash.csLabels = {
lib_keyname1: 'key_value1',
lib_keyname2: 'key_value2'
};
</script>
Use labels param in Libero.getTracking() call. It is anonymous object containing key/value pairs.
Note that:
The keys must begin with lib_ prefix.
The key values have to be a scalar.
The are following reserved words that you cannot use as object's keys:
name
Keys starting with ns_
Keys starting with c
Sometime can occurs that a site inserts the ``Comscore'' code several times. That means that tracking calls will be duplicate,
In order to enable check to prevent multiples comscore calls (synchronous mode),
you can set libero_comscore_check_multiple_calls Javascript variable before
loading js/comscore.js file:
<script type="text/javascript">
libero_comscore_check_multiple_calls = 1;
</script>
libero_comscore_check_multiple_calls will set to maximum calls allowed from
the same page (that is, without reload and/or frame/iframe).
You can use alternatively check_multiple_calls argument in
Libero.getTracking() asynchronous call.
Enrico Sorcinelli <enrico.sorcinelli [at] staff.libero.it>
Send bug reports and comments to: <enrico.sorcinelli [at] staff.libero.it>. In each report please include also the API version module, the browser name and version and your SO.
Copyright (C) 2012 by Libero S.r.l.