Autocomlete Tracking Overview

This guide covers how to send tracking events for autocomplete/typeahead search interactions using the Athos Beacon API.

Autocomplete tracking events capture shopper interactions with the autocomplete dropdown that appears as users type in the search bar. All events require a context object (see Context Object Guide) and event-specific data.

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

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

Event Flow

Typical event sequence for autocomplete interactions:

Render - When user types and autocomplete dropdown appears with results
Redirect - Only if redirect URL returned instead of results and shopper is redirected to the link provided
Impression - When results/banners become visible in dropdown
Clickthrough OR Add to Cart - Based on shopper action in dropdown

Implementation Tips

Data Source: All autocomplete event data comes from the Autocomplete API response.

Response ID: Store the responseId from the Autocomplete API response for use in all subsequent events related to that autocomplete session.

Beacon 2.0 Parameter: When using Beacon 2.0 tracking, you must include beacon=true in your Autocomplete 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 Autocomplete 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: For autocomplete, typically all results in the dropdown are visible at once, so send all results in a single impression event.

Typing Behavior: Each new search query (different text) should generate a new render event with its own responseId. Don't send render events on every keystroke - wait for API response. We recommend a 200ms debounce.

Dropdown Closure: When the autocomplete dropdown closes without interaction, no additional events are needed.

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 Autocomplete 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	Dropdown opens with results	`responseId`
impression	Items visible in dropdown	`responseId`, `results`, `banners`
clickthrough	Item clicked from dropdown	`responseId`, `results` OR `banners` (1 item)
addtocart	Quick add used in dropdown	`responseId`, `results` (with qty/price)
redirect	Redirect occurs	`responseId`, `redirect`

Events

1. Render

Endpoint: POST /{siteId}/autocomplete/render
When to send: Shopper types in searchbar and autocomplete results are rendered in dropdown

Required data fields:

responseId - Unique ID from Autocomplete API response

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

2. Redirect

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

Required data fields:

responseId - Unique ID from Autocomplete 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}/autocomplete/impression
When to send: Autocomplete results/banners become visible in the dropdown

Required data fields:

responseId - Unique ID from Autocomplete 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)

Result object:

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

Example:

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

4. Clickthrough

Endpoint: POST /{siteId}/autocomplete/clickthrough
When to send: Shopper clicks an autocomplete result/banner from dropdown (navigates to PDP)

Required data fields:

responseId - Unique ID from Autocomplete 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}/autocomplete/addtocart
When to send: Shopper adds product via "Quick Add to Cart" button in autocomplete dropdown
Note: Omit if Quick Add feature not implemented

Required data fields:

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

Product object:

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

Example:

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