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
  6. Cross-Domain Tracking

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

All properties should be lowercase

identify(properties)

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

Example

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

push([callback])

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

Example

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.

All events and properties should be lowercase

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:

Examples

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 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: Do not set name for any inputs/buttons to the following: “submit”, “method”, “length”
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

Options

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

Example

<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">
</form>

// "#registration" must match the `id` field of your `<form>`.
// All `<input>` fields that are type="password" will be automatically excluded 
// Do not set name for any inputs/buttons to the following: "submit", "method", "length"

woopra.call("trackForm", "Register", "#registration", {
  exclude: ["secret"]
});

Cross-Domain Tracking

Many site owners would benefit greatly from the ability to monitor customer behavior across their different domains, as this allows a much more holistic understanding of customer’s relationships with your business. In addition, cross-domain tracking would be extremely useful in situations where anonymous users go from domain1.com to domain2.com and ultimately identify themselves on domain2.com, essentially allowing identification across both sites.

Tracking visitor behaviour across your different domains poses a difficult challenge, however. A unique ID is required in order to associate the actions of anonymous visitors with the correct profile. This ID is stored and retrieved via cookies by your web browser. However, cookies from domain1.com cannot be directly accessed by domain2.com.

While it is not yet in production for all of our users, we offer an experimental script to our customers who wish to try it, which will allow tracking of visitors across domains.

Woopra’s cross-domain tracking script allows you to easily associate a the visitor’s unique ID across two different domains by passing it through a URL. As long as the cross-domain script is present on both domains, the visitor ID will be written to the cookie with what was passed in from the URL, enabling Woopra to identify the same visitor ID and associate actions with the same visitor profile.

Please read the Considerations section for extra information regarding the use of this feature.

Usage

In order to use this feature you must first include this specific cross-domain snippet on each of the domains

Note: this experimental snippet is different from the snippet in our documentation section).
<script>
!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/t/5.js",c=e.getElementsByTagName(g)[0],c.parentNode.insertBefore(b,c)}("woopra");
</script>

From there you have two options:

You can manually decorate your URLs using woopra.decorate(url) which will return to you the URL with the user’s cookie appended to it. An example would be when a user hovers over a link, replace the URL with a decorated URL.

The other option is to have the Woopra tracker take care of this automatically by configuring the cross_domain option. This option takes in an array of domain names that will be used to auto-decorate any links that go to that domain.

woopra.config({
   domain: "domain1.com",
   cross_domain: "domain2.com"
});

If you place this snippet on domain1.com and links to domain2.com are present on the page, the Woopra script will automatically change the URL to contain their cookie id when users hover over these links. This will enable domain2.com to associate the user if they were to be identified on domain2.com.

Considerations

Unique Users

Since Woopra will merge visitor profiles across your domains, you can expect to see a lower unique visitor count. However, be careful with users sharing URLs with their cookie IDs. If this happens then multiple users will be sharing the same ID and have all of their profiles merged.

You can pass the option hide_xdm_data: true to the Woopra tracker to have Woopra attempt to hide the cookie in the URL after it is used. This is accomplished by using the browser’s pushState functionality (only supported in newer browsers). This may cause issues with your website’s framework if it uses pushState.

Previous Anonymous Visitor Profile

Once an anonymous visitor is returned to a URL with a new ID, their old profile will no longer be associated with that visitor.
For example:

* Visitor goes to domain2.com and is assigned an id:123
* Visitor goes to domain1.com and is assigned an id:abc
* Visitor clicks a link on domain1.com that takes them back to domain2.com. When this happens, the the visitor on domain2.com will now have an id:abc instead of id:123. The behavioral timeline from when the visitor id was 123 will remain in that profile, but will not be associated with their new profile.

This only applies to anonymous users since Woopra will merge the profiles of identified visitors.

Do you know what your customers are doing?
Find out in 5 minutes.

Start your 30-day free trial. No credit cards. No obligations.

Try it out