Events API Events are at the heart of Froomle. They represent the actions the user takes on your website, which fuel our machine learning models. The structure of the events we require, and the events we need is described in the Events pages. To stream these events to the Froomle platform you use your personal HTTP API at subdomain.froomle.com. This URL is followed by /api/environment/events. The Froomle support team will decide on the values of subdomain and environment with you at kick-off of the project. Back-end integration When integrating Froomle into a back-end service, it is recommended to send events to the endpoint in batches. Implementing this is especially applicable during peaks of high traffic and will speed up the response time. The recommended amount of time between two batches is 500 milliseconds. Delays up to 1 second are acceptable. Delays up to 5 seconds have a potential negative influence on the quality of recommendations. Delays >1 minute have a guaranteed negative effect on the quality of recommendations. Front-end integration When integrating Froomle into a front-end service, the events have to be sent as they occur. For events that occur in rapid succession or at the same time (e.g. multiple impression events), it is still recommended to send events in a single request to the endpoint. Specification Log an event of any form to the Froomle Event API. POST /{environment}/events Parameters Type Name Description Schema Path environment required The environment for which this event is sent. string Body body required body body Name Schema events required < Event > array Responses HTTP Code Description Schema 200 Event was accepted and will be processed. No Content 400 The event body was not in the right format or was missing mandatory information. No Content 400 "Events contain errors: ……. See exact response for details. Typical examples include channel/page_type/list_name with an invalid value or missing mandatory fields." No Content 415 The event body is not of type json. No Content 500 Something went wrong while processing. No Content Consumes application/json cURL Example $ curl --location --request POST 'https://{subdomain}.froomle.com/api/{environment}/events' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer X' \ --data-raw '{ "events": [ { //send whenever a user visits an item detail page (regardless of a Froomle module being shown) "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" }, { //send whenever a user gets a recommendation in view "event_type": "impression", "page_type": "home", "device_id" : "the_device_id-123", "user_id" : "the_user_id-123", //data from the recommendation "list_name" : "The list name", "action_item" : "the_action_item_id-123", "action_item_type" : "article", "request_id": "6461", "channel": "mobile-app", "user_group": "froomle" }, { //send whenever a user clicks on a recommendation (Froomle or baseline) "event_type": "click_on_recommendation", "page_type": "home", "device_id" : "the_device_id-123", "user_id" : "the_user_id-123", //data from the recommendation "list_name" : "The list name", "action_item" : "the_action_item_id-123", "action_item_type" : "article", "request_id": "6461", "channel": "mobile-app", "user_group": "froomle" }, { //send whenever a user visits a page other than an item detail page (regardless of a Froomle module being shown) "event_type": "page_visit", "page_type": "home", "device_id" : "the_device_id-123", "user_id" : "the_user_id-123", "channel" : "www-desktop" }, { //send when a user purchases an item "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" } ] }' Definitions Event For all events that can be used in the froomle integration see concepts/Events Polymorphism : Composition Name Description Schema device_id required Unique identifier of the current user’s session, usually stored in a cookie. Use the value "no-consent" for users that wish to remain anonymous. string user_id optional User id of the authenticated user string event_type optional needs to be exactly Event string action_item required The item id of the item interacted with string action_item_type required Type of the item interacted with string