Events (behavior tracking)

Gravity uses events for tracking user interactions. Events are collected on our server and are used to build user profiles to provide personalized recommendations.

Example list of events

TimeEvent typeuserIdItemIdorderIdlocationrecId
1552486741BUY123123abc123abc12312-12-12
1552486778BUY321321321cba321cba12-12-12
1552486802VIEW123123abc123abc123
1552487324REC_CLICK123123321cba321cbak37hv01j-0300tkrwhkz-S.ITEM_PAGE-14nrg7y
1552488333BROWSE121212www.abc.abc/categories/teddybears/

Event Anatomy

By each action, time, user identification and event type are necessary. In many cases, the events are related to a specific item that has been viewed/bought/etc. by the user. Additional fields like url location, orderId can be added to each of the events.

Event PropertyDescription
userIdID for logged in users
cookieIdID for guests
(For mobile devices, send deviceId as cookieId)
itemIdID of the subject of the event
eventTypeType of the events, e.g. VIEW, BUY, ADD_TO_CART
timeThe time when the event occurred in UNIX timestamp format
recIdFor REC_CLICK, the id of the recommendation placement, where the item was clicked.
Added automatically in the case of frontend (JS) integration; needs to be parsed from the recommendation result (may be called recommendationId in the response) and added explicitly in the case of backend (REST, Java/Android, iOS, php) integration.
Used for conversion tracking.
<custom_property>Additional event attributes, such as price and orderId for BUY events

Event Types

Classified event types

The list of supported event types is predefined, and the most commonly used Classified related types are summarized in the table below.

Events can have arbitrarily many custom attributes, called name-value pairs. These name-value pairs allow to pass any information about the events. The table below describes the suggested name values for the specific event types.

Event TypeDescriptionNameValues for the event
VIEWThe user viewed the info page of an item.
PHONE_CLICKThe user clicks on the show phone number button.
LETTER_SENDThe user sent a message to the advertiser.
RATINGThe user rated an item.value - The value of the rating.
ADD_TO_FAVORITESThe user added the item to his/her favorites.listId - Use if the webshop supports multiple favorites lists.
REMOVE_FROM_FAVORITESThe user removed an item from his/her favorites.listId - Use if the webshop supports multiple favorites lists.
REC_CLICKThe user clicked on a recommended item.recId - see above, at Event Anatomy

position - The position of the clicked item in the recommendation list. The position of the first item is 1.
SEARCHA list of products was displayed to the user, for example by browsing a category or by free text search.searchString

filter.* - If the listing is based on comparing an item namevalue to a filter value, you can provide the actual filter here.For example, if the user was browsing a specific category, name='Filter.CategoryId' and value='CategoryA' can be specified.

E-commerce event types

The list of supported event types is predefined, and the most commonly used E-commerce related types are summarized in the table below.

Events can have arbitrarily many custom attributes, called name-value pairs. These name-value pairs allow to pass any information about the events. The table below describes the suggested name values for the specific event types.

Event TypeDescriptionNameValues for the event
VIEWThe user viewed the info page of an item.
BUYThe user bought an item.orderId
unitPrice - Formatted as a decimal number, for example 1234 or 12345.67
currency
quantity - Formatted as a decimal number.
RATINGThe user rated an item.value - The value of the rating.
ADD_TO_CARTThe user added an item to the shopping cart.quantity
REMOVE_FROM_CARTThe user removed an item from the shopping cart.quantity
ADD_TO_FAVORITESThe user added the item to his/her favorites.listId - Use if the webshop supports multiple favorites lists.
REMOVE_FROM_FAVORITESThe user removed an item from his/her favorites.listId - Use if the webshop supports multiple favorites lists.
REC_CLICKThe user clicked on a recommended item.recId - see above, at Event Anatomy

position - The position of the clicked item in the recommendation list. The position of the first item is 1.
SEARCHA list of products was displayed to the user, for example by browsing a category or by free text search.searchString
filter.* - If the listing is based on comparing an item namevalue to a filter value, you can provide the actual filter here.For example, if the user was browsing a specific category, name='Filter.CategoryId' and value='CategoryA' can be specified.

Video streaming event types

The list of supported event types is predefined, and the most commonly used Video streaming related types are summarized in the table below.

Events can have arbitrarily many custom attributes, called name-value pairs. These name-value pairs allow passing any information about the events. The table below describes the suggested name values for the specific event types.

Event TypeDescriptionName-values for the event
VIEWThe user viewed the video detail page.
RATINGThe user rated an item.value - The value of the rating.
ADD_TO_FAVORITESThe user added the item to his/her favorites.listId - Use if the webshop supports multiple favorites lists.
REMOVE_FROM_FAVORITESThe user removed an item from his/her favorites.listId - Use if the webshop supports multiple favorites lists.
REC_CLICKThe user clicked on a recommended item.recId - see above, at Event Anatomy

position - The position of the clicked item in the recommendation list. The position of the first item is 1.
SEARCHA list of products was displayed to the user, for example by browsing a category or by free text search.query
filter.* - If the listing is based on comparing an item name-value to a filter value, you can provide the actual filter here.
For example, if the user was browsing a specific category, name='Filter.CategoryId' and value='CategoryA' can be specified.
FREE_VIEWThe user watched an item for free.
PAID_VIEWThe user paid for watching/listening an item.value - How much the user paid for watching the item. A decimal number.
SUBSCRIPTION_VIEWThe user watched an item that was available for her by a subscription.
WATCHThe user watched a percentage of a video.percentage - The percentage the user watched the video.

File-based initial event upload

You can provide historical events for Gravity uses a TSV file. It can be uploaded to RECO using the DASH. This should be used for transactional type events like BUY.
sample event catalog

userIditemIdcookieIdtimeeventTypeorderIdunitPricequantitycurrency
12345613cd10a5f49-5885b759437f0ccd1285579547BUYO-2362300.303USD
1212313cc9c746e5-a899a80c7a067beb1285578547BUYO-2341000.202EUR

Where a value is missing (such as userId) the content for that should be left empty (instead of missing, null and such attributes).

You can add event specific meta information by adding additional columns.

Automated event tracking

This is the most simple way of sending events. As you only have to include Gravity's JS library. The event tracking does not require any further action from your side. The tracking code is injected by Gravity.
The communication between the recommendation engine and the customer's site is implemented by asynchronous JavaScript calls directly between the user's browser and the recommendation engine.

First, you need to bootstrap our system by adding the following code to the webpage (this will load and setup our JS library). Paste this snippet into your website template page so that it appears before the closing tag.

<head>
    [...]
<script>
    (function(g,r,a,v,i,t,y){
        g[a]=g[a]||[],y=r.createElement(v),
        g=r.getElementsByTagName(v)[0];y.async=1;
        y.src='//'+i+'/js/'+t+'/gr_reco5.min.js';
        g.parentNode.insertBefore(y,g);y=r.createElement(v),y.async=1;
        y.src='//'+i+'/grrec-'+t+'-war/JSServlet4?cc=1';
        g.parentNode.insertBefore(y,g);
    })(window, document, '_gravity','script', '<CUSTOMERID>-<SERVERLOCATION>.gravityrd-services.com', '<CUSTOMERID>');
</script>
</head>

You should replace CUSTOMERID with your partner identifier and SERVERLOCATION with the gravity cluster name!

(The library will register a global object named "GravityRD". Except this object, which is necessary we don't pollute your namespace.)

📘

For debugging reasons, a non-minimized version of the library is also available, named: gr_reco5.js

JS event tracking

You can initiate events using our JS API. This gives you more control over user tracking but more advanced coding is required. In addition to including Yusp's JS fragment, you should trigger the events by JS calls. Some of the work like cookie tracking and associating the events to recommendations is still done automatically.

E-commerce sample code

var  _gravity = _gravity || [];
_gravity.push({type: 'set', userId: 'user1234'});
// searching for an item
_gravity.push({type: 'event', eventType: 'SEARCH', filter.categoryId: "4", filter.minPrice: "15", filter.maxPrice: "45"});

// clicking on non-Yusp recommendation box 
_gravity.push({type: 'event', eventType: 'CLICK', itemId: "item123", scenarioId: "W_CAT_RIGHT", position: "1"});
// clicking on a yusp recommendation box
_gravity.push({type: 'event', eventType: 'REC_CLICK', itemId: "item123", scenarioId: "W_CAT_RIGHT", position: "1", recId: "1192821"});

// viewing the item the user clicked on in the recommendation box.
_gravity.push({type: 'event', eventType: 'VIEW', itemId: "item123"});
// adding the item to the user's cart.
_gravity.push({type: 'event', eventType: 'ADD_TO_CART', itemId: "item123", quantity: "1"});
// also adding another item to the user's cart.
_gravity.push({type: 'event', eventType: 'ADD_TO_CART', itemId: "item146", quantity: "2"});
// buying the items from the cart.
_gravity.push({type: 'event', eventType: 'BUY', itemId: "item123", quantity: "1", orderId: "566443", unitPrice: "34"});
_gravity.push({type: 'event', eventType: 'BUY', itemId: "item146", quantity: "2", orderId: "566443", unitPrice: "24"});

// the user unhides full detailed description section
_gravity.push({type: 'event', eventType: 'UNHIDE', itemId: "item123"});

Classified sample code

 var _gravity = _gravity || [];
_gravity.push({type: 'set', userId: 'user1234'});
// viewing the item the user clicked on in the recommendation box.
_gravity.push({type: 'event', eventType: 'VIEW', itemId: "item123"});
// searching for an item
_gravity.push({type: 'event', eventType: 'SEARCH', filter.categoryId: "4", filter.minPrice: "15", filter.maxPrice: "45"});

// clicking on non-Yusp recommendation box 
_gravity.push({type: 'event', eventType: 'CLICK', itemId: "item123", scenarioId: "W_CAT_RIGHT", position: "1"});
// clicking on a yusp recommendation box
_gravity.push({type: 'event', eventType: 'REC_CLICK', itemId: "item123", scenarioId: "W_CAT_RIGHT", position: "1", recId: "1192821"});

// adding the item to the user's favorites.
_gravity.push({type: 'event', eventType: 'ADD_TO_FAVORITES', itemId: "item123"});
// also adding another item to the user's favorites.
_gravity.push({type: 'event', eventType: 'ADD_TO_FAVORITES', itemId: "item146"});

// the user contacts via contact form or via apply button
//fill contact form
_gravity.push({type: 'event', eventType: 'LETTER_SEND', itemId: "item123"});
//show phone number
_gravity.push({type: 'event', eventType: 'PHONE_VIEW', itemId: "item123"});
//apply button click
_gravity.push({type: 'event', eventType: 'APPLY', itemId: "item123"});

// the user rates an item.
_gravity.push({type: 'event', eventType: 'RATE', itemId: "item146", value: "4"});

Video streaming sample code

var _gravity = _gravity || [];
_gravity.push({type: 'set', userId: 'user1234'});
// viewing the item the user clicked on in the recommendation box.
_gravity.push({type: 'event', eventType: 'VIEW', itemId: "item123"});
// searching for an item
_gravity.push({type: 'event', eventType: 'SEARCH', filter.categoryId: "4", searchString: "Game of Thrones"});

// clicking on non-Yusp recommendation box 
_gravity.push({type: 'event', eventType: 'CLICK', itemId: "item123", scenarioId: "W_CAT_RIGHT", position: "1"});
// clicking on a yusp recommendation box
_gravity.push({type: 'event', eventType: 'REC_CLICK', itemId: "item123", scenarioId: "W_CAT_RIGHT", position: "1", recId: "1192821"});

// adding the item to the user's favorites.
_gravity.push({type: 'event', eventType: 'ADD_TO_FAVORITES', itemId: "item123"});
// also adding another item to the user's favorites.
_gravity.push({type: 'event', eventType: 'ADD_TO_FAVORITES', itemId: "item146"});

// the user views these 2 items.
_gravity.push({type: 'event', eventType: 'FREE_VIEW', itemId: "item123"});
_gravity.push({type: 'event', eventType: 'FREE_VIEW', itemId: "item146"});
// the user rates an item.
_gravity.push({type: 'event', eventType: 'RATE', itemId: "item146", value: "4"});

Server-side event tracking

We provide different server-side APIs which can be used for tracking user events. Use the server-side API, only if none of the other methods are applicable.

For more details please visit the following pages:
Java client
PHP client
REST API