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:

FieldDescription
event_typeStringThe name of the event, e.g. "viewed", "liked", "shared". See Event Types below for more details.
attributes optionalObjectAn object containing key:value pairs indicating attributes to be tracked as metadata in this event. See Attributes below for more information.
callback optionalFunctionA 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 TypeSpecial AttributesDescription
viewedresource_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.
likedscore - 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.
sharedresource_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.
commentedresource_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).
purchasedIndicates a user has purchased an item or a set of items from a shopping cart. Automatically triggered by the _bt.trackPurchase function.
updated_cartIndicates a user has made a change to an item or a set of items in their shopping cart.
started_membershipIndicates 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.'}
);