Follow

Content Based Event Tracking Install instructions

This document contains all of the information you will need to install the WhatCounts Behavioral Track & Trigger module onto your website. 

WhatCounts uses a JavaScript library to capture events that occur on your site. To ensure a successful integration, these instructions should be reviewed and executed by a developer with at least 1 to 3 years of JavaScript development experience.  The developer needs to know where each script should be placed to have access to the appropriate information on the site.

Installation Checklist 

  • Install Scripts 
    • Install Main Script 
    • Install Identify via Account Script 
    • Install Identify via Email Script 
    • Install Viewed Content Script 
    • Install Viewed Category Script 
    • Install Searched Content Script 
  • Test Installation 

Estimated Time For Installation 

We estimate that installing and testing these scripts will take between 1 to 5 hours of development time, depending on the complexity of the site and the familiarity of the developer with the system. 

Information Needed Before Installation 

You will need 2 Site Keys from WhatCounts: 1 for test and 1 for production. To locate your site keys: 

  1. While logged in, click the Customer Care icon in the top-right corner and select "BTT Validator". 
  2. Your Site Keys are located in the "Configuration" section.

Script Installation Instructions

Each of the following scripts should be installed into a template for your website. For each script, fields in the format %%field%% should be replaced with a variable from your site to provide the information described in the fields table. Optional fields should be replaced with an empty string (i.e. "") if they are not provided.

Main Script 

Page: This script should appear on every page on your site inside the <head> tag 

* %%Field%% is a placeholder. %% should not appear in the script on your site.

<script type="text/javascript"> 
!function(){ var analytics=window.analytics=window.analytics||[]; 
if(!analytics.initialize) { if(analytics.invoked) { window.console&&console. 
error&&console.error("Segment snippet included twice."); } else { analytics. 
invoked=!0; analytics.methods=["trackSubmit","debug", 
"trackClick","trackLink","trackForm","pageview","identify","group","track","ready","alias","page","once","off","on"]; 
analytics.factory=function(t){ return function() { var e=Array.prototype.slice. 
call(arguments); e.unshift(t); analytics.push(e); return analytics; } }; 
for(var t=0;t<analytics.methods.length;t++){ var e=analytics.methods[t]; 
analytics[e]=analytics.factory(e) } analytics.load=function(t){ analytics. 
apiKey = t; var e=document.createElement("script"); e.type="text/javascript"; 
e.async=!0; e.src="https://static.whatcounts.com/analytics.min.js"; var 
n=document.getElementsByTagName("script")[0];n.parentNode.insertBefore(e,n) }; 
analytics.SNIPPET_VERSION="4.0.0"; 
window.analytics.load('%%wcapikey%%'); 
window.analytics.page(undefined, undefined, undefined, {wcapiVersion: '2. 
0'}); 
}}}(); 
</script> 

Name

Req? 

Description 

wcapikey 

Y

The API key provided by WhatCounts. This can be hardcoded in the template, but must be different on your test environment and production environment to avoid contaminating production data.

 

Identify via Account Script 

Page: This script should appear on every page on your site inside the <head> tag, beneath the previous script.

You should install this script so that it executes on any page where you can positively identify the user. For some sites that means it can be placed into the head after the main script, for other sites it will need to be placed on certain pages or templates where the customer information is available. If email information is available but the user id is not, the identify event should capture an email and any other available information, and leave userid as an empty string.

* %%Field%% is a placeholder. %% should not appear in the script on your site.

<script type="text/javascript">
(function() {

// Identify the customer if they have an account.
//
// If this script is installed on a page where you will always have
// customer information, the "if" statement can be removed.

if(%%loggedin%%) {
window.analytics.identify("%%userid%%", {
name: "%%fullname%%",
fullName: "%%fullname%%",
firstName: "%%firstname%%",
lastName: "%%lastname%%",
email: "%%email%%"
}, {wcapiVersion: '2.0'});
}
})();
</script>

Name

Req? 

Description 

userid

Y

A unique id for the user.

loggedin 

Y

A check to see if there is a currently logged in customer we can identify. If so, we should show customer information in the identify event. If not, we can remove that event on the current page. This should return `true` or `false` to the page.

fullname 

Y

The full name of the logged in customer if available, empty string otherwise.

firstname 

Y

The first name for the logged in customer if available, empty string otherwise.

lastname 

Y

The last name for the logged in customer if available, empty string otherwise.

email 

Y

The email address for the logged in customer.  This is essential to include correctly for every identify event. 

 

Identify via Email Script 

Page: Many sites provide forms for a user to enter their email to sign up for a newsletter or other email communication. This script should be included anywhere that occurs. 

This script provides a second way of pulling in user information. Since it only pulls in an email, it is less rich than pulling in full login data. But for many sites it provides more opportunity for capturing data.

* %%Field%% is a placeholder. %% should not appear in the script on your site.

<script type="text/javascript"> 
// IMPORTANT: The following code will need to be customized for your site
// The end result should be an identify event triggering when the user adds 
// their email to an email submission form. 

(function() { 
// this variable should be set to point at the form submission button 
// the exact code here may need to be customized for your site 

var emailFormButton = document.getElementById('emailFormButton'); 

// this variable should be set to point at the form submission input 
// the exact code here may need to be customized for your site 

var emailInput = document.getElementById('emailInput'); 
if (emailFormButton) { 
emailFormButton.addEventListener('click', function() { 
window.analytics.identify(null, { 
email: emailInput.value, 
source: 'email-input', 
}, {wcapiVersion: '2.0'}); 
}); 
} 
})(); 
</script> 

 

Viewed Content Script  

Page: This script should be placed at the bottom of all pages 

* %%Field%% is a placeholder. %% should not appear in the script on your site.

<script type="text/javascript">
(function(){
analytics.track('Viewed Content', {
publishdate: "%%publishdate%%",
author: "%%author%%",
contenttype: "%%contenttype%%",
title: "%%title%%",
pagecategory: [%%pagecategory%%]
}, {wcapiVersion: '2.0'});
})();
</script>

Name

Req? 

Description 

title

Y

The title of the page.

author

Y

The author of the page’s content.

contenttype

Y

The content type of the page viewed.

publishdate 

Y

The date which the page's content was published.

pagecategory 

Y

This should be a list of the categories that contain this page, in array form. If your site has nested categories, those can be represented in the format ['parent category > child category > grandchild category', 'category2', 'parent category > category 3'].

 

Viewed Category Script  

Page: This script should be placed at the bottom of all category pages 

<script type="text/javascript">
(function(){
analytics.track('Viewed Product Category', {
category: "%%category%%"
}, {wcapiVersion: '2.0'});
})();
</script>

Name

Req? 

Description 

category 

Y

The category represented by this page. This can either be a single string like "News", or in the case of hierarchical categories, an array of strings, shown like { category: ["News", "Sports", "Baseball"] }.

 

Searched Content Script (Optional) 

Page: This script should be included on your search results page. 

* %%Field%% is a placeholder. %% should not appear in the script on your site.

<script type="text/javascript">
(function(){
analytics.track('Searched Product', {
query: "%%query%%"
}, {wcapiVersion: '2.0'});
})();
</script>

Name

Req? 

Description 

query 

Y

The search terms for the current search.

 

Testing

After completing the installation of every script on your test environment, please perform the following actions on your test environment in order to generate test events. If the installation is working currently, these test events should immediately be visible in our validator. We recommend keeping the validator open in a separate tab or window, and refreshing each team you perform each action, to confirm that 1) the appropriate resulting event appears in the validator, and 2) the properties of the event appear correctly. 

For more specifics on what to test, please see each action below. 

All installations should test the following: 

  • Go to your home page
    • Check: Does a "Viewed Content Event" fire in the validator? 
  • Go to a page within a specific category 
    • Check: Does a "Viewed Category Event" fire in the validator? 
    • Check: Do the page properties appear correctly in the event detail in the validator? 
  • If you have alternative ways of viewing content that you wish to support, view those as well. 
    • Note: For example, some sites have a "Quick View" option that is different than a standard page view. Check to ensure the "Viewed Content Event" fires on this view options, just as you did for the standard page view above. 
  • Log in to an account 
    • Check: Does an "Identify Event" fire in the validator? 
    • Check: Do all customer traits appear correctly in the event detail in the validator? 
      • Note: the most important thing to check here is that the "email" trait populates correctly.
    • Navigate to a few different pages while logged in. Does the "Identify Event" fire in the validator upon each new page load? 
  • Enter your email address in any popups, lightboxes, or input forms on the site (such as an email signup form)
    • Check: Does an "Identify Event" fire in the validator? 
    • Check: Does the "email" trait appear correctly in the event detail in the validator?
  • Search for content keywords in any search boxes on the site
    • Check: Does a "Searched Content Event" fire in the validator?

Troubleshooting: Selectors and events in JavaScript 

This section is for users who are not comfortable selecting elements on the page in JavaScript or triggering events based off of user action. Since some events require customization to correctly work on a given site, this is a brief explanation of how to create custom selectors and event handlers for a site.

Selectors in JavaScript 

Several of the scripts in this document require reacting to user events happening on the page. For instance, in an Identify event we have an example script that looks like this: 

var addToCartButton = document.getElementById('addtocart'); 
if(addToCartButton) { 
addToCartButton.addEventListener('click', function() { 
analytics.track('Added Product', { 
//properties here ... 
}, wcapiVersion: '1.0'}); 
}); 
} 

The problem with this snippet is that it is not very generalized. It assumes that you have an element on your page from which email can be fetched called "emailInput". In some cases that assumption will be accurate, but in most cases your setup will be different. Your email element might have a different id or no id. In this case you'll have to generalize the above example to fit your installation.

The 2 easiest ways to select an element in JavaScript are using ids and classes. Ids should be used when there is only a single element on a page that you wish to select, classes can be used when you want to select multiple items. Selecting an element with an id in JavaScript is simple.

To select 

<button id="foo">Do something</button> 

you can call 

var button = document.getElementById('foo'); 

inside of a script. 

Selecting a set of elements with a class isn't too much more complicated. To select each button with the bar class 

<button class="bar">Button 1</button> 
<button class="bar">Button 2</button> 

you can call 

var buttons = document.querySelectorAll('.bar '); 

Note that the argument, '.bar', is the css syntax for selecting elements with the class bar, rather than the plain name used with document.getElementById. If you're familiar with CSS, you can use querySelectorAll to use more advanced selectors using the same syntax as CSS.

Of course in some cases, your site might not currently have classes or ids on all of the elements that you want to select. In that case we suggest adding them. If you're adding classes, we recommend ending the class name with something like "-js" so that you know that it is for selecting with JavaScript and not for use in css styling. So you could change a button like this

<button>Subscribe To Newsletter</button> 

to 

<button class="subscribe-to-newsletter-js">Subscribe To Newsletter</button> 

at which point it would be selectable. 

Event Listeners in JavaScript 

Once you have a reference to an element or a set of elements, we can listen to events on them. In JavaScript this is done with the "addEventListener" function. The 2 main events we may want to listen to in our scripts are click events (for when a customer clicks on a button to perform an action) and change events (for when a customer updates an input with a new value).

Listening to click events on a set of elements with the class "subscribe-to-newsletter-js" looks like this 

var buttons = document.querySelectorAll('.subscribe-to-newsletter-js '); 
for (var i = 0; i < buttons.lengthi++) { 
buttons[i].addEventListener('click', function() { 
//do stuff here when the user clicks on the button 
}); 
} 

Listening to a change event on a single input with id "quantity-js" looks like this 

var quantityInput = document.getElementById('quantity-js'); 
quantityInput.addEventListener('change', function() { 
var inputValue = this.value; 
}); 

Compatibility Note 

"addEventListener" is not supported in versions of Internet Explorer prior to version 9. If you need to support Internet Explorer versions 8 or earlier, you will need to use a more complicated approach, or use a dom library like jQuery (see below). Here's a version of the above snippet that supports Internet Explorer 8. 

var quantityInput = document.getElementById('quantity-js'); 
if (quantityInput.addEventListener) { 
quantityInput.addEventListener('change', function() { 
var inputValue = this.value; }); 
} else if (quantityInput.attachEvent) { 
quantityInput.attachEvent('onchange', function(el) { 
return function() { var inputValue = el.value; }; 
}(quantityInput)); 
} 

jQuery 

WhatCounts’ browse scripts have no external dependencies beyond the analytics script that the main script loads in. But if you already have jQuery or another JavaScript DOM library on your site, it can make the process of selecting events much easier, especially if you have to support old versions of Internet Explorer.

Here's the 2 examples above written in jQuery: 

//trigger function when the user clicks on any element
// with the class subscribe-to-newsletter-js
$('.subscribe-to-newsletter-js').on('click', function() {
//do stuff here when the user clicks on a button
});
//get value of the input of the element with id quantity-js
//every time it changes
$('#quantity-js').on('change', function() {
var inputValue = this.value;
});

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

Powered by Zendesk