# Event Model and Tracking Contract

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

Events describe how users interact with your content and recommendations. They train our AI models, power your analytics dashboards, and enable accurate KPI attribution.

> **NOTE:**
> 
> This page defines the event contract shared by every integration method. For implementation instructions, use [Frontend SDK event tracking](https://docs.froomle.com/froomle-doc-main/v2/js_lib/jslib.html#EventTracking) or [Manual Event Integration](https://docs.froomle.com/froomle-doc-main/v2/guide/manual-integration/events.html).

> **IMPORTANT:**
> 
> For full request/response details and all event field specifications, see the [Events API Reference](https://docs.froomle.com/froomle-doc-main/v2/api_reference/events/events_api.html).

> **NOTE:**
> 
> **Actor Identifiers**: All events require a device identifier. For normal consented traffic this is a real `device_id`; for no-consent browser flows use the literal value `device_id: "no-consent"`. A `user_id` should be provided whenever the user is logged in and consent allows it, to enable cross-device continuity.

> **NOTE:**
> 
> **Site context**: All events may include one optional `site_context` string for dashboard segmentation, for example `"example.com"` or `"specific.example.com"`. Use it for a site, subdomain, edition, or similar customer-defined context. Keep it stable across SDK-managed and manually sent events for the same site context.

> **NOTE:**
> 
> **Subscription level**: All events may include one optional `subscription_level` string for dashboard segmentation by current visitor entitlement. Accepted values are `NONE`, `REGISTERED`, `TRIAL`, and `SUBSCRIPTION`. This describes the visitor state; it is independent of a recommended item’s `access_type` and independent of the `subscription_type` field on subscription lifecycle events.

> **NOTE:**
> 
> **UTM tracking**: Browser SDK integrations can automatically copy standard UTM URL parameters to event payloads for campaign attribution. Manual Events API integrations may send the same optional fields directly. Supported fields are `utm_id`, `utm_source`, `utm_medium`, `utm_campaign`, `utm_source_platform`, `utm_term`, `utm_content`, `utm_creative_format`, and `utm_marketing_tactic`.

> **NOTE:**
> 
> **Referrer tracking**: Browser SDK integrations can automatically add current-page and source fields from `window.location.href` with the URL fragment removed and the browser-standard `document.referrer`. Manual Events API integrations may send the same optional fields directly. Supported fields are `page_url`, `referrer_url`, `referrer_type` (`direct`, `internal`, or `external`), `referrer_origin`, and `referrer_domain`. `referrer_url` is only as complete as the browser exposes through `document.referrer`.
> 
> Persisting `page_url` and `referrer_url` enables best-effort session and source attribution. Same-site navigation can be matched when a later event’s `referrer_url` equals an earlier event’s `page_url` for the same visitor, while the first event with `referrer_type: "external"` identifies the external entry source when the browser exposes it.

<a id="_rollout_model"></a>

## Rollout model

Treat tracking as three phases:

1.  Development: prove that requests and rendering work in your development environment.
    
2.  Events go-live: bring page/business events live before recommendation placements depend on recommendation attribution.
    
3.  Recommendations go-live: once recommendation placements are live, make recommendation attribution complete as well.
    

> **IMPORTANT:**
> 
> For launched recommendation placements:
> 
> -   `impression` is required whenever a Froomle recommendation is shown.
>     
> -   `click_on_recommendation` is required whenever a Froomle recommendation is clicked.
>     
> 
> Those events are not relevant before recommendation placements exist, but they are part of launch readiness once those placements go live.

<a id="_events_go_live_page_and_business_events"></a>

## Events go-live: page and business events

These events form the baseline tracking layer and should be in place before recommendation placements depend on recommendation attribution.

> **NOTE:**
> 
> Initialized DOM integrations and mounted React `FroomleSdkInit` recover the current page event and re-observe currently visible, resolved recommendation placements after consent permits tracking. Pure programmatic integrations call `trackCurrentPage()` and recommendation event helpers explicitly. A `1 → 2` transition after anonymous delivery intentionally starts a separate identified observation period, not an update to earlier events. See [SDK automatic tracking after consent changes](https://docs.froomle.com/froomle-doc-main/v2/js_lib/jslib.html#consent-page-recovery) before adding manual tracking workarounds.

<a id="detail-pageview"></a>

### detail\_pageview

Priority: **Must**

Sent when a user views a specific item’s detail page (e.g., an article, product, or video).

-   **Trigger**: Page load of a detail view.
    
-   **Minimal JSON**:
    

```
{
  "event_type": "detail_pageview",
  "page_type": "article_detail",
  "device_id": "device-123",
  "user_id": "user-123",
  "action_item": "item-987",
  "action_item_type": "article",
  "channel": "www-desktop"
}
```

<a id="page-visit"></a>

#### Page visit

Priority: **Must**

A page visit represents the viewing of a generic page, which cannot be linked to a single item. Common examples are a view of a home page or category page.

**Minimal JSON example:**

```json
{
  "event_type": "page_visit",
  "page_type": "home",
  "device_id": "device-123",
  "user_id": "user-123",
  "channel": "www-desktop"
}
```

<a id="item-interaction"></a>

#### Item interaction

The item interaction event represents any item interaction event that is not explicitly covered by the Froomle specification. Examples are product likes or add-to-wishlists.

**Minimal JSON example:**

```json
{
  "event_type": "item_interaction",
  "interaction_type": "product_like",
  "device_id": "device-123",
  "user_id": "user-123",
  "action_item": "item-987",
  "action_item_type": "product",
  "channel": "www-desktop"
}
```

<a id="user-interaction"></a>

#### User interaction

The user interaction event represents any non-item interaction event not explicitly covered by the Froomle specification. Examples include filling in a review form or starting an interactive chatbot session.

**Minimal JSON example:**

```json
{
  "event_type": "user_interaction",
  "interaction_type": "submit_review",
  "device_id": "device-123",
  "user_id": "user-123",
  "channel": "www-desktop"
}
```

<a id="_integration_events_recommendations"></a>

### Integration events (recommendations)

Integration events track user interactions with live Froomle recommendation placements. They enable performance measurement and recommendation improvement through reinforcement learning.

> **NOTE:**
> 
> These events become applicable once recommendation placements exist. If no recommendation placement is live yet, there is nothing to attribute here.

<a id="click-on-recommendation"></a>

#### Click on recommendation

Priority: **Must when a recommendation is clicked**

This event should be triggered whenever a user clicks on a Froomle recommendation. After a click, a user is redirected to the detail page corresponding to the clicked item.

**Minimal JSON example:**

```json
{
  "event_type": "click_on_recommendation",
  "page_type": "home",
  "device_id": "device-123",
  "user_id": "user-123",
  "list_name": "recommended_for_you",
  "action_item": "item-987",
  "action_item_type": "article",
  "request_id": "req-6461",
  "channel": "www-desktop",
  "user_group": "froomle"
}
```

<a id="impression"></a>

#### Impression

Priority: **Must for live recommendation placements**

An impression event is triggered when the user is shown a Froomle recommendation. When a user receives recommendations in a carousel, only the ones that have been shown should be considered impressed.

**Minimal JSON example:**

```json
{
  "event_type": "impression",
  "page_type": "home",
  "device_id": "device-123",
  "user_id": "user-123",
  "list_name": "recommended_for_you",
  "action_item": "item-987",
  "action_item_type": "article",
  "request_id": "req-6461",
  "channel": "www-desktop",
  "user_group": "froomle"
}
```

<a id="_subscription_media_events"></a>

### Subscription & Media events

<a id="start-subscription"></a>

#### Start subscription

Priority: **Recommended**

A start\_subscription event represents that the user has started a subscription to a newspaper, a streaming service, etc.

For browser SDK integrations, call `sendStartSubscription(subscriptionType, extras?)` only after the application confirms the subscription. Declarative DOM tracking does not infer this conversion from a click. The helper includes configured `context_item` / `context_item_type` when available and can also send the event without item context. See [Subscription Conversion Events](https://docs.froomle.com/froomle-doc-main/v2/js_lib/jslib.html#SubscriptionConversionEvents).

The Events API contract permits omitting `subscription_type`; the browser SDK helper deliberately requires `subscriptionType` so browser integrations provide a stable subscription category.

**Minimal JSON example:**

```json
{
  "event_type": "start_subscription",
  "page_type": "article_detail",
  "device_id": "device-123",
  "user_id": "user-123",
  "subscription_type": "physical",
  "context_item": "item-987",
  "context_item_type": "article",
  "channel": "www-mobile"
}
```

<a id="cancel-subscription"></a>

#### Cancel subscription

A cancel\_subscription event represents that the user has canceled a subscription.

For browser SDK integrations, call `sendCancelSubscription(subscriptionType, extras?)` only after the application confirms the cancellation. The same helper is available to JS/TS, React, and script-tag integrations; it supplements any automatic DOM tracking. Configured item context is included when available, but is not required. See [Subscription Conversion Events](https://docs.froomle.com/froomle-doc-main/v2/js_lib/jslib.html#SubscriptionConversionEvents).

The Events API contract permits omitting `subscription_type`; the browser SDK helper deliberately requires `subscriptionType` so browser integrations provide a stable subscription category.

**Minimal JSON example:**

```json
{
  "event_type": "cancel_subscription",
  "page_type": "article_detail",
  "device_id": "device-123",
  "user_id": "user-123",
  "subscription_type": "physical",
  "channel": "www-mobile"
}
```

<a id="checkpoint"></a>

#### Checkpoint

A checkpoint event represents that the user has reached a specific point in consumed media (video, podcast, audio).

**Minimal JSON example:**

```json
{
  "event_type": "checkpoint",
  "page_type": "video_detail",
  "device_id": "device-123",
  "user_id": "user-123",
  "checkpoint_type": "Progress",
  "progress": 0.5,
  "action_item": "item-987",
  "action_item_type": "episode",
  "channel": "www-mobile"
}
```

<a id="_e_commerce_events"></a>

### E-Commerce events

<a id="add-to-cart"></a>

#### Add to cart

Priority: **Recommended**

An add to cart event is triggered when a user adds an item to their cart/basket. It identifies a user’s intention to buy, without certainty of purchase.

**Minimal JSON example:**

```json
{
  "event_type": "add_to_cart",
  "page_type": "product_detail",
  "device_id": "device-123",
  "user_id": "user-123",
  "action_item": "item-987",
  "action_item_type": "product",
  "amount": 2,
  "channel": "www-mobile",
  "basket_content": [
    { "id": "item-654" },
    { "id": "item-987" }
  ]
}
```

<a id="remove-from-cart"></a>

#### Remove from cart

A remove from cart event is triggered when a customer removes an item from their basket/cart.

**Minimal JSON example:**

```json
{
  "event_type": "remove_from_cart",
  "device_id": "device-123",
  "user_id": "user-123",
  "action_item": "item-987",
  "action_item_type": "product",
  "amount": 1,
  "channel": "www-mobile",
  "basket_content": [
    { "id": "item-654" }
  ]
}
```

<a id="purchase"></a>

#### Purchase

Priority: **Must**

A purchase event represents the action of buying a product on a webpage, in a physical store or on a mobile application.

**Minimal JSON example:**

```json
{
  "event_type": "purchase",
  "device_id": "device-123",
  "user_id": "user-123",
  "action_item": "item-987",
  "action_item_type": "product",
  "amount": 2,
  "original_price": 29.99,
  "purchased_price": 19.99,
  "channel": "www-mobile"
}
```

<a id="_batch_events"></a>

### Batch events

Batch events are expected to be sent when recommendations are requested in bulk (for example, when all users receive a campaign email).

<a id="batch-open"></a>

#### Batch open

Priority: **Recommended**

Batch open events represent a user opening the message that contains the recommendations (e.g., opening an email).

When the delivery platform cannot send JSON, this event can be implemented as an image-based `GET` request to the Events API. See [Track message opens with an image request](https://docs.froomle.com/froomle-doc-main/v2/guide/manual-integration/events.html#ManualTrackingPixel).

**Minimal JSON example:**

```json
{
  "event_type": "batch_open",
  "page_type": "email",
  "device_id": "device-123",
  "user_id": "user-123",
  "campaign_id": "campaign-456",
  "channel": "email"
}
```

<a id="batch-click-on-recommendation"></a>

#### Batch click on recommendation

Priority: **Must**

This event should be triggered whenever a user clicks on a recommendation in a campaign.

**Minimal JSON example:**

```json
{
  "event_type": "batch_click_on_recommendation",
  "device_id": "device-123",
  "user_id": "user-123",
  "list_name": "email_recommendations",
  "action_item": "item-987",
  "action_item_type": "article",
  "request_id": "req-6461",
  "campaign_id": "campaign-456",
  "channel": "email"
}
```

<a id="batch-impression"></a>

#### Batch impression

An impression event is triggered when the user is shown a recommendation. Only recommendations used in the campaign should result in an impression (not all requested items).

**Minimal JSON example:**

```json
{
  "event_type": "batch_impression",
  "device_id": "device-123",
  "user_id": "user-123",
  "list_name": "email_recommendations",
  "action_item": "item-987",
  "action_item_type": "article",
  "request_id": "req-6461",
  "campaign_id": "campaign-456",
  "channel": "email"
}
```

<a id="_implement_the_contract"></a>

## Implement the contract

| Method | Ownership | Implementation guide |
| --- | --- | --- |
| Frontend SDK | The browser SDK can construct and deliver page events, explicit subscription lifecycle events, and, when it owns the rendered placement metadata, recommendation-attribution events. | [Event Tracking with the Frontend SDK](https://docs.froomle.com/froomle-doc-main/v2/js_lib/jslib.html#EventTracking) |
| Manual / custom integration | Your application constructs, delivers, retries, and validates events through the Events API, Pub/Sub, or SFTP. | [Manual Event Integration](https://docs.froomle.com/froomle-doc-main/v2/guide/manual-integration/events.html) |

<a id="_full_event_specification_reference"></a>

## Full event specification reference

For complete field specifications, required vs. optional fields, and additional examples for each event type, see [Events API Reference](https://docs.froomle.com/froomle-doc-main/v2/api_reference/events/events_api.html) and the sections below.

<a id="_extended_event_specifications"></a>

### Extended event specifications

The following events are supported and use the same base fields as the core events above (`device_id`, `user_id` when available, `page_type`, `channel`, optional `site_context`, optional `subscription_level`, optional UTM fields, optional page/referrer source fields), with additional fields noted below.

<a id="_user_interaction"></a>

#### User interaction

For non-item interactions not covered by other event types (for example, a user submits a review form).

Required: `interaction_type`

<a id="_start_subscription"></a>

#### Start subscription

Represents a user starting a subscription.

Optional: `subscription_type` Optional: `context_item`, `context_item_type`

<a id="_cancel_subscription"></a>

#### Cancel subscription

Represents a user canceling a subscription.

Optional: `subscription_type` Optional: `context_item`, `context_item_type`

<a id="_checkpoint"></a>

#### Checkpoint

Represents a progress checkpoint in media consumption.

Required: `checkpoint_type` Optional: `progress` Required: `action_item`, `action_item_type`

<a id="_add_to_cart"></a>

#### Add to cart

Represents a user adding an item to their basket.

Required: `action_item`, `action_item_type`, `amount` Optional: `basket_content`

<a id="_remove_from_cart"></a>

#### Remove from cart

Represents a user removing an item from their basket.

Required: `action_item`, `action_item_type`, `amount` Optional: `basket_content`

<a id="_purchase"></a>

#### Purchase

Represents a completed purchase.

Required: `action_item`, `action_item_type`, `amount`, `purchased_price` Optional: `original_price`

<a id="_batch_open"></a>

#### Batch open

Represents a user opening a batch message (for example, an email).

Required: `campaign_id`

<a id="_batch_click_on_recommendation"></a>

#### Batch click on recommendation

Represents a click on a recommendation in a batch campaign.

Required: `list_name`, `action_item`, `action_item_type`, `request_id`, `campaign_id`

<a id="_batch_impression"></a>

#### Batch impression

Represents a recommendation impression in a batch campaign.

Required: `list_name`, `action_item`, `action_item_type`, `request_id`, `campaign_id`

<a id="_best_practices"></a>

## Best practices

-   Always retain `list_name` and `request_id` for recommendation-related events; include `user_group` when the benchmark contract requires it.
    
-   Keep `site_context`, `subscription_level`, campaign fields, and page-source fields consistent across integration methods for the same context.
    
-   Keep event schemas consistent across channels.
    
-   Apply the agreed consent behavior before adding user or device identifiers.
    

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

## Related topics

-   [Recommendation request model](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/recommendation-requests.html)
    
-   [Manual Event Integration](https://docs.froomle.com/froomle-doc-main/v2/guide/manual-integration/events.html)
    
-   [Frontend SDK event tracking](https://docs.froomle.com/froomle-doc-main/v2/js_lib/jslib.html#EventTracking)
    
-   [Batch requests](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/batch-requests.html)
    
-   [QA & Monitoring](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/qa-monitoring.html)
    
-   [Performance & Metrics](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/performance-metrics.html)