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.
- Basic JavaScript Tracking
- Configure Tracker
- Identify Customers
- Track Custom Events
- Track Forms
- 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/t/5.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()
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.
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.
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.
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 – Experimental
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 solution 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
There are two possible approaches to the configuration.
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.