JavaScript API Client

Installation

Install the Calq API client by adding the following JavaScript snippet to your page in between your <head> and </head> tags.

You will need to add your Calq project's write key to the snippet where it says YOUR_WRITE_KEY_HERE. You can find your write key from the project settings option inside Calq.

The snippet prepares stub methods so you can use Calq before it has finished loading. The main library will be loaded in the background asynchronously (non-blocking) so your website will continue to load quickly.

Tracking actions

Calq performs analytics based on actions that user's take. You can track an action using calq.action.track. Specify the action and any associated data you wish to record.

// Track a new action called "Product Review"
calq.action.track(
    "Product Review",
    { "Rating": 9.0 }
);

The second parameter is free-form and lets you send additional data about the action. This extra data can be used to make advanced queries within Calq.

Tracking revenue actions

Actions sometimes have revenue amount associated with them such as an item sale or sponsored banner click. Calq provides a special method for these actions called calq.action.trackSale. This includes the same parameters as calq.action.track but includes 2 extra for a currency code and revenue amount.

// Track a sale action worth 9.99 USD
calq.action.trackSale(
    "Product Sale",
    { "Product Id": 149, "Product Name": "Dinosaur T-Shirt XL" },
    "USD", 
    9.99
);

Using the calq.action.trackSale method will accurately attribute revenue to the current user. This allows Calq to produce revenue reports including user lifetime values (LTV).

If you want to track a refund then specify a negative sale amount.

Tracking links & forms

Sometimes you might want to add tracking to an outbound link or a form. In this case you might find your page reloads before Calq has had time to communicate with our API server. To overcome this we provide another method called calq.action.trackHTMLLink. This works exactly the same as calq.action.track but will wait until any API calls are complete before returning (i.e. blocking calls).

<a href="http://calq.io" onclick="calq.action.trackHTMLLink('Link', { 'Target': 'Calq' });">Example Link</a>

Tracking page views

Calq will not automatically track page views. To track a page view action for the current page you will need to call calq.action.trackPageView. This will create a new event called "Page View" and include the page title and URL.

// Track a page view event for the current page
calq.action.trackPageView();

Global action properties

There are often properties that you will want to include with every action you send to Calq. These properties are normally information about the environment, such as the device being used, or information about the user, such as age, gender, or referrer.

To save you specifying this information with each action, Calq lets you set global properties with calq.action.setGlobalProperty. Global properties are saved to the client (as a cookie) so they will also persist between sessions.

// Set the "Referral Source" property for all new actions
calq.action.setGlobalProperty("Referral Source", "Google Campaign");

The Calq JS client will also automatically add the following useful global properties with each action:

$device_agent The user agent of the browser being used.
$device_mobile Whether the device is a mobile device such as a phone or tablet.
$device_os The operating system running on the device (Windows, OSX, iOS, Android etc).
$device_resolution The screen size of the device being used.
$country The user's current country (from IP address).
$region The user's region within their country (from IP address).
$city The user's estimated city (from IP address - not always accurate particularly on mobile carriers).

Note that properties starting with a $ are special properties. Your custom properties should not start with a $.

Identifying users

All users are assigned a unique identifier by the Calq client. You may however want to assign a different ID, such as your own user ID from your database. A common case for this is when a user registers or logs in.

To assign a new ID to the current client session use calq.user.identify.

// Identify the current user as 12345678
calq.user.identify("12345678");

A user may have sent actions before you call identify. In this case the previous actions will be automatically associated with the new ID (going back a max of 14 days). This means if a user performs some actions in your application, and then logs in after, those actions are correctly attributed.

Once you have called identify you should not attempt to assign a different ID to the same user again. Calq will deliberately reject this with an error. Calling identify with the existing Id is allowed and will be silently ignored.

Logging out

When users logout of your website you normally want to stop associating tracked actions with that user. To do this you will need to clear the Calq session using calq.user.clear.

// Generate a new session to track subsequent actions (logout the current user)
calq.user.clear();

Using calq.user.clear generates a new session. Actions performed after calling clear will be tracked as a new user, although if the same user logs back in again they can be correctly associated using calq.user.identify.

User information

In addition to sending data about actions, you can also send properties about users themselves. This allows you to analyze your audience based on who they are, rather than what they did.

You can set user properties using calq.user.profile. User properties are free-form so you can store whatever matters to you. However, just like actions, there are also some special properties too.

// Set some persistent profile properties for the current user
calq.user.profile(
    { "Company": "MegaCorp", "$email": "super_customer1@notarealemail.com" }
);

You must call calq.user.identify before you can store profile information.