Tracking Events

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

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

Actor Identifiers: All events require a device_id. A user_id should be provided whenever the user is logged in to enable cross-device continuity.

Essential Events

These events are required for basic integration and go-live.

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 Froomle recommendations. They enable performance measurement and recommendation improvement through reinforcement learning.

Click on recommendation

Priority: Must

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: Recommended

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.

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.

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

Event delivery channels

You can send events via:

  • Events API (front-end or back-end). See Events API Reference.

  • SDK/code templates for web and mobile.

  • PubSub for streaming pipelines (beta).

  • SFTP for offline or batch events (for example, email opens).

Pub/Sub (beta)

If you publish events via Pub/Sub, the typical flow is:

  1. Align on which event types will be shared.

  2. Receive Pub/Sub specs and access from Froomle.

  3. Map your events to the Froomle event schema.

  4. Link your stream to the Froomle stream (csv/tsv/json supported).

  5. Froomle validates the implementation.

This option is in beta and requires coordination with support.

Using the SDK vs. custom implementation

If you use the SDK, event payload construction, batching, and retry logic are handled for you. You still need to:

  • Provide stable list_name, page_type, channel, and identifiers.

  • Ensure consent handling rules are applied in your app or site.

If you do not use the SDK, you must implement the Events API calls yourself and enforce the event schema, required fields, and retries.

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. Use SFTP for non-time-sensitive events (for example, email opens or historic events). It is batch-oriented and not suited for real-time use cases.

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), 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

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 pass list_name, request_id, and user_group in recommendation-related events.

  • Keep event schemas consistent across channels.

  • For no-consent users, do not send events.

Related topics