Overview

Recommendations Tracking Overview

This guide covers how to send tracking events for personalized recommendations using the Searchspring Beacon API.

Recommendations tracking events capture shopper interactions with personalized product recommendations. All events require a context object (see Context Object Guide) and event-specific data.

Base URL: https://analytics.searchspring.net/beacon/v2/{siteId}/recommendations/[event]

Key Difference: All recommendations events require a tag field identifying the recommendation profile.

📘

Note

{siteId} and [event] should be replaced with your site's siteId, found in your Searchspring management console, and the subsequent event.

Event Flow

Typical event sequence for recommendations:

1. Render - When recommendations requested from API and rendered on page
2. Impression - When recommended items enter viewport
3. Clickthrough OR Add to Cart - Based on shopper action

Recommendation Profile Tags

Common profile tags include:

• similar - Similar products
• trending - Trending products
• recently-viewed - Recently viewed items
• bought-together - Frequently bought together
• personalized - Personalized for user

The actual tags depend on your configuration in the Searchspring Management Console.

Implementation Tips

Data Source: All recommendation event data comes from the Personalized Recommendations API response.

Response ID: Store the responseId from the Recommendations API response for use in all subsequent events. Batched Recommendation API responses will all contain the same responseId for each profile in the batch - use the value provided for subsequent tracking events.

Beacon 2.0 Parameter: When using Beacon 2.0 tracking, you must include beacon=true in your Recommendation API requests. This enables automatic tracking event generation by the API and ensures proper integration with the Beacon tracking system.

Test Parameter: During development and testing, include test=true in your Recommendation API requests to prevent test events from being processed as real user interactions. This keeps your analytics and reporting data clean while you validate your implementation.

Profile Tags: Store the profile tag used in the API request to include in all tracking events for those recommendations.

Multiple Profiles: If displaying multiple recommendation profiles on a single page, track each profile separately with its own events and tag value.

Viewport Visibility: For impression events, only send items currently visible. Use intersection observers to detect when items scroll into view.

Results vs. Banners: Recommendations do not currently support any merchandising banners - an empty array should be sent in the applicable banner payloads.

Mapping Product Identifiers: The Recommendations API response returns uid and sku for each product, but beacon events require parentId, uid, and sku. For products without variants (most common), set parentId equal to uid. For products with variants, parentId should be the parent product's identifier while uid is the specific variant identifier. See the Tracking Overview for detailed examples.

Quick Reference

Events

1. Render

Endpoint: POST /{siteId}/recommendations/render
When to send: Page loads and personalized recommendations are requested from API and rendered

Required data fields:

• responseId - Unique ID from Recommendations API response
• tag - Recommendation profile tag (e.g., "similar", "trending", "recently-viewed")

{
  "context": { /* see context guide */ },
  "data": {
    "tag": "similar",
    "responseId": "42c2dc64-d203-4d74-8122-515f26afb253"
  }
}

2. Impression

Endpoint: POST /{siteId}/recommendations/impression
When to send: Recommended products/banners scroll into view
Important: Only send items currently visible in the shopper's viewport

Required data fields:

• tag - Recommendation profile tag
• responseId - Unique ID from Recommendations API response
• banners - Array of visible banners - NOT CURRENTLY SUPPORTED (can be empty)
• results - Array of visible products (optional but recommended)

Result object:

{
  "type": "product",
  "parentId": "8128331911111",
  "uid": "8128331907370",
  "sku": "SKU-123"        // optional
}

Example:

{
  "context": { /* see context guide */ },
  "data": {
    "tag": "similar",
    "responseId": "42c2dc64-d203-4d74-8122-515f26afb253",
    "results": [
      {
        "type": "product",
        "parentId": "8128331911111",
        "uid": "8128331907370"
      },
      {
        "type": "product",
        "parentId": "8128331922222",
        "uid": "8128021070122"
      }
    ],
    "banners": []
  }
}

3. Clickthrough

Endpoint: POST /{siteId}/recommendations/clickthrough
When to send: Shopper clicks a recommended product/banner (navigates to PDP)

Required data fields:

• tag - Recommendation profile tag
• responseId - Unique ID from Recommendations API response
• results OR banners - Single clicked item (exactly 1)

Product clickthrough:

{
  "context": { /* see context guide */ },
  "data": {
    "tag": "similar",
    "responseId": "a907d0ad-720a-4666-b046-00c0c28fb78d",
    "results": [
      {
        "type": "product",
        "parentId": "8128331911111",
        "uid": "8128331907370"
      }
    ]
  }
}

4. Add to Cart

Endpoint: POST /{siteId}/recommendations/addtocart
When to send: Shopper adds recommended product via "Quick Add to Cart" button
Note: Omit if Quick Add feature not implemented

Required data fields:

• tag - Recommendation profile tag
• responseId - Unique ID from Recommendations API response
• results - Array of products added

Product object:

{
  "parentId": "8128331911111",
  "uid": "8128331907370",
  "qty": 1,
  "price": 49.99,
  "sku": "SKU-123"        // optional
}

Example:

{
  "context": { /* see context guide */ },
  "data": {
    "tag": "similar",
    "responseId": "42c2dc64-d203-4d74-8122-515f26afb253",
    "results": [
      {
        "parentId": "8128331911111",
        "uid": "8128331907370",
        "qty": 1,
        "price": 49.99
      }
    ]
  }
}