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