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