Overview

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

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

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

Recommendations Flow

1. Render → Recommendations displayed
2. Impression → Items enter viewport
3. Clickthrough → Shopper clicks recommendation
4. 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

1. Read the Context Object Guide to understand the shared context structure
2. 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
3. Implement events following the patterns in the guides
4. Test with dev: true before going live