A TypeScript library for tracking user interactions and analytics events to Athos Commerce's Beacon API. This library enables real-time tracking of user behavior across search, recommendations, autocomplete, and e-commerce interactions.
This package can be used by both Athos Commerce and Searchspring accounts.
- 🎯 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
To use the beacon via our CDN build, place the following script before the page's closing </head> tag:
<script siteId="[REPLACE WITH ATHOS OR SEARCHSPRING SITEID]" src="https://cdn.athoscommerce.net/analytics/beacon.js"></script>The beacon will then be available for usage via window.athos.tracker
<script>
window.athos.tracker.events.search.render({ data: { responseId: '35e5ea31-a537-471b-ba2b-6eea9caebe62' }})
</script>Utilizing this package via the CDN is preferred if you either:
- plan on integrating Athos API and are not sending events directly to the beacon endpoint.
OR
- You are actively developing an integration, however would like to start tracking events before going live with the integration. Note that after going live with a Snap integration, this beacon.js should be removed from the website, however the function calls can remain on the website. The Snap integration will publish an identical reference of this Beacon to the same path:
window.athos.tracker.
If you are integrating Athos via API instead of utilizing Snap, the @athoscommerce/beacon package is available to use for your convenience.
npm install --save @athoscommerce/beaconimport { 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'
}
}
});The first parameter to the Beacon constructor contains required and optional global configuration that applies to all tracking events.
import { Beacon } from '@athoscommerce/beacon';
const beacon = new Beacon({ siteId: 'abc123' });| Option | Type | Description | Required |
|---|---|---|---|
siteId |
string |
Your Athos site ID | ✔️ |
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'
}
);| 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 based on siteId |
requesters.beacon.headers |
HTTPHeaders |
Custom headers for beacon API requests | { 'Content-Type': 'text/plain' } |
requesters.personalization.origin |
string |
Custom personalization preflight endpoint | Auto-detected based on siteId |
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 |
The Athos Search, Autocomplete, and Recommendations APIs will return a responseId property that is required on most beacon event's payload. It will only be returned if the beacon=true parameter is provided to each API.
// Search API Example Response
const response = {
"breadcrumbs": [...],
"merchandising": {...},
"pagination": {...},
"query": {...},
"responseId": "f70594d2-c360-4292-8711-b256567099d3"
"results": [...],
"sorting": {...},
}
window.athos.tracker.events.search.render({
data: {
responseId: response.responseId,
}
});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="width: 100%; background: #ADD8E6; text-align: center; padding: 20px;">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' }
]
}
});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.
Track when a user logs into their shopper account.
window.athos.tracker.events.shopper.login({
data: { id: 'shopper-12345' }
});Autocomplete events track user interactions within the autocomplete/search suggestions interface.
Track when autocomplete suggestions are rendered to the user.
window.athos.tracker.events.autocomplete.render({
data: {
responseId: response.responseId
}
});Track impressions (visibility) of autocomplete suggestions.
window.athos.tracker.events.autocomplete.impression({
data: {
responseId: response.responseId,
results: [
{ type: 'product', uid: 'product-1', parentId: 'parent-1', sku: 'SKU-1' },
{ type: 'banner', uid: 'banner-1' }
],
banners: [
{ uid: 'banner-1' }
]
}
});Track when a user adds a product to cart from autocomplete results.
window.athos.tracker.events.autocomplete.addToCart({
data: {
responseId: response.responseId,
results: [
{
uid: 'product-1',
parentId: 'parent-1',
sku: 'SKU-1',
qty: 1,
price: 29.99
}
]
}
});This method automatically manages the stored cart state.
Track when a user clicks on an autocomplete suggestion.
window.athos.tracker.events.autocomplete.clickThrough({
data: {
responseId: response.responseId,
results: [
{
type: 'product',
uid: 'product-1',
parentId: 'parent-1',
sku: 'SKU-1'
}
]
}
});Track when an autocomplete suggestion causes a page redirect.
const redirectUrl = response.merchandising?.redirect; // 'https://example.com/sale-page'
window.athos.tracker.events.autocomplete.redirect({
data: {
redirect: redirectUrl,
responseId: response.responseId
}
});Search events track user interactions within search results pages.
window.athos.tracker.events.search.render({
data: {
responseId: '607bafd1-f624-4e58-afa5-b8b8e90929f5'
}
});window.athos.tracker.events.search.impression({
data: {
responseId: '607bafd1-f624-4e58-afa5-b8b8e90929f5',
results: [
{ type: 'product', uid: 'product-1', parentId: 'parent-1', sku: 'SKU-1' },
{ type: 'product', uid: 'product-2', parentId: 'parent-2', sku: 'SKU-2' }
],
banners: [{ uid: 'banner-1' }]
}
});window.athos.tracker.events.search.addToCart({
data: {
responseId: '607bafd1-f624-4e58-afa5-b8b8e90929f5',
results: [
{
uid: 'product-1',
parentId: 'parent-1',
sku: 'SKU-1',
qty: 1,
price: 29.99
}
]
}
});window.athos.tracker.events.search.clickThrough({
data: {
responseId: '607bafd1-f624-4e58-afa5-b8b8e90929f5',
results: [
{
type: 'product',
uid: 'product-1',
parentId: 'parent-1',
sku: 'SKU-1'
}
]
}
});window.athos.tracker.events.search.redirect({
data: {
redirect: 'https://example.com/promo',
responseId: '607bafd1-f624-4e58-afa5-b8b8e90929f5'
}
});Category events track user interactions on category/listing pages.
window.athos.tracker.events.category.render({
data: {
responseId: '50c7aaf3-1909-43cd-8fff-a8e5c4452ddb'
}
});window.athos.tracker.events.category.impression({
data: {
responseId: '50c7aaf3-1909-43cd-8fff-a8e5c4452ddb',
results: [
{ type: 'product', uid: 'product-1', parentId: 'parent-1', sku: 'SKU-1' }
],
banners: []
}
});window.athos.tracker.events.category.addToCart({
data: {
responseId: '50c7aaf3-1909-43cd-8fff-a8e5c4452ddb',
results: [
{
uid: 'product-1',
parentId: 'parent-1',
sku: 'SKU-1',
qty: 1,
price: 49.99
}
]
}
});window.athos.tracker.events.category.clickThrough({
data: {
responseId: '50c7aaf3-1909-43cd-8fff-a8e5c4452ddb',
results: [
{
type: 'product',
uid: 'product-1',
parentId: 'parent-1',
sku: 'SKU-1'
}
]
}
});Recommendations events track interactions with personalized product recommendations.
Track when a recommendation set is rendered to the user.
window.athos.tracker.events.recommendations.render({
data: {
tag: 'homepage-recommendations',
responseId: '1a304980-27d4-4f4b-96cc-758b280dfa7a'
}
});Track impressions of recommended products.
window.athos.tracker.events.recommendations.impression({
data: {
tag: 'homepage-recommendations',
responseId: '1a304980-27d4-4f4b-96cc-758b280dfa7a',
results: [
{ type: 'product', uid: 'product-1', parentId: 'parent-1', sku: 'SKU-1' },
{ type: 'product', uid: 'product-2', parentId: 'parent-2', sku: 'SKU-2' }
],
banners: []
}
});Track when a user adds a recommended product to cart.
window.athos.tracker.events.recommendations.addToCart({
data: {
tag: 'homepage-recommendations',
responseId: '1a304980-27d4-4f4b-96cc-758b280dfa7a',
results: [
{
uid: 'product-1',
parentId: 'parent-1',
sku: 'SKU-1',
qty: 1,
price: 39.99
}
]
}
});Track clicks on recommended products.
window.athos.tracker.events.recommendations.clickThrough({
data: {
tag: 'homepage-recommendations',
responseId: '1a304980-27d4-4f4b-96cc-758b280dfa7a',
results: [
{
type: 'product',
uid: 'product-1',
parentId: 'parent-1',
sku: 'SKU-1'
}
]
}
});Track product page views. This automatically updates the viewed products history.
window.athos.tracker.events.product.pageView({
data: {
result: {
uid: 'product-123',
parentId: 'parent-123',
sku: 'SKU-123'
}
}
});Track when products are added to the cart.
window.athos.tracker.events.cart.add({
data: {
results: [
{
uid: 'product-1',
parentId: 'parent-1',
sku: 'SKU-1',
qty: 1,
price: 29.99
}
],
cart: [
{
uid: 'product-1',
parentId: 'parent-1',
sku: 'SKU-1',
qty: 1,
price: 29.99
},
{
uid: 'product-2',
parentId: 'parent-2',
sku: 'SKU-2',
qty: 2,
price: 19.99
}
]
}
});The cart state is automatically managed and synchronized with storage.
Track when products are removed from the cart.
window.athos.tracker.events.cart.remove({
data: {
results: [
{ uid: 'product-1', parentId: 'parent-1', sku: 'SKU-1', qty: 1 }
],
cart: [
{
uid: 'product-2',
parentId: 'parent-2',
sku: 'SKU-2',
qty: 2,
price: 19.99
}
]
}
});Track completed transactions/orders.
window.athos.tracker.events.order.transaction({
data: {
orderId: 'order-12345',
transactionTotal: 119.97,
total: 129.97,
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
}
]
}
});This method automatically clears the stored cart after tracking the transaction.
Track errors from Shopify pixel implementations.
window.athos.tracker.events.error.shopifypixel({
data: {
message: 'Product not found',
stack: 'Error: Product not found\n at fetchProduct (app.js:45)',
details: {
productId: 'abc-123',
endpoint: '/api/products/abc-123'
}
}
});Track errors from SNAP implementations.
window.athos.tracker.events.error.snap({
data: {
message: 'Failed to load recommendations',
stack: 'Error: Network timeout\n at loadRecs (snap.js:120)',
details: {
tag: 'homepage-recs',
timeout: 5000
}
}
});Beacon automatically manages local storage and cookies to maintain user state across sessions. This includes:
- 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
Access and manipulate the stored cart through the storage.cart API:
// Get current cart
const cartItems = beacon.storage.cart.get();
// Set cart to specific items
beacon.storage.cart.set([
{ uid: 'p1', sku: 'SKU-1', qty: 2, price: 29.99 }
]);
// Add items to cart
beacon.storage.cart.add([
{ uid: 'p2', sku: 'SKU-2', qty: 1, price: 19.99 }
]);
// Remove items from cart
beacon.storage.cart.remove([
{ uid: 'p1', sku: 'SKU-1', qty: 1 }
]);
// Clear cart
beacon.storage.cart.clear();Access and manipulate the viewed products history:
// Get viewed products
const viewedItems = beacon.storage.viewed.get();
// Set viewed products
beacon.storage.viewed.set([
{ uid: 'p1', sku: 'SKU-1' }
]);
// Add to viewed products
beacon.storage.viewed.add([
{ uid: 'p2', sku: 'SKU-2' }
]);Set or change the currency for tracking transactions.
const beacon = new Beacon({ siteId: 'abc123' });
// Set currency if not provided in globals
beacon.setCurrency({ code: 'EUR' });| Parameter | Type | Description |
|---|---|---|
currency.code |
string |
ISO 4217 currency code |
Get the current tracking context including user, session, and page information.
const context = beacon.getContext();
// Returns: {
// userId: 'uuid-...',
// sessionId: 'uuid-...',
// pageLoadId: 'uuid-...',
// pageUrl: 'https://...',
// userAgent: '...',
// timestamp: '2024-01-01T...',
// ...
// }Update specific context properties.
beacon.updateContext('userId', 'custom-user-id');
beacon.updateContext('dev', 'development');
beacon.updateContext('pageUrl', 'https://example.com/new-page');Get or generate the current user ID.
const userId = beacon.getUserId();Get or generate the current session ID (expires after 30 minutes of inactivity).
const sessionId = beacon.getSessionId();Get the current shopper ID if set.
const shopperId = beacon.getShopperId();Set the shopper ID and triggers both a login event to the beacon and preflight request for personalization.
const result = beacon.setShopperId('shopper-12345');Get the current page load ID. Generate a new one with pageLoad().
const pageLoadId = beacon.getPageLoadId();Generate a new page load ID. Call this method when tracking page transitions or navigation within a single-page application.
const newPageLoadId = beacon.pageLoad();Get the current timestamp in ISO 8601 format.
const timestamp = beacon.getTimestamp();Send preflight data to the personalization API. This is automatically called when cart or shopper state changes, but can be manually triggered if needed.
beacon.sendPreflight();
// With overrides
beacon.sendPreflight({
userId: 'custom-user-id',
siteId: 'custom-site-id',
shopper: 'shopper-123',
cart: [/* products */],
lastViewed: [/* products */]
});Generate and returns a new UUID.
const id = beacon.generateId();For environments where the standard fetch API is unavailable or needs to be customized (e.g., adding authentication, request interception), provide a custom fetch implementation:
// Custom fetch that adds authentication
const customFetch = async (url, options) => {
const response = await fetch(url, {
...options,
headers: {
...options.headers,
'Authorization': `Bearer ${token}`
}
});
return response;
};
const beacon = new Beacon(
{ siteId: 'abc123' },
{
apis: {
fetch: customFetch
}
}
);Override default API endpoints for internal proxying or custom infrastructure:
const beacon = new Beacon(
{ siteId: 'abc123' },
{
requesters: {
beacon: {
origin: 'https://internal-api.example.com/beacon/v2',
headers: { 'X-Internal-Key': 'secret' }
},
personalization: {
origin: 'https://internal-api.example.com/personalization',
headers: { 'X-Internal-Key': 'secret' }
}
}
}
);For single-page applications, generate a new page load ID when the page/view changes:
// On navigation
const newPageLoadId = beacon.pageLoad();
console.log('New page load:', newPageLoadId);
// Track that we're now viewing a new product
window.athos.tracker.events.product.pageView({
data: {
result: { uid: 'new-product', sku: 'SKU-123' }
}
});Update tracking context dynamically as user behavior or application state changes:
// Update page URL for client-side routing
beacon.updateContext('pageUrl', window.location.href);Attribution is automatically captured from url parameters (ie. https://example.com/products?athos_attribution=email:campaign-123) and will be placed on the beacon context.
Enabling development mode will prevent beacon events from appearing in reports in the Athos console.
const beacon = new Beacon(
{ siteId: 'abc123' },
{ mode: 'development' }
);MIT - See LICENSE file for details