Event Model and Tracking Contract

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

This page defines the event contract shared by every integration method. For implementation instructions, use Frontend SDK event tracking or Manual Event Integration.

For full request/response details and all event field specifications, see the Events API Reference.

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.

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.

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.

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.

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.

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.

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.

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.

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"
}

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:

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

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:

{
  "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"
}

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:

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

Integration events (recommendations)

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

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

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:

{
  "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"
}

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:

{
  "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"
}

Subscription & Media events

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.

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:

{
  "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"
}

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.

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:

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

Checkpoint

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

Minimal JSON example:

{
  "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"
}

E-Commerce events

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:

{
  "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" }
  ]
}

Remove from cart

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

Minimal JSON example:

{
  "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" }
  ]
}

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:

{
  "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"
}

Batch events

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

Batch open

Priority: Recommended

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

Minimal JSON example:

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

Batch click on recommendation

Priority: Must

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

Minimal JSON example:

{
  "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"
}

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:

{
  "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"
}

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

Manual / custom integration

Your application constructs, delivers, retries, and validates events through the Events API, Pub/Sub, or SFTP.

Manual Event Integration

Full event specification reference

For complete field specifications, required vs. optional fields, and additional examples for each event type, see Events API Reference and the sections below.

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.

User interaction

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

Required: interaction_type

Start subscription

Represents a user starting a subscription.

Optional: subscription_type Optional: context_item, context_item_type

Cancel subscription

Represents a user canceling a subscription.

Optional: subscription_type Optional: context_item, context_item_type

Checkpoint

Represents a progress checkpoint in media consumption.

Required: checkpoint_type Optional: progress Required: action_item, action_item_type

Add to cart

Represents a user adding an item to their basket.

Required: action_item, action_item_type, amount Optional: basket_content

Remove from cart

Represents a user removing an item from their basket.

Required: action_item, action_item_type, amount Optional: basket_content

Purchase

Represents a completed purchase.

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

Batch open

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

Required: campaign_id

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

Batch impression

Represents a recommendation impression in a batch campaign.

Required: list_name, action_item, action_item_type, request_id, campaign_id

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.

Related topics