Javascript API

The Javascript API provides a simple way to track website activity.

The tracking script

Before you can use the API, you must include the project's tracking script in the HEAD section of all the pages you wish to collect data on. This script can be found on the Setup / Projects menu item.

Initialize the library

The script requires the project id to be placed in the following line of code:

var gator = new Aggregator( [ your project id ] );

logEvent

Log an event, like a session start, signup or login.

Syntax:

gator.logEvent( eventName, [ data ] )

Parameters:

`eventName`	The event name, like 'Purchase' or 'Signup'.
`data`	(optional) Extra data to add to the event. For example, revenue, user data or item codes. This should be passed as a JavaScript object literal, like: `{ revenue: 9.95, tax: 1.89 }`.

Examples:

gator.logEvent('Signup');

gator.logEvent('Signup', { firstName: 'Mary' });

gator.logEvent('Item Purchased', { itemName: 'A26533', itemQuantity: 1 } );

logPageview

This functions logs a website page view. It is part of the default tracking script, but can be placed anywhere on the page, even in multiple places. For example, in addition to standard page views, you can use this function to track Ajax requests from various spots on a page.

Syntax:

gator.logPageview( [ pageName ] )

Parameters:

pageName (optional) The page name. This defaults to the current page, but can be overridden with this value.

Example:

gator.logPageview('helpdialog.html');

logOutbound

This functions logs an outbound link event. For more information and examples click here.

Syntax:

gator.logOutbound( eventName, href or callback, [ data ] )

Parameters:

`eventName`	The event name, like 'Exited From Home Page' or 'Signup to Pay'.
`href`	The URL of the link to navigate to after the event is logged.
`callback`	A function to call after the event is logged.
`data`	(optional) Extra data to add to the event. For example, user data or item codes. This should be passed as a JavaScript object literal, like: `{ accountId: 'A123' }`.

Example of logging an exit from a signup page:

<a href="/somepage" onclick="gator.logOutbound('Exited Signup', this.href)">Leave Page</a>

Example of using a callback:

gator.logOutbound('Contact',
function() {
console.log('this is called after the event is logged');
window.location = '/nextpage';
}
);

ready

Sets a callback function for when the gator library is fully loaded. This is not needed except in special circumstances, since most API calls are queued until the library is ready.

Example:

gator.ready(function () { console.log('Library loaded!'); }

setPerson

Sets the user's identity, like an email address or a customer id. This is useful for reporting on individual user activity. Once you identify a person, the identity is automatically carried forward for all sessions for the person on the same device. If the person uses multiple devices, you can identify the person across the devices to get a full profile of the person's activity.

Syntax:

gator.setPerson( personId, [ data ] )

Parameters:

`personId`	The person's unique id, like an email address or customer id.
`data`	(optional) Data to attach to the person. If this is set, it will completely overwrite the data for the person. To update a person's data, use the `updatePerson` call. See below for examples.

Example - Set the session's person. This id can be set after a login, or via a social API.

gator.setPerson('jane@corp.com');

Example - Set the session's person and add some data to the person.

gator.setPerson('jane@corp.com', { firstName: 'Jane', lastName: 'Smith', loginTime: new Date() });

updateEvent

Sets/updates data from an event that was previously recorded. This could be used to update timings, or quantities. You must have the unique id of the original event in order to update the event.

Syntax:

gator.updateEvent( id, data )

Parameters:

`id`	The event's unique id, like 'ORD0001'. This is originally set with the `logEvent` call by setting the `id attribute.`
`data`	What to update on the event. See below for examples.

Examples:

gator.updateEvent('VIDEO00331', { title: 'Car ad' });

gator.updateEvent('VIDEO00331', { viewingTime: 18 });

Updates also support the following update operators on numeric data:

`$inc`	Increments the value of the attribute by the specified amount.
`$mul`	Multiplies the value of the attribute by the specified amount.
`$min`	Only updates the attribute if the specified value is less than the existing field value.
`$max`	Only updates the attribute if the specified value is greater than the existing field value.
`$unset`	Deletes an attribute.

Use the following syntax for update operators:

{ operator: { attribute name: value } }

Example - To add 5 seconds to the user's viewing time of a video:

gator.updateEvent('VIDEO00331', { $inc: { viewingTime: 5 } });

Example - To apply the maximum viewing time to 60 seconds:

gator.updateEvent('VIDEO00331', { $max: { viewingTime: 60 } });

updatePerson

Updates/merges the data on an existing person and sets the person for the session. If the person doesn't exist, it is created.

Syntax:

gator.updatePerson( personId, data )

Parameters:

`personId`	The person's unique id, like an email address or customer id.
`data`	What to update on the person. See below for examples.

Examples:

gator.updatePerson('Customer 123', { email: 'jane@corp.com' });

gator.updatePerson('Customer 123', { firstName: 'Jane', lastName: 'Smith', viewingTime: 18 });

Updates also support the following update operators on numeric data:

`$inc`	Increments the value of the attribute by the specified amount.
`$mul`	Multiplies the value of the attribute by the specified amount.
`$min`	Only updates the attribute if the specified value is less than the existing field value.
`$max`	Only updates the attribute if the specified value is greater than the existing field value.
`$unset`	Deletes an attribute.

Use the following syntax for update operators:

{ operator: { attribute name: value } }

Example - Add one to the number of logins for a person:

gator.updatePerson('Customer 123', { $inc: { logins: 1 } });

Example - To apply the maximum viewing time of an offer to 10 seconds:

gator.updatePerson('Customer 123', { $max: { offerWatchedTime: 10 } });

updateSession

Sets/updates data on the current session.

Syntax:

gator.updateSession( data )

Parameters:

data What to update on the session. See below for examples.

Examples:

gator.updateSession({ viewedAd3: true });

gator.updateSession({ timeOnAd3: 12 });

Updates also support the following update operators on numeric data:

`$inc`	Increments the value of the attribute by the specified amount.
`$mul`	Multiplies the value of the attribute by the specified amount.
`$min`	Only updates the attribute if the specified value is less than the existing field value.
`$max`	Only updates the attribute if the specified value is greater than the existing field value.
`$unset`	Deletes an attribute.

Use the following syntax for update operators:

{ operator: { attribute name: value } }

Example - To add 5 seconds to the user's viewing time of an ad:

gator.updateSession({ $inc: { timeOnAd3: 5 } });

Example - To remove an attribute from a session:

gator.updateSession({ $unset: { trial: 1 } });