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)

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 

Queued actions are flushed and sent to woopra's tracking servers every time the user closes the tab/window or switches away from the tab, navigates away from the page, woopra.push() is called, an action has been cancelled, or a file download/outgoing link/form track/click track event is captured.

lifecycle

String: "page" | "action"

Defaults 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 of page will be tracked again if the user is inactive longer than timeout. The action has the same properties with an extra returning property with the value of 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"
    });
};