Understanding the Froomle platform

This page explains the basic concepts we use in our platform.


It’s important that Froomle knows who’s calling. Environments are Froomle’s way to identify sandboxed integrations with separated data (items and events). By default we provide a production and a test environment for each of your brands. The environment is specified in the url of our API calls.

Page type

Froomle likes to respond to every one of your calls in a relevant way, that’s why we need to know where you’re calling from. We call this a page-type.

Page-types identify a unique location where you’ve integrated one or more Froomle modules that is distinctly different from other locations and in addition, this page-type is useful to differentiate on in our reporting.

We expect the following page_types:

  • home

  • article_detail

  • category

  • other

If you call Froomle with a previously unknown page-type, we won’t know what to do. So if you want to deploy us on a new page-type, we should be in touch.


The channel field is used to identify which version of your website the user is seeing. It is important to make this distinction when analyzing user behavior: different channels lead to different user experiences. We expect the following channels:

  • www-desktop: for users visiting your website from their computer

  • www-mobile: for users visiting your website from their mobile phone/tablet

  • mobile-app: for users using an app to visit your content

  • test: to be used during the integration phase if the real channel cannot be passed yet.


Froomle will provide you with a $CLIENT_ID and $CLIENT_SECRET through the Froomle portal once the project is initiated. These credentials will need to be used to retrieve a Bearer token. These tokens can then be used to retrieve recommendations, and manage your item metadata. Events can be ingested without being authenticated. Below you can find an example:

curl --request POST \
  --url "https://{subdomain}.froomle.com/oauth/token" \
  --header "content-type: application/json" \
  --data "{\"client_id\":\"$CLIENT_ID\",\"client_secret\":\"$CLIENT_SECRET\"}"


Froomle can identify your users by either device_id and/or user_id. A device_id is anything that is tied to a specific device or browser, such as a cookie set on your website. A user_id is expected to be long-lived and used across devices, e.g. a login ID. See Users for more information.

AB Testing & Benchmarking

Froomle uses AB testing to optimize our modules for each use case. We also support benchmarking against recommendations from third parties or with a benchmark we set up ourselves. The AB Testing page describes which options we support.