Search Tracking Overview

This guide covers how to send tracking events for search results pages using the Athos Beacon API.

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

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

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

Event Flow

Typical event sequence for a search page:

Render - When page loads and results rendered
Redirect - Only if redirect URL returned instead of results and shopper is redirected to the link provided
Impression - When results/banners enter viewport
Clickthrough OR Add to Cart - Based on shopper action

Implementation Tips

Data Source: All search event data comes from the Search API response.

Response ID: Store the responseId from the Search 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 Search 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 Search 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 Search 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

Event	When	Required Fields
render	Page loads	`responseId`
impression	Items visible	`responseId`, `results`, `banners`
clickthrough	Item clicked	`responseId`, `results` OR `banners` (1 item)
addtocart	Quick add used	`responseId`, `results` (with qty/price)
redirect	Redirect occurs	`responseId`, `redirect`

Events

1. Render

Endpoint: POST /{siteId}/search/render
When to send: Search results page loads and results are rendered

Required data fields:

responseId - Unique ID from Search API response

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

2. Redirect

Endpoint: POST /{siteId}/search/redirect
When to send: Search API returns redirect URL and shopper is redirected

Required data fields:

responseId - Unique ID from Search API response
redirect - Redirect URL from merchandising.redirect in API response

{
  "context": { /* see context guide */ },
  "data": {
    "redirect": "https://example.com/collections/all-shirts",
    "responseId": "a907d0ad-720a-4666-b046-00c0c28fb78d"
  }
}

3. Impression

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

Required data fields:

responseId - Unique ID from Search 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" }
    ]
  }
}

4. Clickthrough

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

Required data fields:

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

Product clickthrough:

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

Banner clickthrough:

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

5. Add to Cart

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

Required data fields:

responseId - Unique ID from Search 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": "0217acd9-540c-48f3-bd6d-e23128e99fa8",
    "results": [
      {
        "parentId": "8128331911111",
        "uid": "8128331907370",
        "qty": 1,
        "price": 29.99
      }
    ]
  }
}