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
  5. Track Forms

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:

!function(){var a,b,c,d=window,e=document,f=arguments,g="script",h=["config","track","trackForm","trackClick","identify","visit","push","call"],i=function(){var a,b=this,c=function(a){b[a]=function(){return b._e.push([a].concat(Array.prototype.slice.call(arguments,0))),b}};for(b._e=[],a=0;a<h.length;a++)c(h[a])};for(d.__woo=d.__woo||{},a=0;a<f.length;a++)d.__woo[f[a]]=d[f[a]]=d[f[a]]||new i;b=e.createElement(g),b.async=1,b.src="//static.woopra.com/js/w.js",c=e.getElementsByTagName(g)[0],c.parentNode.insertBefore(b,c)}("woopra");

// configure tracker
 domain: 'mybusiness.com'

// track pageview


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:

    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. Calling identify() does not send anything to Woopra, in order to send the properties and identify the visitor, you need to call track() after you identify().


Argument Type Description
properties Object An object of any properties you want to save for this current visitor.


// configure

// Identify customer
    email: 'johndoe@mybusiness.com',
    name: 'John Doe',
    company: 'My Business'

// 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().


Argument Type Description
callback Function A callback function to run after the tracking function has been successfully received by Woopra


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.

track(eventName, [properties], [callback])

Argument Type Description
eventName String The name of the event that you are tracking
properties Object An object of any properties you want to track with the event
callback Function A callback function to run after the tracking function has been successfully received by Woopra/td>

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



// 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 Forms

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 this, Woopra provides a function to automatically track forms and then submit the form after the form is tracked. Woopra will track all input fields inside of a <form> except password inputs, which are automatically excluded, and any exclusions defined in the options object.

Note: older snippets will need to call woopra.call(‘trackForm’, ‘Register’, ‘registration’, { … })

trackForm(eventName, formName, [options])

Argument Type Description
eventName String The name of the event that you are tracking
formName String The id attribute of your form. Start with a #.
options Object An options object


Option Default Description
exclude [] An array of form field names to exclude from tracking.


<form id="registration" action=".">
Full Name: <input type="text" name="fullname">
Email: <input type="text" name="email">
Password: <input type="password" name="password">
Secret: <input type="text" name="secret">

// '#registration' must match the `id` field of your `<form>`.
// All `<input>` fields that are type="password" will be automatically excluded 

woopra.trackForm('Register', '#registration', {
  exclude: ['secret']

Need any help? Contact support