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 customer_token.froomle.com. This URL is followed by /api/environment/events. The Froomle support team will decide on the values of customer_token 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

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

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://{customer_token}.froomle.com/api/{environment}/events' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer X' \
--data-raw '{
  "events": [
    {
        "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"
    },
    {
        "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"
    },
    {
        "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"
    },
    {
        "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"
    }
  ]
}'

Definitions

Event

For all events that can be used in the froomle integration see concepts/Events

Polymorphism : Composition

Name Description Schema

device_id
optional

Unique identifier of the current user’s session, usually stored in a cookie

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