Events

Events are interactions of your users with your website or application. They are often associated with an item, but don’t have to be. Examples of user interactions that lead to an event are when a user opens a product detail page, clicks on a recommendation or purchases a product. The recommendations Froomle serves are based on these events. Events are grouped by the kind of interaction they represent, for example:

This page discusses the details of what user interactions are considered events and what they look like. To learn how to send these events to Froomle, see Events API.

Concepts

Tracking event types

Tracking events are events that can be used across all types of website or apps. The event types you can record as users make use of your website are:

User Event Name User Action

detail_pageview

Views an item detail page

group_pageview

Views a page containing multiple items e.g. categories, promotions

item_interaction

Interacts with an item e.g. product like, favourite, …​

group_interaction

Interacts with a group of items e.g. category like, favourite, …​

page_visit

Views a generic page not included in other pageview events

Integration event types

Integration events are all user interactions with recommendations on your website. These are the Froomle integration event types that you can record as users interact with recommendations on your website:

User Event Name User Action

impression

Views a personalised recommendation

click_on_recommendation

Clicks on a given recommendation

Retail event types

Retail events are all events specific to retail use cases. Froomle tracks the following events in the retail conversion funnel:

User Event Name User Action

add_to_cart

Adds item to cart

remove_from_cart

Removes item from cart

purchase

Completes a purchase

Batch event types

Batch integration events are all user interactions with recommendations that were generated in bulk and not at the user’s request. These are the Froomle batch integration event types that you can record as users interact with these types of recommendations:

User Event Name User Action

batch_impression

Views a personalised recommendation

batch_click_on_recommendation

Clicks on a given recommendation

batch_open

Opens the email, notification, …​

Search event types

A search integration implies a user can utilize a personalised search engine to improve their search results. The events recorded for search are similar to a default integration.

User Event Name User Action

search_impression

Views a personalised recommendation

search_click_on_recommendation

Clicks on a given recommendation

Session event types

When recommendations will be provided in an interactive session, such as a chatbot, we refer to this as a session integration. In an interactive recommendation context, every user session will be seen as independent of prior session.

User Event Name User Action

session_impression

Views a personalised recommendation

session_click_on_recommendation

Clicks on a given recommendation

Media event types

For an optimal media Froomle integration checkpoints are a great addition to improve the model. Checkpoints provide information about the progress a user has made while watching, reading or listening to content.

User Event Name User Action

checkpoint

Passes a certain checkpoint in the content

Event priority

To provide the best recommendations possible, it is recommended to record user events for all event types. The following table describes the priority of the different user event types. The highest priority of user events must be logged to obtain quality data models.

Priority User Events

Required for initial setup

detail_pageview

Important for model improvement

item_interaction

group_interaction

group_pageview

Important for model improvement (retail)

purchase

add_to_cart

remove_from_cart

Important for model improvement (media)

checkpoint

Required for analysis (KPI’s)

impression

click_on_recommendation

batch_open

batch_click_on_recommendation

batch_impression

page_visit

session_click_on_recommendation

session_impression

search_click_on_recommendation

search_impression

Event specifications

User information

Froomle identifies users through the use of a device_id or user_id. Neither of those fields are mandatory on their own, but either one of them needs to be present and preferably both.

Tracking events

Website tracking events can be used on any website, be it a webshop or streaming platform.

Detail pageview

The user views an item detail page. Examples are article pages, video pages or product detail pages.

  • Specification

  • Example

Field Description

event_type*

string

Required. Defines the type of the specified event, has to be exactly detail_pageview.

page_type*

string

Required. Page from which the event originated, e.g. home, overview, detail, …​ .

device_id*

string

Required. User identifier stored in a cookie.

user_id*

string

Required. User identifier of the logged in user.

action_item*

string

Required. Identifier of the item interacted with.

action_item_type

string

Optional. Type of the item interacted with.

channel

string

Optional. The platform the user is currently using. Examples include: mobile-web, desktop-web, iphone, android, ipad.

 
{
    "event_type": "detail_pageview",
    "page_type": "detail",
    "device_id" : "the_device_id-123",
    "user_id" : "the_user_id-123",
    "action_item" : "the_action_item_id",
    "channel" : "desktop-website"
}

Group pageview

The user views an overview page or any other page that pertains to a group of items. An example is a category overview page.

  • Specification

  • Example

Field Description

event_type*

string

Required. Defines the type of the specified event, has to be exactly group_pageview.

page_type*

string

Required. Page from which the event originated, e.g. home, overview, detail, …​ .

device_id*

string

Required. User identifier stored in a cookie.

user_id*

string

Required. User identifier of the logged in user.

action_group*

string

Required. Identifier of the group interacted with.

action_group_type

string

Optional. Type of the group interacted with.

channel

string

Optional. The platform the user is currently using. Examples include: mobile-web, desktop-web, iphone, android, ipad.

 
{
    "event_type": "group_pageview",
    "page_type": "category",
    "device_id" : "the_device_id-123",
    "user_id" : "the_user_id-123",
    "action_group" : "the_viewed_group",
    "channel" : "desktop-website"
}

Page visit

A page visit represents the viewing of a generic page, that cannot be linked to a group of items or a single item. A common example of this is a view of the homepage of the website.

  • Specification

  • Example

Field Description

event_type*

string

Required. Defines the type of the specified event, has to be exactly page_visit.

page_type*

string

Required. Page from which the event originated, e.g. home, overview, detail, …​ .

device_id*

string

Required. User identifier stored in a cookie.

user_id*

string

Required. User identifier of the logged in user.

channel

string

Optional. The platform the user is currently using. Examples include: mobile-web, desktop-web, iphone, android, ipad.

 
{
    "event_type": "page_visit",
    "page_type": "home",
    "device_id" : "the_device_id-123",
    "user_id" : "the_user_id-123",
    "channel" : "desktop-website"
}

Item interaction

The item interaction event represents any item interaction event that is not explicitly covered in the Froomle specification language for events. Examples are product likes or add-to-wishlists. If your website has item interactions that are not covered by specific events, contact your Solution Architect at support@froomle.com to discuss whether it is useful to track them.

  • Specification

  • Example

Field Description

event_type*

string

Required. Defines the type of the specified event, has to be exactly item_interaction.

page_type*

string

Required. Page from which the event originated, e.g. home, overview, detail, …​ .

device_id*

string

Required. User identifier stored in a cookie.

user_id*

string

Required. User identifier of the logged in user.

interaction_type*

string

Required. The type of interaction, e.g. like, save, share, …​ .

action_item*

string

Required. Identifier of the item interacted with.

action_item_type

string

Optional. Type of the item interacted with.

channel

string

Optional. The platform the user is currently using. Examples include: mobile-web, desktop-web, iphone, android, ipad.

 
{
    "event_type": "item_interaction",
    "page_type": "detail",
    "device_id" : "the_device_id-123",
    "user_id" : "the_user_id-123",
    "interaction_type" : "product_like",
    "action_item" : "the_action_item_id",
    "channel" : "desktop-website"
}

Group interaction

The group interaction event represents any group interaction event that is not explicitly covered in the Froomle specification language for events. Examples are category likes or subscribes. If your website has group interactions that are not covered by specific events, contact your Solution Architect at support@froomle.com to discuss whether it is useful to track them.

  • Specification

  • Example

Field Description

event_type*

string

Required. Defines the type of the specified event, has to be exactly group_interaction.

page_type*

string

Required. Page from which the event originated, e.g. home, overview, detail, …​ .

device_id*

string

Required. User identifier stored in a cookie.

user_id*

string

Required. User identifier of the logged in user.

action_group*

string

Required. Identifier of the group interacted with.

action_group_type

string

Optional. Type of the group interacted with.

interaction_type*

string

Required. The type of interaction, e.g. like, save, share, …​ .

channel

string

Optional. The platform the user is currently using. Examples include: mobile-web, desktop-web, iphone, android, ipad.

 
{
    "event_type": "group_interaction",
    "page_type": "category",
    "device_id" : "the_device_id-123",
    "user_id" : "the_user_id-123",
    "action_group" : "the_viewed_category",
    "interaction_type": "category_like",
    "channel" : "desktop-website"
}

Integration events

Integration events are all user interactions with recommendations on your website.

Click on recommendation

This event should be triggered whenever a user clicks on a recommendation. It is our expectation that after a click, a user is redirected to the detail page corresponding to the clicked item.

  • Specification

  • Example

Field Description

event_type*

string

Required. Defines the type of the specified event, has to be exactly click_on_recommendation.

page_type*

string

Required. Page from which the event originated, e.g. home, overview, detail, …​ .

device_id*

string

Required. User identifier stored in a cookie.

user_id*

string

Required. User identifier of the logged in user.

list_name*

string

Required. Title of the list to which the recommendation belongs. Should match the title of the list.

action_item*

string

Required. Identifier of the item interacted with.

action_item_type

string

Optional. Type of the item interacted with.

request_id*

string

Required. Either the Froomle-generated request identifier if Froomle generated the displayed recommendations, or your own request identifier if you generated the recommendations yourself. The Froomle request identifier is included in the recommendation response that generated the recommendations.

context_item

string

Optional. Identifier of the item in context (not interacted with).

context_item_type

string

Optional. Type of the item in context (not interacted with).

channel

string

Optional. The platform the user is currently using. Examples include: mobile-web, desktop-web, iphone, android, ipad.

version

string

Optional. Version should be supplied if the recommendation was generated by Froomle, or if you have AB tests with different versions of your own.

user_group*

string

Required. User_group identifies who provided the recommendation. This can be "froomle", your own personalization solution, or simply "cms" for static content.

 
{
    "event_type": "click_on_recommendation",
    "page_type": "home",
    "device_id" : "the_device_id-123",
    "user_id" : "the_user_id-123",
    "list_name" : "The list name",
    "action_item" : "the_action_item_id-123",
    "request_id": 6461,
    "context_item": "the_context_item_id-123",
    "channel": "phone-app",
    "version": "1",
    "user_group": "froomle"
}

Impression

An impression event is triggered when the user is shown a recommendation. When a user receives their recommendations in a carousel, only the ones that have been shown should be considered impressed.

  • Specification

  • Example

Field Description

event_type*

string

Required. Defines the type of the specified event, has to be exactly impression.

page_type*

string

Required. Page from which the event originated, e.g. home, overview, detail, …​ .

device_id*

string

Required. User identifier stored in a cookie.

user_id*

string

Required. User identifier of the logged in user.

list_name*

string

Required. Title of the list to which the recommendation belongs. Should match the title of the list.

action_item*

string

Required. Identifier of the item interacted with.

action_item_type

string

Optional. Type of the item interacted with.

request_id*

string

Required. Either the Froomle-generated request identifier if Froomle generated the displayed recommendations, or your own request identifier if you generated the recommendations yourself. The Froomle request identifier is included in the recommendation response that generated the recommendations.

context_item

string

Optional. Identifier of the item in context (not interacted with).

context_item_type

string

Optional. Type of the item in context (not interacted with).

channel

string

Optional. The platform the user is currently using. Examples include: mobile-web, desktop-web, iphone, android, ipad.

version

string

Optional. Version should be supplied if the recommendation was generated by Froomle, or if you have AB tests with different versions of your own.

user_group*

string

Required. User_group identifies who provided the recommendation. This can be "froomle", your own personalization solution, or simply "cms" for static content.

 
{
    "event_type": "impression",
    "page_type": "home",
    "device_id" : "the_device_id-123",
    "user_id" : "the_user_id-123",
    "list_name" : "The list name",
    "action_item" : "the_action_item_id-123",
    "request_id": 6461,
    "context_item": "the_context_item_id-123",
    "channel": "phone-app",
    "version": "1",
    "user_group": "froomle"
}

Batch events

Batch events are expected to be sent when recommendations are requested in bulk. When a batch of recommendations was generated for all users, we refer to this as a campaign. An example of this is an email integration, where all users receive a certain campaign email.

Batch open

The batch open events represents a user opening the message that contains the recommendations. An example is when a user opens an email.

  • Specification

  • Example

Field Description

event_type*

string

Required. Defines the type of the specified event, has to be exactly batch_open.

page_type*

string

Required. Page from which the event originated, e.g. home, overview, detail, …​ .

device_id*

string

Required. User identifier stored in a cookie.

user_id*

string

Required. User identifier of the logged in user.

campaign_id*

string

Required. Identifier of the campaign for which the batch recommendations were generated.

channel

string

Optional. The platform the user is currently using. Examples include: mobile-web, desktop-web, iphone, android, ipad.

 
{
    "event_type": "batch_open",
    "page_type": "email",
    "device_id" : "the_device_id-123",
    "user_id" : "the_user_id-123",
    "campaign_id": "the_campaign_id-123",
    "channel": "mobile-phone"
}

Batch click on recommendation

This event should be triggered whenever a user clicks on a recommendation in a campaign. It is our expectation that after a click, a user is redirected to the detail page corresponding to the clicked item.

  • Specification

  • Example

Field Description

event_type*

string

Required. Defines the type of the specified event, has to be exactly batch_click_on_recommendation.

page_type*

string

Required. Page from which the event originated, e.g. home, overview, detail, …​ .

device_id*

string

Required. User identifier stored in a cookie.

user_id*

string

Required. User identifier of the logged in user.

list_name*

string

Required. Title of the list to which the recommendation belongs. Should match the title of the list.

action_item*

string

Required. Identifier of the item interacted with.

action_item_type

string

Optional. Type of the item interacted with.

request_id*

string

Required. Either the Froomle-generated request identifier if Froomle generated the displayed recommendations, or your own request identifier if you generated the recommendations yourself. The Froomle request identifier is included in the recommendation response that generated the recommendations.

campaign_id*

string

Required. Identifier of the campaign for which the batch recommendations were generated.

channel

string

Optional. The platform the user is currently using. Examples include: mobile-web, desktop-web, iphone, android, ipad.

 
{
    "event_type" : "batch_click_on_recommendation",
    "device_id" : "the_device_id-123",
    "user_id" : "the_user_id-123",
    "list_name" : "The list name",
    "action_item" : "the_action_item_id-123",
    "request_id": 6461,
    "context_item": "the_context_item_id-123",
    "campaign_id": "the_campaign_id-123",
    "channel": "phone-app"
}

Batch impression

An impression event is triggered when the user is shown a recommendation. It is common to request more recommendations than will be shown when requesting recommendations in bulk. Only those used in the campaign should result in an impression.

  • Specification

  • Example

Field Description

event_type*

string

Required. Defines the type of the specified event, has to be exactly batch_impression.

page_type*

string

Required. Page from which the event originated, e.g. home, overview, detail, …​ .

device_id*

string

Required. User identifier stored in a cookie.

user_id*

string

Required. User identifier of the logged in user.

list_name*

string

Required. Title of the list to which the recommendation belongs. Should match the title of the list.

action_item*

string

Required. Identifier of the item interacted with.

action_item_type

string

Optional. Type of the item interacted with.

request_id*

string

Required. Either the Froomle-generated request identifier if Froomle generated the displayed recommendations, or your own request identifier if you generated the recommendations yourself. The Froomle request identifier is included in the recommendation response that generated the recommendations.

channel

string

Optional. The platform the user is currently using. Examples include: mobile-web, desktop-web, iphone, android, ipad.

campaign_id*

string

Required. Identifier of the campaign for which the batch recommendations were generated.

 
{
    "event_type" : "batch_impression",
    "device_id" : "the_device_id-123",
    "user_id" : "the_user_id-123",
    "list_name" : "The list name",
    "action_item" : "the_action_item_id-123",
    "request_id": 6461,
    "channel": "phone-app",
    "campaign_id": "the_campaign_id-123"
}

Search events

Search events are expected to be sent when you’ve integrated the Froomle personalised search engine.

Search click on recommendation

This event should be triggered whenever a user clicks on a search result. It is our expectation that after a click, a user is redirected to the detail page corresponding to the clicked item.

  • Specification

  • Example

Field Description

event_type*

string

Required. Defines the type of the specified event, has to be exactly search_click_on_recommendation.

page_type*

string

Required. Page from which the event originated, e.g. home, overview, detail, …​ .

device_id*

string

Required. User identifier stored in a cookie.

user_id*

string

Required. User identifier of the logged in user.

list_name*

string

Required. Title of the list to which the recommendation belongs. Should match the title of the list.

action_item*

string

Required. Identifier of the item interacted with.

action_item_type

string

Optional. Type of the item interacted with.

request_id*

string

Required. Either the Froomle-generated request identifier if Froomle generated the displayed recommendations, or your own request identifier if you generated the recommendations yourself. The Froomle request identifier is included in the recommendation response that generated the recommendations.

channel

string

Optional. The platform the user is currently using. Examples include: mobile-web, desktop-web, iphone, android, ipad.

 
{
    "event_type" : "search_click_on_recommendation",
    "device_id" : "the_device_id-123",
    "user_id" : "the_user_id-123",
    "list_name" : "The list name",
    "action_item" : "the_action_item_id-123",
    "request_id": 6461,
    "channel": "phone-app"
}

Search impression

An impression event is triggered when the user is shown a search result. It is common to have more search results than can be shown on a single page. Impressions should thus only be sent for results that were seen by a user.

  • Specification

  • Example

Field Description

event_type*

string

Required. Defines the type of the specified event, has to be exactly search_impression.

page_type*

string

Required. Page from which the event originated, e.g. home, overview, detail, …​ .

device_id*

string

Required. User identifier stored in a cookie.

user_id*

string

Required. User identifier of the logged in user.

list_name*

string

Required. Name of the list to which the recommendation belongs.

action_item*

string

Required. Identifier of the item interacted with.

action_item_type

string

Optional. Type of the item interacted with.

request_id*

string

Required. Either the Froomle-generated request identifier if Froomle generated the displayed recommendations, or your own request identifier if you generated the recommendations yourself. The Froomle request identifier is included in the recommendation response that generated the recommendations.

channel

string

Optional. The platform the user is currently using. Examples include: mobile-web, desktop-web, iphone, android, ipad.

 
{
    "event_type" : "search_impression",
    "device_id" : "the_device_id-123",
    "user_id" : "the_user_id-123",
    "list_name" : "The list name",
    "action_item" : "the_action_item_id-123",
    "request_id": 6461,
    "channel": "phone-app"
}

Session events

Session events are expected to be sent when you’ve integrated Froomle in an interaction recommendation context, such as a chatbot. In contrast to other events, recommendations in a sessions do not require an identifiable user, but instead a unique session ID.

Session click on recommendation

This event should be triggered whenever a user clicks on a recommendation in an interactive session.

  • Specification

  • Example

Field Description

event_type*

string

Required. Defines the type of the specified event, has to be exactly session_click_on_recommendation.

page_type*

string

Required. Page from which the event originated, e.g. home, overview, detail, …​ .

session_id*

string

Required. Unique identifier of this session.

list_name*

string

Required. Title of the list to which the recommendation belongs. Should match the title of the list.

action_item*

string

Required. Identifier of the item interacted with.

action_item_type

string

Optional. Type of the item interacted with.

request_id*

string

Required. Either the Froomle-generated request identifier if Froomle generated the displayed recommendations, or your own request identifier if you generated the recommendations yourself. The Froomle request identifier is included in the recommendation response that generated the recommendations.

channel

string

Optional. The platform the user is currently using. Examples include: mobile-web, desktop-web, iphone, android, ipad.

 
{
    "event_type" : "session_click_on_recommendation",
    "session_id" : "the_session_id-123",
    "list_name" : "The list name",
    "action_item" : "the_action_item_id-123",
    "request_id": 6461,
    "channel": "phone-app"
}

Session impression

A session_impression event is triggered when the user is shown a recommendation in an interactive session.

  • Specification

  • Example

event_type*

string

Required. Defines the type of the specified event, has to be exactly session_impression.

page_type*

string

Required. Page from which the event originated, e.g. home, overview, detail, …​ .

session_id*

string

Required. Unique identifier of this session.

list_name*

string

Required. Title of the list to which the recommendation belongs. Should match the title of the list.

action_item*

string

Required. Identifier of the item interacted with.

action_item_type

string

Optional. Type of the item interacted with.

request_id*

string

Required. Either the Froomle-generated request identifier if Froomle generated the displayed recommendations, or your own request identifier if you generated the recommendations yourself. The Froomle request identifier is included in the recommendation response that generated the recommendations.

channel

string

Optional. The platform the user is currently using. Examples include: mobile-web, desktop-web, iphone, android, ipad.

 
{
    "event_type" : "session_impression",
    "session_id" : "the_session_id-123",
    "list_name" : "The list name",
    "action_item" : "the_action_item_id-123",
    "request_id": 6461,
    "channel": "phone-app"
}

Media events

Checkpoint

A checkpoint event represents that the user has reached a specific point in the consumed media.

  • Specification

  • Example

Field Description

event_type*

string

Required. Defines the type of the specified event, has to be exactly checkpoint.

page_type*

string

Required. Page from which the event originated, e.g. home, overview, detail, …​ .

device_id*

string

Required. User identifier stored in a cookie.

user_id*

string

Required. User identifier of the logged in user.

action_item*

string

Required. Identifier of the item interacted with.

action_item_type

string

Optional. Type of the item interacted with.

tag*

string

Required. Type of the reached checkpoint in the media entity.

action_item*

string

Required. Identifier of the item interacted with.

action_item_type

string

Optional. Type of the item interacted with.

channel

string

Optional. The platform the user is currently using. Examples include: mobile-web, desktop-web, iphone, android, ipad.

 
{
    "event_type": "checkpoint",
    "page_type": "video_detail",
    "device_id" : "the_device_id-123",
    "user_id" : "the_user_id-123",
    "action_item": "the_action_item_id-123",
    "tag": "ended",
    "action_item_type": "episode",
    "channel": "mobile-website"
}

Retail events

Add to cart

An add to cart event is triggered when a user adds an item to their cart/basket. It also identifies a user’s intention to buy, without the certainty of purchase.

  • Specification

  • Example

Field Description

event_type*

string

Required. Defines the type of the specified event, has to be exactly add_to_cart.

page_type*

string

Required. Page from which the event originated, e.g. home, overview, detail, …​ .

device_id*

string

Required. User identifier stored in a cookie.

user_id*

string

Required. User identifier of the logged in user.

action_item*

string

Required. Identifier of the item interacted with.

action_item_type

string

Optional. Type of the item interacted with.

amount*

integer

Required. Number of items added to the cart.

channel

string

Optional. The platform the user is currently using. Examples include: mobile-web, desktop-web, iphone, android, ipad.

 
{
    "event_type": "add_to_cart",
    "page_type": "detail",
    "device_id" : "the_device_id-123",
    "user_id" : "the_user_id-123",
    "action_item": "the_action_item_id-123",
    "amount": 10,
    "channel": "mobile-website"
}

Remove from cart

A remove from cart event is triggered when a customer removes an item from their basket/cart.

  • Specification

  • Example

Field Description

event_type*

string

Required. Defines the type of the specified event, has to be exactly remove_from_cart.

device_id*

string

Required. User identifier stored in a cookie.

user_id*

string

Required. User identifier of the logged in user.

action_item*

string

Required. Identifier of the item interacted with.

action_item_type

string

Optional. Type of the item interacted with.

amount*

integer

Required. Number of items removed from the shopping cart.

channel

string

Optional. The platform the user is currently using. Examples include: mobile-web, desktop-web, iphone, android, ipad.

 
{
    "event_type": "remove_from_cart",
    "device_id" : "the_device_id-123",
    "user_id" : "the_user_id-123",
    "action_item": "the_action_item_id-123",
    "amount": 10,
    "channel": "mobile-website"
}

Purchase

A purchase event represents the action of buying a product on the webpage, in a physical store or on a mobile application.

  • Specification

  • Example

Field Description

event_type*

string

Required. Defines the type of the specified event, has to be exactly purchase.

device_id*

string

Required. User identifier stored in a cookie.

user_id*

string

Required. User identifier of the logged in user.

action_item*

string

Required. Identifier of the item interacted with.

action_item_type

string

Optional. Type of the item interacted with.

amount*

integer

Required. Number of purchased items.

original_price

float

Optional. Original price of the item (in case a reduction was applied).

purchased_price

float

Optional. The price paid by the customer for the item.

channel

string

Optional. The platform the user is currently using. Examples include: mobile-web, desktop-web, iphone, android, ipad.

 
{
    "event_type": "purchase",
    "device_id" : "the_device_id-123",
    "user_id" : "the_user_id-123",
    "action_item": "the_action_item_id-123",
    "amount": 10,
    "original_price": 29.99,
    "purchased_price": 9.99,
    "channel": "mobile-website"
}