# Modules and Placements

> Current Froomle documentation · [View canonical page](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/modules-and-placements.html)

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.

<a id="_module_definition"></a>

## 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.

<a id="_standardized_taxonomy"></a>

## Standardized Taxonomy

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

<a id="_channels"></a>

### 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. |

<a id="_page_types"></a>

### 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. |

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

<a id="_list_name"></a>

## 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.

<a id="_module_configuration"></a>

## 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`.

<a id="_deduplication_across_placements"></a>

## 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.

<a id="_placement_mapping_checklist"></a>

## 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).
    
-   Page/business events for that page context are already defined.
    
-   For a live recommendation placement, you can track impressions and clicks for that placement, either automatically through the SDK or manually in your own integration.
    
-   The module name is aligned between product, engineering, and analytics.
    

<a id="_news_module_catalog"></a>

## News module catalog

See [News modules](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/modules/index.html) for the default module library and usage guidance.

<a id="_related_topics"></a>

## Related topics

-   [News modules](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/modules/index.html)
    
-   [Event model and tracking contract](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/tracking-events.html)
    
-   [Filters and constraints](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/filters-and-constraints.html)
    
-   [Recommendation request model](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/recommendation-requests.html)
    
-   [Frontend SDK recommendation integration](https://docs.froomle.com/froomle-doc-main/v2/js_lib/jslib.html#SdkRecommendations)
    
-   [Manual recommendation integration](https://docs.froomle.com/froomle-doc-main/v2/guide/manual-integration/recommendations.html)