Page Tracking

When integrating with Piano we recommend that you drop the Piano javascript on all pages. This will enable you to track data across your entire site as well as leverage the full suite of Piano functionality.

Please note that you will need a unique VX production application ID (AID) to implement AI page tracking; you can contact your Piano account representative to receive yours.

Sample Tracking Code

The full sample tracking code looks as follows:

tp = window["tp"] || [];
 
// The content published date, see: http://vx.piano.io/javascript-tracking
tp.push(["setContentCreated", "2014-04-03T04:00:00"]);
 
// The content author, see: http://vx.piano.io/javascript-tracking
tp.push(["setContentAuthor", "Ernest Hemingway"]);
 
// The content section, see: http://vx.piano.io/javascript-tracking
tp.push(["setContentSection", "Literature"]);
 
// The content tags, see: http://vx.piano.io/javascript-tracking
tp.push(["setTags", ["sports", "new york", "yankees"]]);
 
// If the content is native advertising, see: http://vx.piano.io/javascript-tracking
tp.push(["setContentIsNative", false]);
 
// Set custom params, see: http://vx.piano.io/javascript-tracking
tp.push(["setCustomParam", "<name>", "<value>", "<scope>"]);
 
// Set Zone. Zone can be used to indicate the AAM platform, or subsection of your site
tp.push(["setZone", "Web"]);
 
// Add custom variable as any key-value pair. The first parameter is the key or name, and the second is the value
tp.push(["setCustomVariable", "userState", "Subscriber"]);
 
// Initiate experience loading
// Note that this step is not required if you're already running composer on your site
(function(src){var a=document.createElement("script");a.type="text/javascript";a.async=true;a.src=src;var b=document.getElementsByTagName("script")[0];b.parentNode.insertBefore(a,b)})("//experience.tinypass.com/xbuilder/experience/load?aid="+
"YOUR_PRODUCTION_AID");

Note: Parameters like published date, author, section, and others must be set prior to the init callback as they are configuration.

Note: You must still call the init function even if you are only tracking pageviews and have an empty init callback.

The parameters that are commented out are optional and are not strictly required for page tracking. These parameters enable additional functionality for reporting, segmenting your audience, drive the ability to customize user experiences, and enable to offer dynamic product bundles. Piano will release more and more functionality based on these additional parameters. For this reason it is highly recommended to configure the parameters as described below.

Published Date

The published date should be an ISO 8601-formatted string that includes the published date and time of the content, local to your website's timezone. For instance, a piece of content that was published at 4am in New York on April 3rd, 2014 would set:

tp.push(["setContentCreated", "2014-04-03T04:00:00"]);

As per the ISO-8601 specification, if no timezone indicator is present, the date and time is interpreted as local time. Local time is local to the application’s configured timezone, not Piano's. The published date enables content age analysis and helps to set content rules based on aging of content.

Author

The author field should contain a string of the author that published the content, for instance:

tp.push(["setContentAuthor", "Ernest Hemingway"]);

The author field enables reporting of traffic and audiences by author.

Section

The section field should contain the section that the content is a part of, for example:

tp.push(["setContentSection", "Literature"]);

Sections are freely-definable and should match how you group content for analysis. The sections do not necessarily have to match with the sections offered in a menu structure in your application. The section field enables reporting by section.

Tags

To track pages using tags, pass them as in the following example:

 tp.push(["setTags", ["Page", "News", "Piano", "VX"]]);

Tags allow for creating dynamic product bundles and can be used for reporting purposes.

Native content flag

The native content flag indicates whether the content is native advertising, i.e. sponsored content. If set to false it means that the content is editorially created. If set to true it means that this is sponsored content, for example:

tp.push(["setContentIsNative", false]);

The native content flag enables to split traffic analysis by type of content.

AAM reporting zones

If you are subject to AAM reporting you can tag pages so that they are tracked accordingly. Zone can be used to indicate the AAM platform, or subsection of your site.

tp.push(["setZone", "Web"]);

Custom Variables

You can add custom variables as any key-value pair. The first parameter is the key or name, and the second is the value. These custom variables can be used in user segmentation in Composer and can also be used in Templates and Offers to customize user experience. You can set multiple custom variables.

The custom variable name is case-sensitive and should only contain alphanumeric characters and underscore.

tp.push(["setCustomVariable", "userState", "Subscriber"]);

Custom Parameters

Custom parameters allow to send any name-value pairs that further describe the page request, the content consumed, or the user. The scope of the parameter allows to determine whether the parameter belongs to the user profile, profile of the content or url, or is only relevant for this one request. Custom parameters allow to provide an even richer set of feature for reporting and analysis.

tp.push(["setCustomParam", "name", "value", "scope"]);
tp.push(["setCustomParam", "name", ["value1","value2","value3"...], "scope"]);
  • scope is one of [‘content’, ‘user’, ‘request’] - defines what does this param describe
  • name is the name of custom parameter
  • value is string or array of strings

Some example use cases are listed below:

• The segment or tier a user belongs to as identified by the CMS or a third-party system:

tp.push(["setCustomParam", "tier","gold","user"]);

• The group a url or article belongs to as defined in the CMS:

tp.push(["setCustomParam", "type","premium","content"]);

• The campaign used to drive traffic to the page as identified by the CMS:

tp.push(["setCustomParam", "campaign","NL_Mar2016","request"]);

Tagging Rules

Tagging rules help to validate data collection mechanisms. Adherence to these tagging rules will enable you to generate a richer set of reports. They are, however, not required for the system to function properly. Nevertheless, to ensure complete reporting, all pages, irrespective of type, should be tracked.

The following tagging rules enable reporting on the listed page types:

Types Purpose Rules
Section Publish Date Author Native Content
Homepage The initial or main page of your website Set to: “homepage” Leave blank Leave blank Leave blank
Index pages Organizes content from multiple pages into a single location: for example, a 'sports' or 'technology' section page. Set to: the name of the sectionLeave blank Leave blankLeave blank
Article pages Pages containing specific articles Set to: the name of the section Fill in Fill in Fill in
Other pages Contact Us, About Us, etc. Set to: “otherpagetype” Leave blank Leave blank Leave blank

Remember: To ensure complete reporting, all pages should be tracked.

Specialty Topics

For Multiple Sites and Domains

For tracking purposes, Piano sets first-party cookies only. This means that if the same tracking code is placed on firstdomain.com and seconddomain.com, the same browser visiting both domains will have two distinct cookies, and therefore Piano won’t be able to run reports across domains.

Parent companies please note: if you have multiple sites, the tracking code on each site must include its own unique application ID (AID) so the data sets are collected appropriately. Please contact your account representative or Piano support if you will need to have cross-domain reports.

Continuous Scrolling

If you implement a continuous scrolling site, you should call tp.main.trackPage() when subsequent posts are loaded or when the scroll depth reaches the desired triggering point. An example of tracking the page view after loading additional content is:

$.ajax({
    url : "/load-more",
    dataType : "json"
}).done(function(data) {
    $(".posts").append(data.html);
 
    tp = window["tp"] || [];
 
// The content published date, see: http://vx.piano.io/javascript-tracking
// tp.push(["setContentCreated", "2014-04-03T04:00:00"]);
 
// The content author, see: http://vx.piano.io/javascript-tracking
// tp.push(["setContentAuthor", "Ernest Hemingway"]);
 
// The content section, see: http://vx.piano.io/javascript-tracking
// tp.push(["setContentSection", "Literature"]);
 
// The content tags, see: http://vx.piano.io/javascript-tracking
// tp.push(["setTags", ["sports", "new york", "yankees"]]);
 
// If the content is native advertising, see: http://vx.piano.io/javascript-tracking
// tp.push(["setContentIsNative", false]);
 
// Set custom params, see: http://vx.piano.io/javascript-tracking
// tp.push(["setCustomParam", "<name>", "<value>", "<scope>"]);    
 
    tp.push(["init", function() {
        tp.main.trackPage(data.url);
    }]);
});

The actual implementation will be specific to your website. Contact your account representative if you have any questions on how to implement page tracking for continuous scrolling.

Detecting Adblocker

The actual implementation of detecting whether a browser has adblocker enabled is up to you; however, this simple script will attempt to load a file that will be blocked by most adblockers. It registers an onerror callback that sets the __adblocker cookie to true, and an onload callback that sets the __adblocker cookie to false.

Piano reads the __adblocker cookie on the browser to perform its logic. The rules of how Piano treats the cookie are:

  • If the __adblocker cookie doesn't exist, the adblocker state will be recorded as not detected.
  • If the __adblocker cookie is set and is either the boolean true or the string “true” the state will be enabled.
  • If the __adblocker cookie is empty, the boolean false, or any string other than “true” the state be disabled.

If you are placing the code directly on your site, use this code. If you are using a tag manager, consult the documentation below.

<script> 
var setAdblockerCookie = function(adblocker) {
    var d = new Date();
    d.setTime(d.getTime() + 60 * 60 * 24 * 30 * 1000);
    document.cookie = "__adblocker=" + (adblocker ? "true" : "false") + "; expires=" + d.toUTCString() + "; path=/";
}
var script = document.createElement("script");
script.setAttribute("async", true);
script.setAttribute("src", "//www.npttech.com/advertising.js");
script.setAttribute("onerror", "setAdblockerCookie(true);");
script.setAttribute("onload", "setAdblockerCookie(false);");
document.getElementsByTagName("head")[0].appendChild(script);
</script>

Tag Managers

If you are using a tag manager other than Tealium or GTM, consult your tag manager's documentation to ensure you are supplying the proper tags, which may mean the removal of the opening and closing script tags.

Please note: Execution order is important. Running an ad blocker detection script in a separate tag from the main tracking script may result in both scripts running in parallel; which may result in inaccurate reports. The ad blocker detection script should be placed before the tracking script within the same tag in your tag manager.

Tealium

The adblocker tags for Tealium are as follows:

var setAdblockerCookie = function(adblocker) {
    var d = new Date();
    d.setTime(d.getTime() + 60 * 60 * 24 * 30 * 1000);
    document.cookie = "__adblocker=" + (adblocker ? "true" : "false") + "; expires=" + d.toUTCString() + "; path=/";
}
var script = document.createElement("script");
script.setAttribute("async", true);
script.setAttribute("src", "//www.npttech.com/advertising.js");
script.setAttribute("onerror", "setAdblockerCookie(true);");
script.setAttribute("onload", "setAdblockerCookie(false);");
document.getElementsByTagName("head")[0].appendChild(script);

GTM

The adblocker tags for Google Tag Manager (GTM) are as follows:

<script> 
var setAdblockerCookie = function(adblocker) {
    var d = new Date();
    d.setTime(d.getTime() + 60 * 60 * 24 * 30 * 1000);
    document.cookie = "__adblocker=" + (adblocker ? "true" : "false") + "; expires=" + d.toUTCString() + "; path=/";
}
var script = document.createElement("script");
script.setAttribute("async", true);
script.setAttribute("src", "//www.npttech.com/advertising.js");
script.setAttribute("onerror", "setAdblockerCookie(true);");
script.setAttribute("onload", "setAdblockerCookie(false);");
document.getElementsByTagName("head")[0].appendChild(script);
</script>

Disabling Tracking

If you need to disable page tracking altogether, set the trackPages boolean to false.

tp.push(["setTrackPages", false]);

If you disable page tracking, we will be unable to collect any data to run AI reports for you.