Modules and Placements

Modules are the core building blocks of a Froomle integration. A module represents one distinct placement in a channel and page type, such as a "Continue Reading" box on an article page or a "Recommended for you" block on a home page.

Module definition

A module is a logical "slot" in your user experience. It is defined by three immutable dimensions that align with industry-standard tracking frameworks (such as Google Analytics 4 or Snowplow):

  1. Channel: The platform where the request originates (e.g., website, mobile app).

  2. Page Type: The logical category of the page or screen (e.g., home, article, category).

  3. Placement: A unique label for the location on that specific page/screen (e.g., sidebar, bottom).

These three values determine a unique module and should not change after go-live. Changing any of them requires a new module definition in the Froomle backend.

Standardized Taxonomy

To ensure data consistency between your analytics platform and Froomle, we recommend using the following standardized values.

Channels

The channel helps Froomle understand the device constraints and user behavior patterns of different platforms. This maps to the Platform dimension in GA4 or Snowplow.

Froomle Value Industry Mapping Description

www

GA4: Web / Snowplow: web

General website traffic.

www-desktop

-

Specific for desktop browser experiences.

www-mobile

-

Specific for mobile browser experiences.

app-ios

GA4: iOS / Snowplow: mob

Native iOS application.

app-android

GA4: Android / Snowplow: mob

Native Android application.

email

-

Outbound newsletter or email placement.

Page Types

The page type tells Froomle the intent of the user. This maps to the custom page_type dimension used in most professional GA4 and Snowplow implementations. Pages with _detail suffix refer to a page where a single item is displayed. Pages without _detail suffix refer to a page where a list of items is displayed.

Froomle Value GA4/Snowplow equivalent Description

home

homepage

The main entry point of the site or app.

category

category_page or listing

A list of items belonging to one topic.

article_detail

article_detail or blog_post

A single piece of content (news, blog, etc.).

video_detail

video_page or media_detail

A page centered around a video player.

product_detail

product_detail

A specific product page (for e-commerce).

item_detail

content_detail or item_page

A generic detail page for any non-specific item type.

search

search_results

Results from an internal site search.

checkout

cart or checkout

Finalization of a transaction.

other

other or uncategorized

A catch-all for pages that do not fit into the primary categories.

If your team uses a dataLayer in Google Tag Manager, we recommend using the exact same page_type variable for your Froomle API requests.

list_name

Each module has a list_name, which is the identifier you use in recommendation requests and event tracking. It must be:

  • Unique per placement.

  • Stable over time.

  • Meaningful enough to map to the placement (but not dependent on a UI label that could change).

Froomle constructs list_name as channel_pageType_location_optionalText. Avoid changing optionalText after go-live.

Module configuration

Beyond the defining fields, a module can be configured with:

  • Strategy (personalized, similar, topical, editor-curated).

  • Filters and constraints.

  • List size (number of recommendations).

These settings can evolve over time without changing the list_name.

Deduplication across placements

If multiple modules appear on the same page, configure deduplication rules so items are not repeated across placements. This typically requires consistent list_name usage and, when needed, passing visible item IDs in the request context.

Placement mapping checklist

Use the checklist below when defining your placements:

  • The placement appears in a consistent context (same channel and page type).

  • You can provide any required context (for example, a current item or category).

  • You can track impressions and clicks for that placement.

  • The module name is aligned between product, engineering, and analytics.

News module catalog

See News modules for the default module library and usage guidance.

Related topics