Froomle event specification

This page gives a full overview of all the tracking events supported by Froomle. Visit the integration handbook for guidelines on how the share them and which events to share in which use case.

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

item_interaction

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

user_interaction

User interactions not covered by one of our other events.

page_visit

Views a generic page (home, category, other)

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 personalized recommendation

click_on_recommendation

Clicks on a given recommendation

Industry specific - Media events

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.

In order to optimize your conversion, Froomle also needs information on when users subscribe or cancel any subscriptions.

User Event Name User Action

checkpoint

Passes a certain checkpoint in the content

user_interaction

Hit a paywall - "interaction_type:paywall"`

start_subscription

Start a subscription plan

cancel_subscription

Cancel a subscription plan

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 personalized recommendation

batch_click_on_recommendation

Clicks on a given recommendation

batch_open

Opens the email, notification, …​

Industry specific - E-commerce events

Retail events are all events specific to e-commerce use cases. Froomle tracks the following events in the e-commerce 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

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 personalized recommendation

session_click_on_recommendation

Clicks on a given recommendation

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. Accepted page_types are: home, article, category, foryou, regional and promotion. If none of these fit your use case, please get in touch with your account manager.

device_id*

string

Required. User identifier stored in a cookie. Use the value "no-consent" for users that wish to remain anonymous.

user_id*

string

Required. User identifier of the logged in user.

action_item*

string

Required. The identifier of the item which is being viewed by the user.

action_item_type*

string

Required. Type of the item interacted with.

channel*

string

Required. The channel the user is currently using. Accepted channels are: www, www-desktop, www-mobile, app, app-ios, app-android, app-audio, app-audio-ios and app-audio-android. If none of these fit your use case, please get in touch with your account manager.

 
{
    "events": [
        {
            "event_type": "detail_pageview",
            "page_type": "article_detail",
            "device_id": "the_device_id-123",
            "user_id": "the_user_id-123",
            "action_item": "the_action_item_id",
            "action_item_type": "article",
            "channel": "www-desktop"
        }
    ]
}

Page visit

A page visit represents the viewing of a generic page, which cannot be linked a single item. Common examples are a view of a home page or category page.

  • 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. Accepted page_types are: home, article, category, foryou, regional and promotion. If none of these fit your use case, please get in touch with your account manager.

device_id*

string

Required. User identifier stored in a cookie. Use the value "no-consent" for users that wish to remain anonymous.

user_id*

string

Required. User identifier of the logged in user.

channel*

string

Required. The channel the user is currently using. Accepted channels are: www, www-desktop, www-mobile, app, app-ios, app-android, app-audio, app-audio-ios and app-audio-android. If none of these fit your use case, please get in touch with your account manager.

 
{
    "events": [
        {
            "event_type": "page_visit",
            "page_type": "home",
            "device_id": "the_device_id-123",
            "user_id": "the_user_id-123",
            "channel": "www-desktop"
        }
    ]
}

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 us 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. Accepted page_types are: home, article, category, foryou, regional and promotion. If none of these fit your use case, please get in touch with your account manager.

device_id*

string

Required. User identifier stored in a cookie. Use the value "no-consent" for users that wish to remain anonymous.

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. Is the item that you currently perform an action on if your "action" = viewing a page, then the item you view is the action item. If your action is clicking a recommendation, the item you clicked is the action item. If the action is impressing an item, the action_item is impression.

action_item_type*

string

Required. Type of the item interacted with.

channel*

string

Required. The channel the user is currently using. Accepted channels are: www, www-desktop, www-mobile, app, app-ios, app-android, app-audio, app-audio-ios and app-audio-android. If none of these fit your use case, please get in touch with your account manager.

 
{
    "events": [
        {
            "event_type": "item_interaction",
            "page_type": "article_detail",
            "device_id": "the_device_id-123",
            "user_id": "the_user_id-123",
            "interaction_type": "product_like",
            "action_item": "the_action_item_id",
            "action_item_type": "product",
            "channel": "www-desktop"
        }
    ]
}

User interaction

The user interaction event represents any non-item interaction event that is not explicitly covered in the Froomle specification language for events, e.g. a user fills in a review form on your website, a user starts a session with an interactive chatbot, etc. If your website has user interactions that are not covered by specific events, contact us 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 user_interaction.

page_type*

string

Required. Page from which the event originated. Accepted page_types are: home, article, category, foryou, regional and promotion. If none of these fit your use case, please get in touch with your account manager.

device_id*

string

Required. User identifier stored in a cookie. Use the value "no-consent" for users that wish to remain anonymous.

user_id*

string

Required. User identifier of the logged in user.

interaction_type*

string

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

channel*

string

Required. The channel the user is currently using. Accepted channels are: www, www-desktop, www-mobile, app, app-ios, app-android, app-audio, app-audio-ios and app-audio-android. If none of these fit your use case, please get in touch with your account manager.

 
{
    "events": [
        {
            "event_type": "user_interaction",
            "page_type": "article_detail",
            "device_id": "the_device_id-123",
            "user_id": "the_user_id-123",
            "interaction_type": "submit_review",
            "channel": "www-desktop"
        }
    ]
}

Integration events

Integration events track the interactions of users with froomle recommendations. The benefits of integration events are:

  • Measuring performance, for example through CTR = click_on_recommendation / impression.

  • Improving recommendations through reinforcement learning and impressions discounting methods.

Click on recommendation

This event should be triggered whenever a user clicks on a Froomle 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. Accepted page_types are: home, article, category, foryou, regional and promotion. If none of these fit your use case, please get in touch with your account manager.

device_id*

string

Required. User identifier stored in a cookie. Use the value "no-consent" for users that wish to remain anonymous.

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. The identifier of the item which was recommended and clicked by the user.

action_item_type*

string

Required. 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

Required. The channel the user is currently using. Accepted channels are: www, www-desktop, www-mobile, app, app-ios, app-android, app-audio, app-audio-ios and app-audio-android. If none of these fit your use case, please get in touch with your account manager.

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. This can be found in the response body of the recommendation request in case the recommendation was generated by Froomle.

 
{
    "events": [
        {
            "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",
            "action_item_type": "article",
            "request_id": "6461",   //This can be found in the response body of the recommendation request in case the recommendation was generated by Froomle.
            "channel": "mobile-app",
            "user_group": "froomle" //This can be found in the response body of the recommendation request in case the recommendation was generated by Froomle.
        }
    ]
}

Impression

An impression event is triggered when the user is shown a Froomle 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. Accepted page_types are: home, article, category, foryou, regional and promotion. If none of these fit your use case, please get in touch with your account manager.

device_id*

string

Required. User identifier stored in a cookie. Use the value "no-consent" for users that wish to remain anonymous.

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. The identifier of the item which was recommended and shown to the user.

action_item_type*

string

Required. 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

Required. The channel the user is currently using. Accepted channels are: www, www-desktop, www-mobile, app, app-ios, app-android, app-audio, app-audio-ios and app-audio-android. If none of these fit your use case, please get in touch with your account manager.

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. This can be found in the response body of the recommendation request in case the recommendation was generated by Froomle.

 
{
    "events": [
        {
            "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",
            "action_item_type": "article",
            "request_id": "6461", //This can be found in the response body of the recommendation request in case the recommendation was generated by Froomle.
            "channel": "mobile-app",
            "user_group": "froomle" //This can be found in the response body of the recommendation request in case the recommendation was generated by Froomle.
        }
    ]
}

Subscription & Media events

Start subscription

A start_subscription event represents that the user has started a subscription to a newspaper, a streaming service, …​

  • Specification

  • Example

Field Description

event_type*

string

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

page_type*

string

Required. Page from which the event originated. Accepted page_types are: home, article, category, foryou, regional and promotion. If none of these fit your use case, please get in touch with your account manager.

device_id*

string

Required. User identifier stored in a cookie. Use the value "no-consent" for users that wish to remain anonymous.

user_id*

string

Required. User identifier of the logged in user.

subscription_type

string

Optional. Type of the started subscription, if applicable. If there are multiple possible subscription levels, these can be represented here. E.g. online, physical, …​

context_item

string

Optional. Identifier of the item in context (not interacted with). Serves as support for analysis purposes, or as history.

context_item_type

string

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

channel*

string

Required. The channel the user is currently using. Accepted channels are: www, www-desktop, www-mobile, app, app-ios, app-android, app-audio, app-audio-ios and app-audio-android. If none of these fit your use case, please get in touch with your account manager.

 
{
    "events": [
        {
            "event_type": "start_subscription",
            "page_type": "article_detail",
            "device_id": "the_device_id-123",
            "user_id": "the_user_id-123",
            "subscription_type": "physical",
            "context_item": "the_context_item_id-123",
            "context_item_type": "article",
            "channel": "www-mobile"
        }
    ]
}

Cancel subscription

A cancel_subscription event represents that the user has canceled a subscription to a newspaper, a streaming service, …​

  • Specification

  • Example

Field Description

event_type*

string

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

page_type*

string

Required. Page from which the event originated. Accepted page_types are: home, article, category, foryou, regional and promotion. If none of these fit your use case, please get in touch with your account manager.

device_id*

string

Required. User identifier stored in a cookie. Use the value "no-consent" for users that wish to remain anonymous.

user_id*

string

Required. User identifier of the logged in user.

subscription_type

string

Optional. Type of the canceled subscription, if applicable. If there are multiple possible subscription levels, these can be represented here. E.g. online, physical, …​

channel*

string

Required. The channel the user is currently using. Accepted channels are: www, www-desktop, www-mobile, app, app-ios, app-android, app-audio, app-audio-ios and app-audio-android. If none of these fit your use case, please get in touch with your account manager.

 
{
    "events": [
        {
            "event_type": "cancel_subscription",
            "page_type": "article_detail",
            "device_id": "the_device_id-123",
            "user_id": "the_user_id-123",
            "subscription_type": "physical",
            "channel": "www-mobile"
        }
    ]
}

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. Accepted page_types are: home, article, category, foryou, regional and promotion. If none of these fit your use case, please get in touch with your account manager.

device_id*

string

Required. User identifier stored in a cookie. Use the value "no-consent" for users that wish to remain anonymous.

user_id*

string

Required. User identifier of the logged in user.

checkpoint_type*

string

Required. Type of the reached checkpoint in the media entity. E.g. Start, Pause, Complete, Progress, …​

progress

number

Optional. The progress of the reached checkpoint in the media entity if applicable to the type. E.g. 0.5 would correspond to 50% of the media content consumed.

action_item*

string

Required. Identifier of the item interacted with. Is the item that you currently perform an action on if your "action" = viewing a page, then the item you view is the action item. If your action is clicking a recommendation, the item you clicked is the action item. If the action is impressing an item, the action_item is impression.

action_item_type*

string

Required. Type of the item interacted with.

channel*

string

Required. The channel the user is currently using. Accepted channels are: www, www-desktop, www-mobile, app, app-ios, app-android, app-audio, app-audio-ios and app-audio-android. If none of these fit your use case, please get in touch with your account manager.

 
{
    "events": [
        {
            "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",
            "checkpoint_type": "Progress",
            "progress": 0.1,
            "action_item_type": "episode",
            "channel": "www-mobile"
        }
    ]
}

E-Commerce 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. Accepted page_types are: home, article, category, foryou, regional and promotion. If none of these fit your use case, please get in touch with your account manager.

device_id*

string

Required. User identifier stored in a cookie. Use the value "no-consent" for users that wish to remain anonymous.

user_id*

string

Required. User identifier of the logged in user.

action_item*

string

Required. Identifier of the item interacted with. Is the item that you currently perform an action on if your "action" = viewing a page, then the item you view is the action item. If your action is clicking a recommendation, the item you clicked is the action item. If the action is impressing an item, the action_item is impression.

action_item_type*

string

Required. Type of the item interacted with.

amount*

integer

Required. Number of items added to the cart.

basket_content

Array<Item>

Optional. The current items in the user’s basket, including the added item.

channel*

string

Required. The channel the user is currently using. Accepted channels are: www, www-desktop, www-mobile, app, app-ios, app-android, app-audio, app-audio-ios and app-audio-android. If none of these fit your use case, please get in touch with your account manager.

 
{
    "events": [
        {
            "event_type": "add_to_cart",
            "page_type": "article_detail",
            "device_id": "the_device_id-123",
            "user_id": "the_user_id-123",
            "action_item": "the_action_item_id-123",
            "action_item_type": "product",
            "amount": 10,
            "channel": "www-mobile",
            "basket_content": [
                {
                    "id": "the_item_added_earlier"
                },
                {
                    "id": "the_action_item_id-123"
                }
            ]
        }
    ]
}

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. Device identifier stored in a cookie. Use the value "no-consent" for users that wish to remain anonymous.

user_id*

string

Optional. User identifier of the logged-in user.

action_item*

string

Required. Identifier of the item interacted with. Is the item that you currently perform an action on if your "action" = viewing a page, then the item you view is the action item. If your action is clicking a recommendation, the item you clicked is the action item. If the action is impressing an item, the action_item is impression.

action_item_type*

string

Required. Type of the item interacted with.

amount*

integer

Required. Number of items removed from the shopping cart.

basket_content

Array <Item>

Optional. The current items of the user’s basket, after removal of the current item.

channel*

string

Required. The channel the user is currently using. Accepted channels are: www, www-desktop, www-mobile, app, app-ios, app-android, app-audio, app-audio-ios and app-audio-android. If none of these fit your use case, please get in touch with your account manager.

 
{
    "events": [
        {
            "event_type": "remove_from_cart",
            "device_id": "the_device_id-123",
            "user_id": "the_user_id-123",
            "action_item": "the_action_item_id-123",
            "action_item_type": "product",
            "amount": 10,
            "channel": "www-mobile",
            "basket_content": [
                {
                    "id": "the_item_left_in_basket"
                }
            ]
        }
    ]
}

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. Device identifier stored in a cookie. Use the value "no-consent" for users that wish to remain anonymous.

user_id*

string

Optional. User identifier of the logged-in user.

action_item*

string

Required. Identifier of the item interacted with. Is the item that you currently perform an action on if your "action" = viewing a page, then the item you view is the action item. If your action is clicking a recommendation, the item you clicked is the action item. If the action is impressing an item, the action_item is impression.

action_item_type*

string

Required. 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

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

channel*

string

Required. The channel the user is currently using. Accepted channels are: www, www-desktop, www-mobile, app, app-ios, app-android, app-audio, app-audio-ios and app-audio-android. If none of these fit your use case, please get in touch with your account manager.

 
{
    "events": [
        {
            "event_type": "purchase",
            "device_id": "the_device_id-123",
            "user_id": "the_user_id-123",
            "action_item": "the_action_item_id-123",
            "action_item_type": "product",
            "amount": 10,
            "original_price": 29.99,
            "purchased_price": 9.99,
            "channel": "www-mobile"
        }
    ]
}

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 represent 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. Accepted page_types are: home, article, category, foryou, regional and promotion. If none of these fit your use case, please get in touch with your account manager.

device_id*

string

Required. User identifier stored in a cookie. Use the value "no-consent" for users that wish to remain anonymous.

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

Required. The channel the user is currently using. Accepted channels are: www, www-desktop, www-mobile, app, app-ios, app-android, app-audio, app-audio-ios and app-audio-android. If none of these fit your use case, please get in touch with your account manager.

 
{
    "events": [
        {
            "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": "www-mobile"
        }
    ]
}

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. Accepted page_types are: home, article, category, foryou, regional and promotion. If none of these fit your use case, please get in touch with your account manager.

device_id*

string

Required. User identifier stored in a cookie. Use the value "no-consent" for users that wish to remain anonymous.

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. Is the item that you currently perform an action on if your "action" = viewing a page, then the item you view is the action item. If your action is clicking a recommendation, the item you clicked is the action item. If the action is impressing an item, the action_item is impression.

action_item_type*

string

Required. 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

Required. The channel the user is currently using. Accepted channels are: www, www-desktop, www-mobile, app, app-ios, app-android, app-audio, app-audio-ios and app-audio-android. If none of these fit your use case, please get in touch with your account manager.

 
{
    "events": [
        {
            "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",
            "action_item_type": "article",
            "request_id": "6461",
            "campaign_id": "the_campaign_id-123",
            "channel": "mobile-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. Accepted page_types are: home, article, category, foryou, regional and promotion. If none of these fit your use case, please get in touch with your account manager.

device_id*

string

Required. User identifier stored in a cookie. Use the value "no-consent" for users that wish to remain anonymous.

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. Is the item that you currently perform an action on if your "action" = viewing a page, then the item you view is the action item. If your action is clicking a recommendation, the item you clicked is the action item. If the action is impressing an item, the action_item is impression.

action_item_type*

string

Required. 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

Required. The channel the user is currently using. Accepted channels are: www, www-desktop, www-mobile, app, app-ios, app-android, app-audio, app-audio-ios and app-audio-android. If none of these fit your use case, please get in touch with your account manager.

campaign_id*

string

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

 
{
    "events": [
        {
            "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",
            "action_item_type": "article",
            "request_id": "6461",
            "channel": "mobile-app",
            "campaign_id": "the_campaign_id-123"
        }
    ]
}

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. Accepted page_types are: home, article, category, foryou, regional and promotion. If none of these fit your use case, please get in touch with your account manager.

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. Is the item that you currently perform an action on if your "action" = viewing a page, then the item you view is the action item. If your action is clicking a recommendation, the item you clicked is the action item. If the action is impressing an item, the action_item is impression.

action_item_type*

string

Required. 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

Required. The channel the user is currently using. Accepted channels are: www, www-desktop, www-mobile, app, app-ios, app-android, app-audio, app-audio-ios and app-audio-android. If none of these fit your use case, please get in touch with your account manager.

 
{
    "events": [
        {
            "event_type": "session_click_on_recommendation",
            "session_id": "the_session_id-123",
            "list_name": "The list name",
            "action_item": "the_action_item_id-123",
            "action_item_type": "article",
            "request_id": "6461",
            "channel": "mobile-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. Accepted page_types are: home, article, category, foryou, regional and promotion. If none of these fit your use case, please get in touch with your account manager.

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. Is the item that you currently perform an action on if your "action" = viewing a page, then the item you view is the action item. If your action is clicking a recommendation, the item you clicked is the action item. If the action is impressing an item, the action_item is impression.

action_item_type*

string

Required. 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

Required. The channel the user is currently using. Accepted channels are: www, www-desktop, www-mobile, app, app-ios, app-android, app-audio, app-audio-ios and app-audio-android. If none of these fit your use case, please get in touch with your account manager.

 
{
    "events": [
        {
            "event_type": "session_impression",
            "session_id": "the_session_id-123",
            "list_name": "The list name",
            "action_item": "the_action_item_id-123",
            "action_item_type": "article",
            "request_id": "6461",
            "channel": "mobile-app"
        }
    ]
}