Have a question?

JavaScript SDK

The Woopra JavaScript tracking code is designed for easy customization. It can be tailored to identify your website visitors and track any customer action on your site.

  1. Basic JavaScript Tracking
  2. Configure Tracker
  3. Identify Customers
  4. Track Custom Events

Basic JavaScript Tracking

In order to activate tracking by Woopra’s servers you must insert a JavaScript snippet into the element 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, preferably in the <head> tag 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(){
var t,i,e,n=window,o=document,a=arguments,s="script",r=["config","track","identify","visit","push","call"],c=function(){var t,i=this;for(i._e=[],t=0;r.length>t;t++)(function(t){i[t]=function(){return i._e.push([t].concat(Array.prototype.slice.call(arguments,0))),i}})(r[t])};for(n._w=n._w||{},t=0;a.length>t;t++)n._w[a[t]]=n[a[t]]=n[a[t]]||new c;i=o.createElement(s),i.async=1,i.src="//static.woopra.com/js/w.js",e=o.getElementsByTagName(s)[0],e.parentNode.insertBefore(i,e)
})("woopra");

// configure tracker
woopra.config({
 domain: 'mybusiness.com'
});

// track pageview
woopra.track();
</script>

Configuration

The Woopra tracker can be customized using the config function. Find below the list of options:

Option Default Description
domain Website domain Website hostname as added to Woopra
cookie_name wooTracker Name of the cookie used to identify the visitor
cookie_domain Website domain Domain scope of the Woopra cookie
cookie_path / Directory scope of the Woopra cookie
cookie_expire 2 years from last action Expiration date (Date object) of the Woopra cookie
ping true Ping woopra servers to ensure that the visitor is still on the webpage
ping_interval 12000 Time interval in milliseconds between each ping
idle_timeout 300000 Idle time after which the user is considered offline
download_tracking true Track downloads on the web page
outgoing_tracking true Track external links clicks on the web page
outgoing_ignore_subdomain true Do not include links to subdomains as outgoing links
download_pause 200 Time in millisecond to pause the browser to ensure that the event is tracked when visitor clicks on a download url.
outgoing_pause 400 Time in millisecond to pause the browser to ensure that the event is tracked when visitor clicks on an outgoing url.
ignore_query_url true Ignores the query part of the url when the standard pageviews tracking function track()
hide_campaign false Enabling this option will remove campaign properties from the URL when they’re captured (using HTML5 pushState).

The config function supports key/value singleton argument:

woopra.config('cookie_name', 'my_business_cookie');

Or an object of keys and values:

woopra.config({
    download_tracking: false,
    outgoing_tracking: false,
    ping_interval: 30000
});

Identifying Customers

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 track() function and formatted in the following manner:

// configure
woopra.config(...);

// Identify customer
woopra.identify({
    email: 'johndoe@mybusiness.com',
    name: 'John Doe',
    company: 'My Business'
});

// track
woopra.track();

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.

Note that if you wish to identify a visitor without sending a tracking event, you can call the function push().

woopra.identify('email', 'johndoe@mybusiness.com').push();

Tracking Actions

Woopra also allows you to track Custom Actions in addition to simple pageviews. Let’s say you are running a website where people can signup. You can track these actions using Woopra’s Custom Events.

The track() function will track the pageview of the current page if no arguments are provided:

woopra.track();

// The line above is equivalent to
woopra.track('pv', {
    url: window.location.pathname,
    title: document.title
});

To track custom actions, you can define the action name string and the properties associated with that action object:

woopra.track('signup', {
    company: 'My Business',
    username: 'johndoe',
    plan: 'Gold'
});

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: payment, comment, logout, email, 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 signup by company.

When you track custom events, remember to update your schema on Woopra. That will help the rest your team to identify the events being tracked and Woopra will automatically build reports out of the box based on the event properties.

Below is another example to track when people click on the play button with id="play-button":

document.getElementById('play-button').onclick = function() {
	woopra.track('play', {
		artist: 'Dave Brubeck',
		song: 'Take Five',
		genre: 'Jazz'
	});
};

Tracking Actions

Woopra allows you to track Actions when forms are submitted. Tracking forms is a well known problem as the page is reloaded as the tracking events are being sent. To get around that problem, Woopra allows a callback in the push function, so the form is not submitted until the event is fully tracked.


$('#form2').one('submit', function(e) {
    var name = $('#name_field_id').val();
    var email = $('#email_field_id').val();
    var form = $(this);
 
    if (name && email) {
        woopra.identify({
            name: name,
            email: email
        }).push(function() {
            form.submit();
        });
    }
    return false;
});

Need any help? Contact our Data Jedis