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
Time | Event type | userId | ItemId | orderId | location | recId |
---|---|---|---|---|---|---|
1552486741 | BUY | 123123 | abc123abc123 | 12-12-12 | ||
1552486778 | BUY | 321321 | 321cba321cba | 12-12-12 | ||
1552486802 | VIEW | 123123 | abc123abc123 | |||
1552487324 | REC_CLICK | 123123 | 321cba321cba | k37hv01j-0300tkrwhkz-S.ITEM_PAGE-14nrg7y | ||
1552488333 | BROWSE | 121212 | www.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 Property | Description |
---|---|
userId | ID for logged in users |
cookieId | ID for guests (For mobile devices, send deviceId as cookieId) |
itemId | ID of the subject of the event |
eventType | Type of the events, e.g. VIEW, BUY, ADD_TO_CART |
time | The time when the event occurred in UNIX timestamp format |
recId | For 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 Type | Description | NameValues for the event |
---|---|---|
VIEW | The user viewed the info page of an item. | |
PHONE_CLICK | The user clicks on the show phone number button. | |
LETTER_SEND | The user sent a message to the advertiser. | |
RATING | The user rated an item. | value - The value of the rating. |
ADD_TO_FAVORITES | The user added the item to his/her favorites. | listId - Use if the webshop supports multiple favorites lists. |
REMOVE_FROM_FAVORITES | The user removed an item from his/her favorites. | listId - Use if the webshop supports multiple favorites lists. |
REC_CLICK | The 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. |
SEARCH | A 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 Type | Description | NameValues for the event |
---|---|---|
VIEW | The user viewed the info page of an item. | |
BUY | The user bought an item. | orderId unitPrice - Formatted as a decimal number, for example 1234 or 12345.67 currency quantity - Formatted as a decimal number. |
RATING | The user rated an item. | value - The value of the rating. |
ADD_TO_CART | The user added an item to the shopping cart. | quantity |
REMOVE_FROM_CART | The user removed an item from the shopping cart. | quantity |
ADD_TO_FAVORITES | The user added the item to his/her favorites. | listId - Use if the webshop supports multiple favorites lists. |
REMOVE_FROM_FAVORITES | The user removed an item from his/her favorites. | listId - Use if the webshop supports multiple favorites lists. |
REC_CLICK | The 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. |
SEARCH | A 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 Type | Description | Name-values for the event |
---|---|---|
VIEW | The user viewed the video detail page. | |
RATING | The user rated an item. | value - The value of the rating. |
ADD_TO_FAVORITES | The user added the item to his/her favorites. | listId - Use if the webshop supports multiple favorites lists. |
REMOVE_FROM_FAVORITES | The user removed an item from his/her favorites. | listId - Use if the webshop supports multiple favorites lists. |
REC_CLICK | The 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. |
SEARCH | A 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_VIEW | The user watched an item for free. | |
PAID_VIEW | The user paid for watching/listening an item. | value - How much the user paid for watching the item. A decimal number. |
SUBSCRIPTION_VIEW | The user watched an item that was available for her by a subscription. | |
WATCH | The 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
userId | itemId | cookieId | time | eventType | orderId | unitPrice | quantity | currency |
---|---|---|---|---|---|---|---|---|
123 | 456 | 13cd10a5f49-5885b759437f0ccd | 1285579547 | BUY | O-236 | 2300.30 | 3 | USD |
12 | 123 | 13cc9c746e5-a899a80c7a067beb | 1285578547 | BUY | O-234 | 1000.20 | 2 | EUR |
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
Updated almost 5 years ago