Javascript Tracking (v3)

The latest version of the Javascript Tracking Code can be found here.

The Woopra JavaScript is fully asynchronous, meaning it does not wait for a response from the server before allowing the page to continue loading in a visitor’s Web browser, hence it will not slow down your website’s loading time. Woopra also allows you to identify your customers as they convert from anonymous visitors to leads or customers by simply providing an email address. By identifying a customer, Woopra will be able to aggregate all the visits of that customer by email across multiple devices. Lastly, Woopra lets you see beyond pageviews and track very specific activities including signups, payments, logins in the form of Custom Event Data.

1. Basic Javascript Tracking

In order to activate tracking by Woopra’s servers you must insert a JavaScript snippet into the HTML code on each page you wish to be tracked. Tracking occurs when a visitor’s Web browser executes the Woopra JavaScript and pings the Woopra servers. Custom visitor data, or custom events, can be added to Woopra and the reference below will demonstrate how this is done.

As a result, asynchronous JavaScript code can be inserted at any location of the document rather than always needing to be inserted in the page footer. This increases the chances that a page view is going to be tracked before the visitor leaves the page.

The basic JavaScript snippet to insert into a page for tracking purposes is as follows:

<script>
function woopraReady(tracker){
	tracker.setDomain('yourdomain.com');
	tracker.setIdleTimeout(300000);
	tracker.track();

	return false; // when we return false, the Woopra script will not call the track() function again.
}

(function(){
var wsc=document.createElement('script');
wsc.type='text/javascript';
wsc.src=document.location.protocol+'//static.woopra.com/js/woopra.js';
wsc.async=true;
var ssc = document.getElementsByTagName('script')[0];
ssc.parentNode.insertBefore(wsc, ssc);
})();
</script>

2. Adding Custom Visitor Data

In order to identify a customer, you need to send their email address to Woopra as a custom visitor property. It should be added before the javascript snippet and formatted in the following manner:

<script type="text/javascript">

function woopraReady(tracker){
	tracker.setDomain('yourdomain.com');
	tracker.setIdleTimeout(300000);

	tracker.addVisitorProperty('email','john@smith.com');
	tracker.addVisitorProperty('name','John Smith');	

	tracker.track();
	return false;
}

(function(){
var wsc=document.createElement('script');
wsc.type='text/javascript';
wsc.src=document.location.protocol+'//static.woopra.com/js/woopra.js';
wsc.async=true;
var ssc = document.getElementsByTagName('script')[0]; 
ssc.parentNode.insertBefore(wsc, ssc);
})();
</script>   

Standard attributes which will be displayed in the Woopra live visitor data include:

  • email – Which displays the visitor’s email address and it will be used as a unique identifier instead of cookies.
  • name – Which displays the visitor’s full name
  • company – Which displays the company name or account of your customer
  • avatar – Which is a URL link to a visitor avatar

But you can define any attribute you like and have that detail passed from within the visitor live stream data when viewing Woopra.

3. Sending Custom Actions (custom events)

Woopra also allows you to track Custom Actions in addition to simple pageviews. Let’s say you are running a website that allows a user to perform an action without having to reload the whole page. You can track these actions using Woopra’s Custom Events.

Important: The attribute name of each custom event is required. It will be used to identify the nature of the custom events. (e.g. payment, transaction, signup, subscription, cart, etc…)

In order to send custom event data to Woopra it should be added before the javascript snippet and formatted in the following manner:

<script type="text/javascript">

function woopraReady(tracker){
	tracker.setDomain('yourdomain.com');
	tracker.setIdleTimeout(300000);

	tracker.pushEvent({
		name: 'signup', // required
		username: 'johnsmith',
		company: 'Woopra, Inc.'
	});

	return false;
}

(function(){
var wsc=document.createElement('script');
wsc.type='text/javascript';
wsc.src=document.location.protocol+'//static.woopra.com/js/woopra.js';
wsc.async=true;
var ssc = document.getElementsByTagName('script')[0]; 
ssc.parentNode.insertBefore(wsc, ssc);
})();
</script>   

The code above will track a custom event titled “signup”, and provides some more information like the username and company of the
account created. Just imagine all of the custom events that can be tracked on your website: add creditcard, add comment, request demo, ad click, etc…

What’s even more important about custom events is that you can always run custom reports about the data you pass to Woopra, so for the example given above, you could get the number of signups by company.

Custom URL Tracking (With optional custom meta data)

If you wish to track the full page URL (containing query part), or to add custom event-level data to the page view, your script would follow this format:

<script type="text/javascript">
function woopraReady(tracker){
	tracker.setDomain('yourdomain.com');
	tracker.setIdleTimeout(300000);

	tracker.trackPageview({
		url: window.location.pathname + window.location.search,
		title: document.title,
		author: 'John Doe',
		category: 'Technology'
	});

	return false;
}

(function(){
var wsc=document.createElement('script');
wsc.type='text/javascript';
wsc.src=document.location.protocol+'//static.woopra.com/js/woopra.js';
wsc.async=true;
var ssc = document.getElementsByTagName('script')[0]; 
ssc.parentNode.insertBefore(wsc, ssc);
})();
</script>   

Custom Events on mouse click (or other events)

Woopra allows to send custom events after the page has loaded, and on certain events you wish to track.ex:

someElement.onclick = function() {
	woopraTracker.pushEvent({
		name: 'Event Name',
		artist: 'Dave Brubeck',
		song: 'Take Five'
	}); 
};

4. Customization

Woopra allows users to customize settings in order to provide flexibility for a wide variety of environments. Doing so is as simple as calling a function within the tracker object. The two settings which can be customized by end users are the idle timeout and the ability to combine subdomains.

Custom Timeout Setting

The default Woopra visitor timeout – or the time after which Woopra ignores inactive visitors on a website – is set at 4 minutes. This means that if a user opens your Web page and then leaves it open in another browser window, Woopra will report that the visitor has gone away after 4 minutes of inactivity on that page (no page scrolling, clicking or other action).

If you would like to increase or decrease the idle timeout setting you define object woo_settings in milliseconds. For example, to set the default timout to 10 minutes it would be (10 min x 60 sec x 1000):

tracker.option('idle_timeout', 600000);

Keep in mind that increasing this number will not only show you more visitors on your site at a time, but will also skew your average time on a page reporting. So it’s important to keep the number reasonable in order to accurately make predictions.

Custom Subdomain Aggregation

Some Woopra users wish to aggregate subdomain traffic within the domain statistics so that they can run combined reports across the entire website. In this case, you need to define an object to tell Woopra to combine the statistics. For example:

tracker.option('domain', 'myrootdomain.com');

If this was running on a subdomain such as shop.mydomain.com it would combine the statistics with the root domain mydomain.com. This method can only be used to combine a subdomain with it’s own root domain, and no other combination.

Other Tracker Options

Javascript Default Description
tracker.option('cookie_name', 'woopraTracker'); woopraTracker Change the name of the cookie stored by Woopra
tracker.option('cookie_domain', 'myrootdomain.com'); n/a Change the tracking cookie domain
tracker.option('cookie_path', '/'); / Change the tracking cookie path
var expires = new Date();
expires.setDate(expires.getDate() + 365);
tracker.option('cookie_expire', expires);
365 Change the tracking cookie expiration
tracker.option('ping', true); true Enable/Disable the periodic pings
tracker.option('ping_interval', 12000); 12000 milliseconds Change ping interval
tracker.option('download_tracking', true); true Enable/Disable download tracking
tracker.option('outgoing_tracking', true); true Enable/Disable outgoing links tracking
tracker.option('download_pause', 200); 200 milliseconds Change download pause (to guarantee the tracking request is sent)
tracker.option('outgoing_pause', 200); 200 milliseconds Change outgoing link pause (to guarantee the tracking request is sent)

A day of setup. A lifetime of insights.

Try Woopra for free. No credit cards. No obligations.