Overview

The Beacon API tracks shopper interactions across your e-commerce site to provide data for analytics, reporting, and personalization. All events are sent via POST requests to https://analytics.searchspring.net/beacon/v2/{siteId}/[module]/[event].

📘
Note
{siteId}, [module], and [event] should be replaced with your site's siteId, found in your Searchspring management console, the module for the requests (autocomplete, search, etc.), and the subsequent event.

Event Structure

Every tracking event requires two components context and data:

{
  "context": {
    // shopper and session information (consistent across all events)
    "timestamp": "2024-06-11T17:47:04.075876Z",
    "pageUrl": "https://example.com/page",
    "userId": "uuid",
    "sessionId": "uuid",
    "pageLoadId": "uuid",
    "initiator": "{{ company }}/{{ framework }}/{{ version }}"
  },
  "data": {
    // event-specific information (varies by event type)
  }
}

Full Context Object Guide - Learn how to construct the context object

Quick Reference

Module	Events	Data Source	Key Fields
Search	render, impression, clickthrough, addtocart, redirect	Search API	responseId, results, banners
Category	render, impression, clickthrough, addtocart	Category API	responseId, results, banners
Autocomplete	render, impression, clickthrough, addtocart, redirect	Autocomplete API	responseId, results, banners
Recommendations	render, impression, clickthrough, addtocart	Recommendations API	tag, responseId, results
Cart	add, remove	Cart page data	results, cart
Product	pageview	PDP data	result
Shopper	login	Auth data	context only
Order	transaction	Order data	orderId, total, results

Event Categories

Search & Discovery Events

Search - Track search results page interactions
Category - Track category page interactions (if integrated)
Autocomplete - Track autocomplete dropdown interactions
Recommendations - Track personalized product recommendations

Common Events: render, impression, clickthrough, addtocart, redirect*

Key Data Fields:

responseId - From API response (required for all)
tag - Recommendation profile (recommendations only)
results / banners - Products/banners displayed or clicked

Shopping Platform Events

Cart - Track cart modifications
Product - Track product page views
Shopper - Track shopper authentication
Order - Track completed transactions

Events:

cart/add - Item added or quantity increased
cart/remove - Item removed or quantity decreased
product/pageview - PDP visited
shopper/login - Successful authentication
order/transaction - Purchase completed

Key Data Fields:

Cart: results (items changed), cart (full cart state)
Product: result (product identifiers)
Shopper: Context only (no data object)
Order: orderId, transactionTotal, total, results

When to Send Events

Search/Category/Autocomplete Flow

Render → Results displayed on page
Impression → Items enter viewport
Clickthrough → Shopper clicks item
Add to Cart → Quick add button used
Redirect → Redirect URL triggered (search/autocomplete only)

Recommendations Flow

Render → Recommendations displayed
Impression → Items enter viewport
Clickthrough → Shopper clicks recommendation
Add to Cart → Quick add button used

Shopping Platform Events

Product Pageview → On every PDP load
Cart Add/Remove → On cart modifications
Shopper Login → On successful authentication
Order Transaction → On order confirmation page

Mapping Product Data from API Responses

When tracking product interactions (impression, clickthrough, addtocart), the beacon events require parentId, uid, and optionally sku. However, the Search, Category, Autocomplete, and Recommendations APIs only return uid and sku in their responses.

Key Mapping Rule:

For products without variants (most common case):

Set parentId equal to uid from the API response
Set uid to the same uid value from the API response
Set sku to the sku value from the API response (if available)

For products with variants:

Set parentId to the parent product's unique identifier
Set uid to the specific variant's unique identifier
Set sku to the variant's SKU (if applicable)

Example:

API returns:

{
  "uid": "8128331907370",
  "sku": "SHIRT-BLUE-M"
}

Beacon event should send:

{
  "parentId": "8128331907370",
  "uid": "8128331907370",
  "sku": "SHIRT-BLUE-M"
}

Note: The parentId field is critical for variant tracking and analytics. When a product has no variants, treating the product itself as both parent and variant ensures proper data consistency.

Best Practices

Identifiers:

Generate UUIDs for userId, sessionId, pageLoadId
Store userId in long-lived cookie/localStorage
Store sessionId in session cookie
Generate pageLoadId once per page load

Testing:

Set dev: true in context to exclude from reporting
Verify all required fields present
Test with both text/plain and application/json

Performance:

Batch impression events when possible
Send events asynchronously
Respect 1MB payload limit

Accuracy:

Only send impressions for visible items - do not resend unless a new render displays new products
Capture timestamps when events occur (not when sent)
Include shopperId when user is authenticated

Getting Started

Read the Context Object Guide to understand the shared context structure
Choose the relevant event guide(s) for your integration:
- Search results pages → Search Events Guide
- Category pages → Category Events Guide
- Personalized recommendations → Recommendations Events Guide
- Cart, product, shopper, order → Shopping Platform Events Guide
Implement events following the patterns in the guides
Test with dev: true before going live