The Woopra JavaScript tracking code is designed for easy customization. It can be tailored to identify your website visitors and track any custom events across your site or application.
In order to activate tracking by Woopra’s servers, you must insert the javascript snippet into the <head> 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.
Javascript code is asynchronous and should be inserted in the <head> tag rather than always needing to be inserted in the page footer. By placing it in the header, the pageview will be tracked before the visitor leaves the page.
Default Pageview Event
Calling woopra.track() with no arguments sends the default built-in "pageview" event. Some of the options that you set in the tracker config are for this built-in event.
woopra.track() (No Arguments)
woopra.track() (No Arguments)window.woopra.track();
// The line above is equivalent to:
woopra.track("pv", {
url: window.location.pathname,
title: document.title
});
Tracking Custom Actions
Woopra also allows you to track any type of Custom Actions in addition to pageviews. Let’s say you're running a website where visitors can signup for your service. You can track these actions using Woopra’s Custom Actions. To track custom actions, you can define the action name string and the properties associated with that action object:
woopra.track(eventName<lowercase string>, [properties]<object>, [callback]<function>)
or
woopra.track(eventName<lowercase string>, [properties]<object>, [options]<object>)
| Argument | Type | Description |
|---|---|---|
| eventName | String | The name of the event that you are tracking. Should be lower case. |
| properties | Object | An object of any properties you want to track with the event. |
| callback | Function or Object | A callback function to run after the tracking function has been successfully received by Woopra. See below "options" for more details. |
All event names and properties should be lowercase.
It is best practice to use
_instead of spaces.But don't worry, you can always customize how events are displayed, described and aggregated throughout Woopra in your schemas. You can even create sentence templates using event property values for when an instance of the event is shown in the Woopra interface. Think: "James Kirk Purchased a Starship for 1000 bitcoin" from your template:
${visitor.full_name} Purchased ${action.product_name} for ${action.item_price} ${action.currency}
Options
Optionally, you can pass, as the last argument to woopra.track() a callback function that will be called after the tracker has received the response from the tracking server.
This can be useful if you need to access Woopra labels data (at window.woopra.labels) but only after it has been evaluated and updated by the tracking server.
You can also use this as a callback to know not only when the snippet has loaded the tracker object, but when the very first Woopra tracking action has successfully been completed. Essentially it guarantees that the Woopra tracker object has been loaded which may be important even though you can in fact call woopra.track() and the other methods as soon as the snippet code has run.
In addition, the callback can be an object as well and use the following options:
| Callback Options as Object | |
|---|---|
onError | Callback is called where there's an error during tracking. |
onBeforeSend | Receives a WoopraAction object as an argument. For example, if you want to cancel scroll depth or update a property before sending. See WoopraAction section below for more details. |
onSuccess | Callback option, receives a WoopraAction object as an argument on success. See WoopraAction section below for more details. |
timeout | Option: Number. The default uses woopra.config('idle_timeout')). |
queue | When true, forces the action to be queued and sent as a beacon. Uses navigator.sendBeacon instead of |
lifecycle | String: page | actionDefaults to page for pv, otherwise action.As page lifecycles will update durations and % or page scrolling through the lifecycle of the page. |
retrack | Boolean: default = false Actions with lifecycle will be tracked again if the user is inactive longer than the timeout. The action has the same properties with an extra returning property with the value of true.In other words, if the user is idle for too long (default 10 min), instead of updating the current action with the new data, a new pv event will be tracked with returning = true. |
Note that errors thrown in callbacks will be caught and logged via (console.error)
WoopraAction
The object returned from onSuccess and onBeforeSend callbacks.
| Callback | Example | Description |
|---|---|---|
action.id | idptnc = action.id | Each action generates an action ID. |
action.update | action.update({ updated: 'property' })Equivalent to woopra.update(action.id, { updated: 'property' }) | Used to update a property on callback. |
action.cancel() | Equivalent to:woopra.cancelAction(action.id) | Cancels an action on callback |
Example
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 signups by company.
Don't Forget Your Schemas
When you track custom events, remember to update your schema on Woopra. Woopra will auto-generate a schema for the first event of that name that comes in, but you can add a display name and declare the types of values passed as event properties. 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"
});
};