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.

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