Track an Event

Tracks an event for the current user

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

Event tracks are non-blocking JavaScript calls.

bt('track', eventType, properties, settings={});

The track call has the following fields:

FieldTypeDescription
eventTypeStringThe name of the event, e.g. "viewed", "liked", "shared".
propertiesObjectA JSON object containing key:value pairs indicating properties to be tracked as metadata in this event. See Properties below for more information. An empty JSON object {} should be provided if there are no properties to be tracked with the event.
settings optionalObjectSettings specific to this event. Currently supports specification of onComplete, onSuccess, and onFailure callback functions. See Settings below for more information.

Automatically-Populated Properties

The following properties will be populated automatically with each event, but may be overridden with values that you specify.

PropertyTypeDescription
idStringBy default uses the current page as the viewed resource.
resourceTypeStringBy default uses the resource type of the current page as the viewed resource's type.
urlStringBy default uses the current page's URL.
modDateISO-8601 Timestamp String or Epoch Time in seconds or millisecondsBy default uses the current page's modification date. If provided, must be an ISO-8601 timestamp or the epoch time.

Event Types

While you may specify any eventType, a few are standardized and specially handled by Zeta's systems. Also note that certain eventTypes will use properties in a special way:

Viewing a Page or Resource

eventType: viewed

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.

bt('track', 'viewed', {});
bt('track', 
   'viewed', 
   {id: 'yourId', resourceType: 'yourResourceType', url: 'https://example.com'}
  );

Completing a Purchase

eventType: purchased

Indicates completion of a transaction in which the user has purchased one or more products.

purchased events must contain a top-level property called shoppingCartItems. This property must be formatted as an array of JSON objects representing purchased items.

Each element of shoppingCartItems must have the following properties:

id: A string representing the ID of the item being purchased.
resourceType: A string representing the resource type for this item.
price: A number representing the price of this item.
quantity: A number representing the quantity of this item purchased.

Note that shoppingCartItems may contain other properties with any additional JSON data as well.

bt('track', 
   'purchased', 
   {
    shoppingCartItems: [ 
     {id: 1234, resourceType: 'myProduct', price: 1.25, quantity: 2}, 
     {id: 2345, resourceType: 'myProduct', price: 2.8, quantity: 1, sale_discount: 0.90}
    ], 
    promoCode: 'StRSiTb'
   }
  );

Updating a Shopping Cart

eventType: updated_cart

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

updated_cart events must contain a top-level property called shoppingCartItems. This property must be formatted as an array of JSON objects representing all items now in the user's cart.

Each element of shoppingCartItems must have the following properties:

id: A string representing the ID of the item.
resourceType: A string representing the resource type for the item.
price: A number representing the price of this item.
quantity: A number representing the quantity of this item now in the cart.

Note that shoppingCartItems may contain other properties with any additional JSON data as well.

bt('track', 
   'updated_cart', 
   {
    shoppingCartItems: [ 
     {id: 1234, resourceType: 'myProduct', price: 1.25, quantity: 2}, 
     {id: 2345, resourceType: 'myProduct', price: 2.8, quantity: 1, sale_discount: 0.90}
    ], 
    promoCode: 'StRSiTb'
     }
  );

Signing Up

eventType: signed_up
Tracks that the user has signed up for an email newsletter, signed up for an account, or any other event that signifies a "new" user.

This track type will automatically execute an updateUser call with each of the given properties before tracking the event. See Update a User for more details).

At least one of the two following properties must be provided:

PropertyTypeDescription
emailStringA string representing the new user's email address.
user_idStringA string representing a consistent primary identifier for this user.
bt('track', 
   'signed_up', 
   {user_id: 'sample-user'}
  );
bt('track', 
   'signed_up', 
   {
    email: '[email protected]',
    newsletter: 'My Newsletter',
    frequency: 'Weekly',
    first_name: 'John',
    last_name: 'Smith'
     },
  );
bt('track', 
   'signed_up', 
   {email: '[email protected]'}
  );

Executing a Search

eventType: searched

Tracks that the user has executed a search on your website.

The following properties should be provided in a searched event when available:

PropertyTypeDescription
queryStringA string representing what the user searched for in a search text field.
bt('track', 
   'searched', 
   {query: 'iPhone X'}
    );

Liking or Rating a Page or Resource

eventType:liked

Indicates an explicit preference or rating for the specified page/resource by the user.

The following properties should be provided in a liked event when available:

PropertyTypeDescription
scoreNumberWhen the event indicates a rating on a multi-point scale, provide an integer representation of the value provided. If the action indicated is a "dislike" or negative preference use -1.
minScoreNumberWhen the event indicates a rating on a multi-point scale, provide an integer that represents the minimum rating possible. If not specified, minimum score is assumed to be 1.
maxScoreNumberWhen the event indicates a rating on a multi-point scale, provide an integer that represents the maximum rating possible.
toStringA string representing the service or external destination of the share, for example, "facebook" or "twitter"
bt('track',
   'liked',
   {}
);
bt('track', 
   'liked', 
   {id: 'your_id', resourceType: 'article', url: 'https://example.com'}
  );
bt('track',
   'liked',
   {'score': -1}
);
bt('track',
   'liked',
   {'score': 3, 'minScore': 1, 'maxScore': 5}
);
bt('track',
   'liked',
   {to: 'facebook'}
);

Sharing a Page or Resource

eventType:shared

Indicates a user has shared the specified page/resource with another user.

The following properties should be provided in a shared event when available:

PropertyTypeDescription
target_user_idsArrayA list of Strings representing the User IDs of the target users for the share.
toStringA string representing the service or external destination of the share, for example, "facebook" or "twitter"
bt('track',
   'shared',
   {}
  );
bt('track', 
   'shared', 
   {id: 'yourId', resourceType: 'yourResourceType', url: 'https://example.com'}
  );
bt('track',
   'shared',
   {'target_user_ids': ['sample-target-user-1', 'sample-target-user-2']}
  );
bt('track',
   'shared',
   {'target_user_ids': ['sample-target-user-1', 'sample-target-user-2']},
   {id: 'yourId', resourceType: 'yourResourceType', url: 'https://example.com'}
  );
bt('track',
   'shared',
   {to: 'facebook'}
  );

Commenting on a Page or Resource

eventType:commented

Indicates a user has commented on the specified page/resource.

The following properties should be provided in a commented event when available:

PropertyTypeDescription
commentTextStringThe text of the comment
bt('track',
   'commented',
   {'commentText': 'This is my comment.' }
  );

Properties

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

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

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

If an event is tracked with any of these property names specified, the specified property may be discarded.

Settings

The settings object is used for configuring the track call.

ObjectDescription
onCompleteThis setting allows the caller to specify a callback function once the track function has completed. The function will be called regardless of whether the track was successful or not. The function should have no parameters (nothing will be passed to it).
onFailure(error)This setting allows the caller to specify a callback function if the track function has completed with an error. The error raised by the track function will be passed into this callback.
onSuccessThis setting allows the caller to specify a callback function once the track function has completed successfully. The function should have no parameters (nothing will be passed to it).
bt('track', 
   'viewed', 
   {id: 'abcde123', resourceType: 'article'}, 
   {onComplete: function() 
   { console.log('Track Call Completed!'); }
   }
  );
bt('track', 
   'viewed', 
   {id: 'abcde123', resourceType: 'article'}, 
   {onFailure: function(err) 
   { console.log('Track Call Failed!: ' + err); }
   }
  );
bt('track', 
   'viewed', 
   {id: 'abcde123', resourceType: 'article'}, 
   {onSuccess: function() 
   { console.log('Track Call Succeeded!'); }
   }
  );