Track an Event

Tracks an event for the current user

❗️

Deprecated API Warning

This page documents a no-longer supported version of the Boomtrain JavaScript Library (versions 4.x and below). The new p13n.js library, documented here is the currently supported library for integrating with ZetaHub.

Events (also known as activities) are used to indicate that a user performed a particular action. These events will appear in your user's profile as recent history, and can be used to create behaviors for triggers and segmentation in the Boomtrain Marketing Engine. As well, these events act as signals for Boomtrain's personalization systems to generate insights and predictive recommendations for your campaigns.

_bt.track(event_type, [attributes], [callback]);

The track call has the following fields:

Field

Description

event_type

String

The name of the event, e.g. "viewed", "liked", "shared". See Event Types below for more details.

attributes optional

Object

An object containing key:value pairs indicating attributes to be tracked as metadata in this event. See Attributes below for more information.

callback optional

Function

A function that is executed after this function completes and the event has been tracked. Note: If an event results in the user leaving the page, be sure to not navigate away until this track call finishes. You can ensure this by adding the page navigation call into the function specified here.

Event Types

While you may specify any event_type, a few are standardized and specially handled by Boomtrain:

Event Type

Special Attributes

Description

viewed

resource_id - If provided, uses this value instead of the current page (default) as the viewed resource.

Indicates a user has viewed a page. Automatically triggered on page load when autoTrack is on (as it is by default). See Getting Started for full details.

liked

score - When a like is paired with a multi-point scale, provide an integer representation of the value provided. If the action indicated is a "dislike" or negative preference, use -1.

Indicates an explicit preference for the current page by the user.

shared

resource_id - If provided, uses this value instead of the current page (default) as the "object" of the share.
target_user_id - The user_id of the target of the share.

Indicates a user has shared the current page/resource (or the one indicated by resource_id) with another user. Emit this once per distinct target user/resource. That is, if a user shares one article with 4 target users, trigger this event 4 times with each target_user_id specified.

commented

resource_id - If provided, uses this value instead of the current page (default) as the "object" that was commented on.
comment_text - The text of the comment.

Indicates a user has commented on the current page/resource (or the one indicated by resource_id).

purchased

Indicates a user has purchased an item or a set of items from a shopping cart. Automatically triggered by the _bt.trackPurchase function.

updated_cart

Indicates a user has made a change to an item or a set of items in their shopping cart.

started_membership

Indicates a new user has signed up. Automatically triggered by the _bt.signup function. See Signup for full details.

Attributes

Provided attributes will be added as metadata on the tracked event.

While attributes can have any form, the following attribute names are reserved and may not be used:

enriched, event_id, geolocation, http_method, identified, identity, is_bot, is_test, properties, referer, status, url, user_agent, href, bsin

If an event is tracked with any of these attribute names, the event will be rejected.

The attribute resource_id can be used to specify the target content that the particular action was taken on. If it is not provided, the event will be attributed to the current page.

Examples

// User viewed the current page
_bt.track('viewed');

// User liked the current page
_bt.track('liked');

// User liked resource123
_bt.track(
  'liked', 
  {'resource_id':'resource123'}
);

// User rated the current page with value 5
_bt.track(
  'liked', 
  {'score':5}
);

// User disliked the current page
_bt.track(
  'liked', 
  {'score':-1}
);

// User shared the current page with sample_user
_bt.track(
  'shared', 
  {'target_user_id':'sample_user'}
);

// User commented on the current page
_bt.track(
  'commented', 
  {'comment_text':'This is my comment.'}
);