Overview

Category Tracking Overview

This guide covers how to send tracking events for category pages using the Searchspring Beacon API.

Category tracking events capture shopper interactions on category pages. All events require a context object (see Context Object Guide) and event-specific data.

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

Note: If you are not integrating Searchspring on category pages, omit the usage of these endpoints.

📘

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 a category page:

1. Render - When page loads and results rendered
2. Impression - When results/banners enter viewport
3. Clickthrough OR Add to Cart - Based on shopper action

Implementation Tips

Data Source: All category event data comes from the Category API response (with category-specific background filters applied).

Response ID: Store the responseId from the Category API response for use in all subsequent events on that page.

Beacon 2.0 Parameter: When using Beacon 2.0 tracking, you must include beacon=true in your Category 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 Category 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.

Impressions: Only send products/banners currently visible in the viewport, fire impression events as items scroll into view.

Results vs. Banners: Although inline banners are returned in a different section of the API response than products, they are considered part of the results for beacon tracking and should be included in the results object. Non-inline merchandising banners (header, footer, and left) should be included in the banners object.

Mapping Product Identifiers: The Category 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}/category/render
When to send: Category page loads and results are rendered

Required data fields:

• responseId - Unique ID from Category API response

{
  "context": { /* see context guide */ },
  "data": {
    "responseId": "650f3e4e-1f4b-4c3a-8c3e-0d6f3e4e1f4b"
  }
}

2. Impression

Endpoint: POST /{siteId}/category/impression
When to send: Results/banners become visible to the shopper

Required data fields:

• responseId - Unique ID from Category API response
• results - Array of visible products or inline banners (can be empty)
• banners - Array of visible banners - these are the slots, left, header (primary), banner (secondary), footer (can be empty)

Product Result object:

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

Banner Result (inline banner) object:

{
  "type": "banner",
  "uid": "9912300911077"
}

Merchandising Banner object:

{
  "uid": "8128168755498"
}

Example:
The example below shows an impression event for a single product and inline banner, and a merchandising banner.

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

3. Clickthrough

Endpoint: POST /{siteId}/category/clickthrough
When to send: Shopper clicks a result/banner (navigates to PDP)

Required data fields:

• responseId - Unique ID from Category API response
• results OR banners - Single clicked item (exactly 1)

Product on inline banner clickthrough:

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

Merchandising Banner clickthrough:

{
  "context": { /* see context guide */ },
  "data": {
    "responseId": "a907d0ad-720a-4666-b046-00c0c28fb78d",
    "banners": [
      { "uid": "8128168755498" }
    ]
  }
}

4. Add to Cart

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

Required data fields:

• responseId - Unique ID from Category API response
• results - Array of products added

Product object:

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

Example:

{
  "context": { /* see context guide */ },
  "data": {
    "responseId": "650f3e4e-1f4b-4c3a-8c3e-0d6f3e4e1f4b",
    "results": [
      {
        "parentId": "8128331911111",
        "uid": "8128331907370",
        "qty": 1,
        "price": 22
      }
    ]
  }
}