beacon.js

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.

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

CDN

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.

NPM

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/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'
    }
  }
});

Initialization

Beacon Globals

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 | ✔️ |

Beacon Config

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 |

Common properties

responseId

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,
  }
});

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' }
    ]
  }
});

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.

Shopper Events

Login

Track when a user logs into their shopper account.

window.athos.tracker.events.shopper.login({ 
  data: { id: 'shopper-12345' }
});

Autocomplete Events

Autocomplete events track user interactions within the autocomplete/search suggestions interface.

Render

Track when autocomplete suggestions are rendered to the user.

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

Impression

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' }
    ]
  }
});

Add to Cart

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.

Click Through

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'
      }
    ]
  }
});

Redirect

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

Search events track user interactions within search results pages.

Render

window.athos.tracker.events.search.render({ 
  data: {
    responseId: '607bafd1-f624-4e58-afa5-b8b8e90929f5'
  }
});

Impression

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' }]
  }
});

Add to Cart

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 
      }
    ]
  }
});

Click Through

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'
      }
    ]
  }
});

Redirect

window.athos.tracker.events.search.redirect({ 
  data: {
    redirect: 'https://example.com/promo',
    responseId: '607bafd1-f624-4e58-afa5-b8b8e90929f5'
  }
});

Category Events

Category events track user interactions on category/listing pages.

Render

window.athos.tracker.events.category.render({ 
  data: {
    responseId: '50c7aaf3-1909-43cd-8fff-a8e5c4452ddb'
  }
});

Impression

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: []
  }
});

Add to Cart

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
      }
    ]
  }
});

Click Through

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

Recommendations events track interactions with personalized product recommendations.

Render

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'
  }
});

Impression

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: []
  }
});

Add to Cart

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
      }
    ]
  }
});

Click Through

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'
      }
    ]
  }
});

Product Events

Page View

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'
    }
  }
});

Cart Events

Add

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.

Remove

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 
      }
    ]
  }
});

Order Events

Transaction

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.

Error Tracking Events

Shopify Pixel Errors

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'
    }
  }
});

SNAP Errors

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
    }
  }
});

Storage Management

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

Cart Storage API

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();

Viewed Products Storage API

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' }
]);

Public API Methods

setCurrency(currency: Currency)

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 |

getContext(): Context

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...',
//   ...
// }

updateContext(key: keyof Context, value: any)

Update specific context properties.

beacon.updateContext('userId', 'custom-user-id');
beacon.updateContext('dev', 'development');
beacon.updateContext('pageUrl', 'https://example.com/new-page');

User ID Management

getUserId(): string

Get or generate the current user ID.

const userId = beacon.getUserId();

getSessionId(): string

Get or generate the current session ID (expires after 30 minutes of inactivity).

const sessionId = beacon.getSessionId();

getShopperId(): string

Get the current shopper ID if set.

const shopperId = beacon.getShopperId();

setShopperId(shopperId: string): string | void

Set the shopper ID and triggers both a login event to the beacon and preflight request for personalization.

const result = beacon.setShopperId('shopper-12345');

getPageLoadId(): string

Get the current page load ID. Generate a new one with pageLoad().

const pageLoadId = beacon.getPageLoadId();

pageLoad(): string

Generate a new page load ID. Call this method when tracking page transitions or navigation within a single-page application.

const newPageLoadId = beacon.pageLoad();

getTimestamp(): string

Get the current timestamp in ISO 8601 format.

const timestamp = beacon.getTimestamp();

sendPreflight(overrides?: PreflightRequestModel): void

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 */]
});

generateId(): string

Generate and returns a new UUID.

const id = beacon.generateId();

Advanced Usage

Custom Fetch Implementation

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
    }
  }
);

Custom API Endpoints

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' }
      }
    }
  }
);

Single Page Application (SPA) Support

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' }
  }
});

Context Updates

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 Tracking

Attribution is automatically captured from url parameters (ie. https://example.com/products?ss_attribution=email:campaign-123) and will be placed on the beacon context.

Error Handling

Development Mode

Enabling development mode will prevent beacon events from appearing in reports in the Athos console.

const beacon = new Beacon(
  { siteId: 'abc123' },
  { mode: 'development' }
);

License

MIT - See LICENSE file for details