🔆What is Beacon.js

beacon.js is a high-performance TypeScript library designed to track user interactions and analytics events for the Athos Commerce Beacon API. It provides real-time insights into user behavior across search, recommendations, autocomplete, and e-commerce journeys. This package can be used by both Athos Commerce and Searchspring accounts.

📘
Want a look under the hood? Check out the full Beacon.js build by navigating to our github

🚀 Key Features

Multi-Channel Tracking: Track events from search, autocomplete, recommendations, category pages, and product pages.
Smart Batching: Automatically batches requests for optimal performance.
Local Storage Management: Manages user IDs, session IDs, cart state, and viewed products.
Attribution Tracking: Built-in support for tracking attribution and campaign sources.
Flexible Configuration: Support for custom headers, custom fetch implementations, and multiple environments.
Multi-Currency: Support for tracking transactions in different currencies.
Production Ready: Optimized for performance with features like keepalive requests and efficient batching.

🛠 Installation & Setup

The Beacon.js package can be used by both Athos Commerce and Searchspring accounts.

🚧
Using SNAP? If you are currently on/building a SNAP integration, please visit our SNAP documentation site for further information on using Beacon.js. These instructions are intended for those building with theAthos APIs.

Option 1: CDN (Recommended for Rapid Integration)

📘
Note Utilizing this package via the CDN is preferred if you plan on integrating the Athos API and are not sending events directly to the beacon endpoint.

Place the following script before the closing </head> tag. This makes the tracker available globally via window.athos.tracker.

<script siteId="YOUR_SITE_ID" src="https://cdn.athoscommerce.net/analytics/beacon.js"></script>

Option 2: NPM (For API-driven Integrations)

Ideal for applications where you want full control over the lifecycle.

npm install --save @athoscommerce/beacon

import { Beacon } from '@athoscommerce/beacon';

// Initialize Beacon with required siteId
const beacon = new Beacon({ 
  siteId: 'abc123',
  currency: { code: 'USD' }
});

// Track an autocomplete render event
beacon.events.autocomplete.render({
  data: {
    // ... render data
  }
});

// Track a product page view
beacon.events.product.pageView({
  data: {
    result: {
      uid: 'product-123',
      sku: 'SKU-123',
      parentId: 'parent-123'
    }
  }
});

👍
Pro Tip If you are building a single-page application (React, Next.js, etc.), use the NPM package. This method allows you to initialize a single Beacon instance in a Global Context or Provider to update state automatically, ensuring your attribution data is never out of sync.

⚙️ Initialization

Setting up the Beacon involves two parts: identifying your siteId and (optionally) fine-tuning how the library communicates with the API.

Basic Setup (Globals)
The first argument is the Globals object. This is where you tell the library who you are.

import { Beacon } from '@athoscommerce/beacon';

const beacon = new Beacon({ 
  siteId: 'abc123' // Your Athos Site ID
});

Mappings

Option	Type	Description	Required
`siteId`	`string`	Your unique Athos identifier.	✔️

Advanced Configuration
The second parameter to the Beacon constructor provides optional configuration for API behavior and request handling.

const beacon = new Beacon(
  { siteId: 'abc123' },
  {
    mode: 'development',
    initiator: 'my-app/1.0.0',
    requesters: {
      beacon: {
        origin: 'https://custom-beacon.example.com/beacon/v2',
        headers: { 'Authorization': 'Bearer token' }
      },
      personalization: {
        origin: 'https://custom-personalization.example.com',
        headers: { 'X-Custom-Header': 'value' }
      }
    },
    apis: {
      fetch: customFetchImplementation
    },
    href: 'https://example.com/page',
    userAgent: 'Custom User Agent'
  }
);

Mappings

Option	Type	Description	Default
`mode`	`'production' \| 'development'`	Application mode. In development mode, errors are logged to console.	`'production'`
`initiator`	`string`	Identifier for the beacon instance.	`beaconjs/{version}`
`apis.fetch`	`FetchAPI`	Custom fetch implementation.	`window.fetch`
`requesters.beacon.origin`	`string`	Custom beacon API endpoint.	Auto-detected
`requesters.beacon.headers`	`HTTPHeaders`	Custom headers for beacon API requests.	`{ 'Content-Type': 'text/plain' }`
`requesters.personalization.origin`	`string`	Custom personalization preflight endpoint.	Auto-detected
`requesters.personalization.headers`	`HTTPHeaders`	Custom headers for personalization requests.	`{}`
`href`	`string`	Override page URL for tracking.	`window.location.href`
`userAgent`	`string`	Override user agent string.	`navigator.userAgent`

🚧
Debugging: Set mode: 'development' to see detailed logs in your browser console without polluting your production analytics data.

🔑 Essential Tracking Properties

To ensure your analytics are accurate, pay close attention to these two properties. They connect the user's action back to the specific search or recommendation result.

The responseId (Required)
The responseId links events together. It is returned by Search, Autocomplete, and Recommendations APIs only if you include beacon=true in your API request.

// Always extract this from your API response
const { responseId } = apiResponse;

window.athos.tracker.events.search.render({ 
  data: { responseId } 
});

Merchandising Banner uid
When building the data payload for banners, the uid property is located within the Banner content. Here is an example of how you may choose to extract it.

// Search API Example Response
const response = {
  "merchandising": {
    "content": {
      "header": [
            "<script data-banner-id=\"440998\" data-banner-type=\"html\" data-banner-html=\"<div style=&quot;width: 100%; background: #ADD8E6; text-align: center; padding: 20px;&quot;>On Sale</div>\" type=\"text/widget\"></script><div style=\"width: 100%; background: #ADD8E6; text-align: center; padding: 20px;\">On Sale</div>"
      ],
      "banner": [],
      "footer": [],
      "left": [],
      "inline": []
    }
  }
}
function getMerchandisingBannerUid(response, type) {
  // Extract data-banner-id from the HTML string
  const htmlString = response.merchandising?.content?.[type]?.[0] || '';
  const match = typeof htmlString === 'string' && htmlString.match(/data-banner-id="(\d+)"/);
  const uid = match ? match[1] : '';
  return uid;
}
window.athos.tracker.events.search.impression({ 
  data: {
    responseId: response.responseId,
    results: [],
    banners: [
      { uid: getMerchandisingBannerUid(response, 'header') } // { uid: '440998' }
    ]
  }
});

👍
Implementation Tip: Use a helper function to regex-match data-banner-id="(\d+)" from your merchandising content. This ensures you aren't manually hardcoding IDs that might change.

📊 Tracking Events

The Beacon class provides a comprehensive event tracking system organized by feature area. Each event method accepts a payload object containing the event data. An optional siteId can be provided to override the global siteId for a specific event.

📘
Note: Every event method follows a consistent structure:
tracker.events.[category].[action]({ data: { ... } }).

Event Categories & Actions

Category	Available Actions	Context / Requirement
autocomplete	render, impression, clickThrough, addToCart, redirect	Used in the search dropdown.
search	render, impression, clickThrough, addToCart, redirect	Used on the main search results page.
category	render, impression, clickThrough, addToCart	Used on category listing pages (PLPs).
recommendations	render, impression, clickThrough, addToCart	Requires a tag (e.g., "homepage-recs").
product	pageView	Used on Product Detail Pages (PDPs).
cart	add, remove	Updates internal cart state & local storage.
order	transaction	Clears the cart and records the purchase.
shopper	login	Links a session to a Shopper ID.
error	shopifypixel, snap	Diagnostic tracking for failures.

📝Autocomplete Events

These events capture the user's journey within the search suggestion interface. All autocomplete interactions require the responseId from the API to maintain attribution.

The Workflow:

render: Fire this when the suggestion dropdown first appears.
impression: Fire this when products or banners become visible in the list.
clickThrough: Fire when a user selects a specific product or suggestion.
addToCart: Fire if a user adds to cart directly from a suggestion (this automatically updates the internal library cart state).
redirect: Fire if a suggestion triggers a hard redirect to a specific URL (e.g., a "Sale" page).

💻 Generic Implementation Structure:

// Generic structure for all Autocomplete actions
window.athos.tracker.events.autocomplete.[action]({
  data: {
    responseId: response.responseId,
    results: [{ uid: 'p1', sku: 'SKU-1' }], // For clicks, impressions, and cart adds
		banners: [{ uid: 'banner-123' }],       // For impressions
    redirect: 'https://example.com/sale'    // Only for .redirect()
  }
});

📘
Note: For a robust example of each Autocomplete Beacon event visit our Beacon.js Github

🔍 Search Events

Search events track how users interact with the main results page. Like Autocomplete, these rely heavily on the responseId to tie user behavior back to the specific search query performed.

The Workflow:

render: Fire when the search results page or results grid finishes loading.
impression: Fire as products or merchandising banners scroll into the user's view.
clickThrough: Fire when a user clicks a product to view its details.
addToCart: Fire when a user adds a product directly from the search grid.
redirect: Fire if the search query triggers a merchant-defined redirect.

💻 Generic Implementation Structure:

// All Search actions use this consistent structure:
window.athos.tracker.events.search.[action]({
  data: {
    responseId: '607bafd1-f624-4e58-afa5-b8b8e90929f5',
    results: [{ uid: 'p1', sku: 'SKU-1', price: 29.99 }], // For clicks, impressions, and cart
    banners: [{ uid: 'banner-123' }],                    // For impressions
    redirect: 'https://example.com/promo'                // Only for .redirect()
  }
});

📘
Note: For a robust example of each Search Beacon event visit our Beacon.js Github

📑 Category Events

Category events track user interactions on category or listing pages. These events rely on the responseId to link user behavior back to the specific category data returned by the system.

The Workflow:

render: Fire when the category page or results grid finishes loading.
impression: Fire as products or merchandising banners scroll into the user's view.
clickThrough: Fire when a user clicks a product from the listing to view its details.
addToCart: Fire when a user adds a product directly from the category grid.

💻 Generic Implementation Structure:

// All Category actions use this consistent structure:
window.athos.tracker.events.category.[action]({ 
  data: {
    responseId: '50c7aaf3-1909-43cd-8fff-a8e5c4452ddb',
    results: [
      { 
        type: 'product', 
        uid: 'product-1', 
        parentId: 'parent-1', 
        sku: 'SKU-1',
        qty: 1,      // Included for addToCart
        price: 49.99 // Included for addToCart
      }
    ],
    banners: [] // Used in impression events
  }
});

📘
Note: For a robust example of each Category Beacon event visit our Beacon.js Github

💡 Recommendations Events

Recommendations events track user interactions with personalized product carousels or recommendation widgets. These utilize a tag (to identify the specific widget location, like 'homepage') and a responseId to tie the interaction back to the recommendation engine's output.

The Workflow:

render: Fire when the recommendation widget finishes loading on the page.
impression: Fire when specific recommended products or banners scroll into the user's viewport.
clickThrough: Fire when a user clicks a recommended product to view its details.
addToCart: Fire when a user adds a product to their cart directly from the recommendation widget.

💻 Generic Implementation Structure:

// All Recommendations actions use this consistent structure:
window.athos.tracker.events.recommendations.[action]({ 
  data: {
    tag: 'homepage-recommendations',
    responseId: '1a304980-27d4-4f4b-96cc-758b280dfa7a',
    results: [
      { 
        type: 'product', 
        uid: 'product-1', 
        parentId: 'parent-1', 
        sku: 'SKU-1',
        qty: 1,      // Included for addToCart
        price: 39.99 // Included for addToCart
      }
    ],
    banners: [] // Used in impression events, not currently supported in recommendations
  }
});

📘
Note: For a robust example of each Recommendation Beacon event visit our Beacon.js Github

📦 Product Events

Product events track how users interact with individual product detail pages (PDP). Unlike search or category events, these focus on a single product entity and are essential for updating the user's "recently viewed" history.

The Workflow:

pageView: Fire immediately when a product detail page finishes loading. This is the primary signal for tracking product interest.

💻 Generic Implementation Structure:

// Product page views use this specific structure:
window.athos.tracker.events.product.pageView({ 
  data: {
    result: {
      uid: 'product-123',
      parentId: 'parent-123',
      sku: 'SKU-123'
    }
  }
});

🛒 Cart Events

Cart events track how users manage items in their shopping basket. These events are critical for calculating conversion rates and abandoned cart recovery, as the system automatically synchronizes the cart state with local storage.

The Workflow:

add: Fire whenever a product is added to the cart (from a PDP, quick-view, or grid).
remove: Fire when an item is deleted from the cart or the quantity is reduced to zero.

💻 Generic Implementation Structure:

// All Cart actions use this consistent structure:
window.athos.tracker.events.cart.[action]({ 
  data: {
    results: [
      { 
        uid: 'product-1', 
        parentId: 'parent-1',
        sku: 'SKU-1', 
        qty: 1, 
        price: 29.99 
      }
    ],
    // The 'cart' array should represent the full state of the basket AFTER the action
    cart: [
      { 
        uid: 'product-2', 
        parentId: 'parent-2',
        sku: 'SKU-2', 
        qty: 2, 
        price: 19.99 
      }
    ]
  }
});

📘
Note: For a robust example of each Cart Beacon event visit our Beacon.js Github

🛍️ Order Events

Order events track the final conversion step in the user journey. These events capture critical financial and geographic data, and firing a transaction automatically clears the stored cart state to prepare for the user's next session.

The Workflow:

*transaction: Fire once the user successfully completes a purchase, typically on the order confirmation page.

💻 Generic Implementation Structure:

// Order transactions use this comprehensive structure:
window.athos.tracker.events.order.transaction({ 
  data: {
    orderId: 'order-12345',
    transactionTotal: 119.97, // Total price of items
    total: 129.97,            // Final total including tax/shipping
    vat: 0.20,
    city: 'New York',
    state: 'NY',
    country: 'US',
    results: [
      { 
        uid: 'product-1', 
        parentId: 'parent-1',
        sku: 'SKU-1', 
        qty: 2, 
        price: 29.99 
      },
      { 
        uid: 'product-2', 
        parentId: 'parent-2',
        sku: 'SKU-2', 
        qty: 1, 
        price: 60.00 
      }
    ]
  }
});

⚠️ Error Tracking Events

Error tracking events are vital for monitoring the health of your integration. They capture failures within specific implementation layers, such as Shopify Pixels or SNAP, allowing developers to debug issues with real-time context from the user's session.

🚧
Note: If you are not using Shopify Pixel or have an integrated SNAP layer in your project, you can skip the following workflow

The Workflow:

shopifypixel: Fire when an error occurs specifically within the Shopify Pixel sandbox or during data mapping for Shopify-specific events.
snap: Fire when errors occur within SNAP (Search, Navigation, and Personalization) implementations, such as failed API calls or rendering timeouts.

💻 Generic Implementation Structure:

// All Error actions use this consistent structure:
window.athos.tracker.events.error.[action]({ 
  data: {
    message: 'Detailed error description',
    stack: 'The stack trace or specific line of failure',
    details: { 
      // Contextual metadata relevant to the error
      productId: 'abc-123',
      tag: 'homepage-recs',
      endpoint: '/api/v1/endpoint'
    }
  }
});

📘
Note: For a robust example of each Error Beacon event visit our Beacon.js Github

💾 Storage & Context Management

Beacon.js automatically manages local storage and cookies to maintain user state across sessions. This powers attribution, "Recently Viewed" lists, and persistent carts without extra code.

User IDs: Persisted for 18 months.
Session IDs: Persisted for 30 minutes.
Cart: Current items in the user's cart
Viewed Products: Recently viewed products (up to 20 items)
Attribution: Campaign/attribution source tracking

Manual Storage Control

While management is automatic, you can manually interact with these stores if your site has custom requirements (e.g., a "Clear My History" button).

// Accessing the Cart Store
const cart = beacon.storage.cart.get(); 
beacon.storage.cart.clear();

// Accessing Viewed Products
const history = beacon.storage.viewed.get();
beacon.storage.viewed.add([{ uid: 'p2', sku: 'SKU-2' }]);

📘
Note: For more in depth examples of how to access and manipulate the tracked cart and viewed products visit our Beacon.js Github

🛠️ Developer Toolkit

The Beacon instance provides several utility methods to manage user identity, tracking context, and session state.

Reference Chart

Method	Type	Description
`setShopperId(id)`	Action	Links a session to a specific customer ID. Triggers a login event and refreshes personalization.
`pageLoad()`	Action	Required for SPAs. Generates a new Page Load ID. Call this method when tracking page transitions or navigation within a single-page application.
`setCurrency({code})`	Action	Sets the ISO 4217 currency code (e.g., 'USD', 'EUR') for all financial events.
`updateContext(k, v)`	Action	Dynamically updates context properties like `pageUrl` or `dev` flags.
`sendPreflight()`	Action	Sends preflight data to the personalization API. This is automatically called when cart or shopper state changes, but can be manually triggered if needed.
`getContext()`	Info	Gets the current tracking context including user, session, and page information.
`getUserId()`	Info	Returns the persistent 18-month UUID for the visitor.
`getSessionId()`	Info	Returns the current 30-minute session ID.

👍
Want more Examples? View the full list of our Beacon.js public API methods, with use case examples at our Beacon.js Github

🏁 Wrapping Up

You now have the core building blocks for a full Athos Commerce Beacon.js integration. By implementing the event workflows above, you've ensured that search behavior, product interest, and conversion data are all communicating seamlessly with the Athos API!

Need to go deeper?

While the default setup handles the vast majority of e-commerce environments, Beacon.js is built to be flexible. If your project requires custom fetch implementations, API proxying, or complex environment overrides, we have you covered.

You can find documentation for these edge cases, along with full TypeScript definitions and low-level utility methods, in our Beacon.js GitHub Repository.

👍
Want more Examples? You can find documentation for these edge cases, along with full TypeScript definitions and low-level utility methods, in our **Beacon.js GitHub Repository **.

🥳
Happy coding! If you run into issues, remember to enable mode: 'development' to see real-time debugging logs in your console.