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

A website consists of multiple page types, of which home and article are the most ubiquitous examples. Other accepted values are category, foryou, regional and promotion. Every page can contain multiple Froomle modules. We apply the same concept to mobile apps.

Although less straightforward, we extend the concept of page_type to emails and push notifications. This extends the list of accepted values with: push, email, emaildaily, emailweekly, emailadhoc, and emailtopical.

If your use-case does not fit with any of the above mentioned accepted values, please get in touch with your account manager.

Knowing the page_type is important to maximize the relevance of recommendations. Furthermore, the page_type can provide important information when you are debugging your integration.


Your users can access your website or app through multiple channels, such as, for example, their browser (www) or mobile app (app). Since different channels provide different experiences, and people also tend to behave differently on different channels, knowing the channel is important to maximize the relevance of recommendations. Furthermore, the channel can provide important information when you are debugging your integration.

Accepted values are:

  • www

    • www-desktop

    • www-mobile

  • app

    • app-ios

    • app-android

  • app-audio

    • app-audio-ios

    • app-audio-android

Whether you use high-level values such as www and app, or low-level values such as www-desktop and app-ios, depends on how your websites and apps are build, how you integrate Froomle, on which level you want to differentiate recommendations and how you debug your integrations.


Customers of Froomle integrate (Froomle) modules. A module is unique, and corresponds to a unique position in the customer experience. It is defined by 3 defining values:

  • The channel (selection from a list of accepted values),

  • The page type (selection from a list of accepted values), and

  • The location on the page (free string like “top left” or “pos 6-9” or “row 6 col 2” etc.)

It is not allowed to use a module in a channel, page type or location on the page that is different from the one specified at creation time.

A module needs to be implemented as one logical unit (box). All recommendations in the module are generated in the same way and satisfy the same constraints.

In reporting, a module is the most fine-grained level.

A module has a list_name` that is unique and automatically constructed as channel_pageType_locationOnPage_optionalText_uniqueSuffix. optionalText can, for example, be the name of the box. However, this is risky. If you change the name of the box some day, you have to decomission the old module and create a new one. After the list_name has been created, the 4 values can no longer be changed.

Besides the 3 defining values, a module has other values that the customer can change over time through the Froomle portal:

  • an off-the-shelf module type,

  • filters or preferences related to the chosen module type,

  • the number of recommendations,

  • etc.

All off-the-shelf available module types are listed on the Froomle website.


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.