Signals Beacon

The signals beacon is an embeddable tracker that captures signals corresponding to user actions, like searches and purchases. Add the beacon script to your site’s <head> once. After that, you can manage what it captures entirely from Lucidworks Platform. No further code changes or deployments to your site are required. At a high level, the tracking flow begins when a user visits the site and performs one or more searches. These searches generate query identifiers that associate user actions with specific queries. As the user interacts with search results and shows interest in a product, additional signals such as clicks and cart events are captured. If the user completes a purchase, the flow concludes with a purchase signal. Each purchased product is linked to the query that led to its cart-add. This process enables end-to-end tracking of user behavior from search to purchase. In this scenario, the signals beacon uses several primary tracking mechanisms:

Visitor ID: A randomly generated identifier stored in local browser storage. It is unique to both the visitor and the device. It persists across sessions.
Session ID: A randomly generated identifier that the beacon uses to track and assign signals to sessions. It is stored in local browser storage under the lwBeaconSessionId key. It expires after 30 minutes of inactivity. This duration is configurable using sessionTimeoutThreshold. Each signal resets the inactivity timer, and the session ID persists across tabs and page reloads. When the user returns after the session expires, a new session ID is generated, but the visitor ID remains the same.
Query ID: A randomly generated identifier created when a search query is submitted. It is stored in session storage and is included with signal events related to that query, such as clicks and cart-adds.
Cart ID: A unique identifier created when a product is added to the cart. It’s shared by every cart-add signal and the purchase signal for that cart. Together with product IDs, it links each purchased product to the query that led to its cart-add. After a purchase, a new cart ID is generated to track subsequent transactions independently.

The signal event flow below outlines a simplified sequence of common events. Additional signal types and behaviors are not included in this summary:

When a user visits the site, a visitor ID and session ID are generated.
When a query is submitted, a query ID is generated and a query signal is sent. This signal includes the visitor ID and session ID.
For each new query, a new query ID is generated and another query signal is sent.
When the user clicks on a product, a click signal is sent. This signal includes the associated query ID.
When the user adds a product to their cart, a cart-add signal is sent with the current query ID and cart ID. If there’s no cart ID yet, one is generated.
When the user completes a purchase and lands on the order confirmation page, a purchase signal is sent. This signal includes the order ID and the current cart ID. The purchase signal doesn’t include a query ID. Each purchased product is traced to its query through the cart ID and product ID. After the signal is sent, the cart ID is replaced with a new one to track future transactions independently.

See the following image for a visual representation of this flow:

How it works

The beacon sends signals to the:

Signals store for storage and aggregation
Analytics Studio service, which provides insights about actions taken by users on your site

The following signals are collected:

Query signals. When a user performs a search, a signal is recorded.
Click signals. When a user clicks on a product, a signal is recorded. One example of a click signal is when a user clicks a search result, which is a strong indicator the result is relevant.
Cart-add signals. When a user clicks to add an item to the cart, a signal is recorded.
Purchase complete signals. When a user completes a purchase and is taken to the order confirmation page, a signal is recorded.
Facet usage. When a user applies a facet, a new query signal is recorded that includes the selected facets.

For information about how the signals beacon is related to other signals and analytics functions, see the Overview of signals process.

Prerequisites

You must be a workspace owner to configure the signals beacon. Before you begin, complete the following tasks:

Analyze your site to confirm compatibility with the signals beacon. The signals beacon is compatible with most websites, but you may need to adjust the configuration to ensure it works as needed.
- Your site should use URL query parameters (?q=foo), not other methods of sending the query parameters. If it is not an option to use query parameters on your site, you can use the Signals API to send signals.
- These fields should be surfaced in the page source, either as attributes or text nodes:
  - Product ID
  - Product title
  - Product image URL
  - Product price
  - Product URL
Identify any other fields that you want the signals beacon to capture. You’ll need their CSS paths to configure the beacon. Again, these can be either attributes or text nodes, as in these examples:
<div class="product" data-product-id="12345"></div> <div class="product">12345</div>
A field’s path might be different on different pages of your site.
The signals beacon supports multiple paths per field to accommodate this.
Create the Signals Store where the signals will be stored.

Enable the beacon

To install the beacon, navigate to the megamenu and click Signals.

Click the Signals Store where you want to configure the signals beacon and then click Integrations.
If the beacon has never been configured for this app, you’ll see “No embed token found” on the Signals Using Beacon screen. In that case, click the Generate button. It can take a few moments to generate the token.
In the Allowed Origins field, enter the domains where you want to use the signals beacon. The format is <scheme>://<hostname>[:<port>]. For example, https://domain.YOUR_COMPANY_NAME.com.
Set the Signals Beacon toggle to On.
Click Copy to copy the script and insert that script into the <head> tag of your website’s HTML file.
This also enables the window.logBeaconInfo() function which you can use with your browser’s developer tools to inspect the fields captured by the beacon so that you can validate and refine your configuration.
See Development and troubleshooting below.
Edit the JSON configuration to process the signals you need for analytics. For more details, see:
- Example JSON configuration
- Example signals script
- Field path configuration
- Beacon Configuration Interface for detailed configuration property information
Click Apply. The configuration is applied to your website and it begins to send signals instantly based on that configuration.
You can edit the configuration at any time. When you edit the JSON configuration and click Apply, the changes are applied in real time and signals are sent and processed using that configuration until it is modified.

After the script is implemented and the signals are sent, you can access consolidated metrics. The Analytics Studio metrics provide valuable customer behavior insights, which can be used to improve your business.

Example JSON configuration

Use the following structure as an example to configure the beacon.

JSON configuration

{
    "attributes": {
      "productPath": ".lw-product-item",
      "sessionTimeoutThreshold": 600000,
      "cartId": "lwRetailCartId",
      "idQueryParam": "pid",
      "numberTypeFields": ["price", "quantity", "revenue"]
    },
    "fields": {
      "productId": ":scope @id",
      "imageuri": ":scope img @src",
      "price": ":scope .search-entity-price span @text",
      "title": ":scope .search-entity-title @text, :scope .search-generic-title @text",
      "uri": ".config-url @href"
    },

    "query": {
      "queryParam": "q",
      "delayForTrackQueryUpdate": 1000
    },
    "click": {},
    "cartAdd": {
      "trigger": ".lw-cart-add-trigger"
    },

    "purchase": {
      "enabled": false
    },
    "purchase_complete": {
      "urlPattern": "/order-confirmation",
      "orderIdUrlParam": "orderId",
      "productPath": ".lw-order-item"
    }
}

Line 13. You can use multiple comma-separated paths in cases where a field has different paths on different pages of your site. See the Field path configuration section for details and examples.
Line 16. Everything below this line is your signal configuration, where you list the signals you want to track and the fields you want to extract from them.
Line 21. By default, these attributes inherit from the top-level attributes [productPath|fields].
Line 27. Turns off the purchase signal, which is sent when the user clicks a checkout element. Because an order can fail after that click, use purchase_complete instead.
Lines 30–31. Sends a purchase signal when the user lands on a page whose URL contains /order-confirmation. The order ID is read from the orderId URL query parameter.
Revenue. This example doesn’t set revenue, so the beacon calculates it from each product’s price and quantity. If you set purchase_complete.revenue, use the item subtotal, not the order total. Revenue shouldn’t include tax, shipping, or other fees.

For information about:

Attributes and fields used to extract product details from page elements, see the Field path configuration section.
The BeaconConfig interface, which includes detailed information about configuration properties, types, and default values, see Beacon configuration interface.

Example signals script

The following example contains possible fields and default values.

Signals script

 {
   "attributes": {
     "productPath": ".lw-product-item",
     "cartId": "lwRetailCartId",
     "numberTypeFields": ["price", "quantity", "revenue"]
   },
   "fields": {
     "productId": ":scope @id",
     "title": ".title @text",
     "imageuri": ".config-image @src",
     "uri": ".url-wrapper a @href"
   },
   "query": {
     "queryParam": "query",
     "delayForTrackQueryUpdate": 1000,
     "productPath": ".lw-product-item",
     "fields": {
       "productId": ":scope @id",
       "title": ".title @text",
       "imageuri": ".config-image @src",
       "uri": ".url-wrapper a @href"
     }
   },
   "click": {
     "productPath": ".lw-product-item",
     "fields": {
       "productId": ":scope @id",
       "title": ".title @text",
       "imageuri": ".config-image @src",
       "uri": ".url-wrapper a @href"
     }
   },
   "cartAdd": {
     "trigger": ".lw-cart-add-trigger",
     "productPath": ".lw-product-item",
     "fields": {
       "productId": ":scope @id",
       "title": ".title @text",
       "imageuri": ".config-image @src",
       "uri": ".url-wrapper a @href"
     }
   },
   "purchase": {
     "enabled": false
   },
   "purchase_complete": {
     "urlPattern": "/order-confirmation",
     "orderIdUrlParam": "orderId",
     "delayForPurchaseRedirect": 1000,
     "productPath": ".lw-order-item",
     "fields": {
       "productId": ":scope @data-item-id",
       "title": ".title @text",
       "price": ".price @text",
       "quantity": ".quantity @text"
     }
   }
 }

Line 2. Global attributes inherited by each signal section.
Line 3. The CSS selector to target product elements. This is the global path inherited by each signal section if no custom path is provided at [query/click/cartAdd/purchase/purchase_complete].productPath. The default is .lw-product-item.
Line 4. The local storage key for the consumer page storing the cart UUID. The cartId value defaults to lwRetailCartId. The beacon obtains the value from localStorage.lwRetailCartId when attaching cart info to /retail/signals/cartadd and /retail/signals/purchase.
Line 5. This list specifies the fields treated as number type fields. The default is ["price", "quantity", "revenue"].
Line 7. This is the main section to extract product field value from your site. For more information, see the Field path configuration section in this topic, which provides detailed configuration about extracting product information to ensure accurate and consistent data collection.
Line 8. The productId field with a value of :scope @id is the only required field to use the Lucidworks Retail Beacon API.
Line 14. Specifies the URL parameter the beacon uses to monitor query updates. For example, with the default param query, if the current product page is filtered with the keyword hat, the URL parameter is http://example.com?query=hat. The default value is query.
Line 15. Specifies the delay, in milliseconds, for tracking element updates in the query. The default value is 1000.
Line 17. Custom overwrite of the fields configuration at the root level.
Line 34. The CSS selector that targets page elements for triggering add-to-cart actions. This has full CSS support for targeting multiple elements with comma-separated selectors. For example, button.add-to-bag, #AddToBagWithPrice.
Line 44. Turns off the purchase signal, which is sent when the user clicks a checkout element. Because an order can fail after that click, use purchase_complete to track completed purchases.
Line 47. The beacon sends a purchase signal when the current URL contains this substring. Use a stable part of your order confirmation page URL.
Line 48. The URL query parameter that contains the order ID. Alternatively, use orderIdSelector to read the order ID from a page element.
Line 49. The delay, in milliseconds, before the beacon reads the confirmation page. Increase this value if your site adds order details to the page after it loads. The default value is 1000.
Line 50. The CSS selector for the purchased items on the confirmation page. If your confirmation page doesn’t display purchased items, use a signal handler to add them.

Field path configuration

The signals beacon extracts product details from page elements using CSS selectors and attributes. You can capture any field that’s surfaced in the page’s DOM by adding it to your JSON configuration, under "fields". This section shows you how to configure your field paths, with examples. The format is: [Element CSS Selector] @[Value Attribute], as in the example below:

"url": ".details .url @href"

  <div class="details">
    ...
    <a class="url" href="http://example.com/prd-123" />
  </div>

http://example.com/prd-123

Special selectors

These special selectors and attributes are available:

The @text pseudo-attribute captures the inner text node, as in these examples:

"title": ".title @text"

<h2 class="title">Fancy Hat</h2>

Fancy Hat

"price": ".details .price @text"

  <div class="details">
    <div class="price" value="100" />
    ...
  </div>

The :scope CSS class targets product details defined on the root productPath element, as in this example:

{
  "attributes": {
    "productPath": ".main-page-product",
  },

  "fields": {
    "productId": ":scope @sku",
    ...
  }
}

<div class="main-page-product" sku="prd-123">

prd-123

The textContent selector targets elements by their text, as follows:
- Exact match: [textContent='Add to cart!']
- Contains: [textContent*='cart']
- Starts with: [textContent^='add']
- Ends with: [textContent$='cart!']
For example:
"trigger": "button[textContent='Add to Cart'], .add-to-cart-container button"
You can also use data attributes as selectors, as in this example where data-testid is a data attribute:
"trigger": ".headerSearchBox, #hdrSrch, input[data-testid=global-search]"

Page type configuration

The pageTypes configuration enables you to classify queries by page type based on URL patterns. Configuration:

"pageTypes": {
  "search": ["*/search*"],
  "category": ["*/category/*"],
  "product": ["*/product/*"]
}

Type: { [pageType: string]: string[] } A mapping of page types to their corresponding URL patterns. The pageTypes configuration enables annotation of query signals via an optional pageType property. By default, when no pageType is specified, query signals are treated as originating from the search page. When a pageType is provided, its value is used for page-type matching. If a query does not match any configured patterns, its pageType is set to “OTHER”. Queries with a pageType other than null or “SEARCH” are excluded from the null query report. This is particularly useful for scenarios where queries originate from or redirect to non-search pages (e.g., category pages).

Explicitly configuring the “search” page type is recommended. Doing so ensures that any query signals from URLs that don’t match a configured pattern are classified as “OTHER” and excluded from the null query report.

Configure the beacon with Agent Studio or UI Studio

To use the signals beacon on the same page as Agent Studio or UI Studio, configure the beacon script with additional attributes. Agent Studio and UI Studio both use the <lw-template> web component, which requires specific beacon configuration to work correctly. Add the following attributes to the beacon script that you downloaded at Analytics Studio > Integrations:

signal-store-api-url: API URL for your signals store.
signal-store-embed-token: Embed token for the signals store.
beacon="{}": Initializes the beacon configuration.
initiator="AS": Identifies the script as being used with Agent Studio or UI Studio.

The following example shows the beacon script configured with those additional attributes:

<head>
  <script 
    type="module" 
    id="lw-ui-lib" 
    src="https://storage.googleapis.com/sb-ui/springboard.esm.js"
    app-studio-api-url="YOUR_APP_STUDIO_API_URL"
    app-studio-embed-token="YOUR_APP_STUDIO_TOKEN"
    signal-store-api-url="YOUR_SIGNAL_STORE_API_URL"
    signal-store-embed-token="YOUR_SIGNAL_STORE_TOKEN"
    beacon="{}"
    initiator="AS">
  </script>
</head>

<body>
  <lw-template template-id="12345" product-id="1234">
  </lw-template>
</body>

Without these attributes, the beacon and lw-template components may conflict and fail to initialize.

Configure the beacon for multiple pages of search results

You can configure the signals beacon if your site separates query results by tabs. For example, one tab for content and another tab for product information. In the following example, each tab’s content path is separated by a comma under "productPath" with the "fields" property defining what is tracked for each tab using :scope.

Configuration

{
  "attributes": {
    "numberTypeFields": [
      "price",
      "quantity",
      "revenue"
    ],
    "productPath": ".cmp-content-search-result-list-item, .cmp-productlist__item"
  },
  "click": {
    "trigger": "a, a h3, .button"
  },
  "fields": {
    "imageuri": ":scope .cmp-content-search-result-list-item__img @src, :scope img @src",
    "productId": ":scope .cmp-content-search-result-list-item_link @href, :scope .cmp-text .anchor @text",
    "title": ":scope .cmp-content-search-result-list-item__details-name @text, :scope .cmp-text p @text",
    "uri": ":scope .cmp-content-search-result-list-item_link @href"
  },
  "query": {
    "queryParam": "search_query"
  }
}

Programmatic hooks

Signal handlers modify, enhance, or suppress signals before the beacon sends them. Use a handler when the data you need isn’t in the page’s Document Object Model (DOM) but is available elsewhere, such as facets stored outside the URL or order details stored in your site’s data layer. You can define a handler for each signal type: query, click, cartAdd, purchase, and purchase_complete. There are two ways to register a handler:

In the beacon configuration. Add a handler property to the signal section. The value is a function written as a string. The function receives an object with window and payload properties.
In your site’s code. Call window.addBeaconListener after the beacon loads. The callback receives the signal payload. You can register one handler for each signal type, and you only need to register it once.

If a signal type has a handler in both places, the handler in the beacon configuration is used.

Signal handler behavior

The signal handler can be used for the following:

Modify signals: return the modified payload object to send an enhanced signal.
Suppress signals: return false to prevent the signal from being sent.
Error handling: if a runtime error occurs in the callback function, the original unmodified signal will be sent.

If the signal handler returns undefined or null, the unmodified signal will be sent.

Signal handlers run synchronously and must return their result immediately. Don’t use async functions or return a Promise, because the beacon doesn’t wait for it to resolve.

The arguments to the window.addBeaconListener function should include these:

The signal type.
Callback function with one argument (signal payload).

Examples of signal payload enhancement

Enhancing a click payload:

window.addBeaconListener('click', (payload) => {
  // Modify the payload as needed
  payload.productDetails[0].product.productId = '123';

  // Return the modified payload to send the signal
  return payload;
});

Example of a query payload:

window.addBeaconListener('query', (payload) => {
  // Modify the payload as needed
  payload.selected_facets = [
    {
      name: 'color',
      values: ['blue', 'white'],
    },
  ];

  // Return the modified payload to send the signal
  return payload;
});

Example of conditional signal suppression

window.addBeaconListener('query', (payload) => {
  // Do not send query signals that contain a blocked search term
  if (payload.searchTerms === 'blocked query') {
    return false;
  }
});

Example of a purchase complete signal from a data layer

Order confirmation pages often don’t display product details in a way the beacon can extract. If your site stores order details in a JavaScript data layer, use a purchase_complete handler to build the signal from that data. This example assumes your site pushes an event like the following to window.dataLayer when the confirmation page loads. Adjust the property names in the handler to match your site’s data layer.

Data layer event

window.dataLayer.push({
  event: 'purchase',
  ecommerce: {
    transaction_id: 'ORD-12345',
    currency: 'USD',
    items: [
      { item_id: 'SKU-1001', item_name: 'Fancy Hat', price: 49.99, quantity: 2 },
      { item_id: 'SKU-2002', item_name: 'Wool Scarf', price: 29.99, quantity: 1 }
    ]
  }
});

Add the handler to the purchase_complete section of your beacon configuration, or register it in your site’s code:

"purchase": {
  "enabled": false
},
"purchase_complete": {
  "urlPattern": "/order-confirmation",
  "delayForPurchaseRedirect": 2000,
  "handler": "function({ window, payload }) { const event = (window.dataLayer || []).find(e => e.event === 'purchase' && e.ecommerce); if (!event) return false; const order = event.ecommerce; const productDetails = (order.items || []).map(item => ({ product: { productId: String(item.item_id), title: item.item_name, price: Number(item.price) }, quantity: Number(item.quantity) || 1 })); const revenue = productDetails.reduce((sum, p) => sum + p.product.price * p.quantity, 0); return { ...payload, orderId: String(order.transaction_id), productDetails, revenue }; }"
}

window.addBeaconListener('purchase_complete', (payload) => {
  const event = (window.dataLayer || []).find((e) => e.event === 'purchase' && e.ecommerce);

  // Suppress the signal if the order details aren't available
  if (!event) return false;

  const order = event.ecommerce;
  const productDetails = (order.items || []).map((item) => ({
    product: {
      productId: String(item.item_id),
      title: item.item_name,
      price: Number(item.price),
    },
    quantity: Number(item.quantity) || 1,
  }));

  // Calculate revenue from line items so it excludes tax, shipping, and fees
  const revenue = productDetails.reduce((sum, p) => sum + p.product.price * p.quantity, 0);

  return {
    ...payload,
    orderId: String(order.transaction_id),
    productDetails,
    revenue,
  };
});

When you build a purchase signal with a handler, keep the following in mind:

The signal must include products. The beacon doesn’t send a purchase signal with an empty productDetails list.
Product IDs must match your other signals. Use the same product ID format as your click and cart-add signals, including prefixes and leading zeros. If the formats differ, Analytics Studio can’t connect purchases to earlier signals, and conversion metrics are inaccurate. Normalize the IDs in the handler if needed.
Use the item subtotal for revenue. Order-level metrics, such as average order value and revenue per visit, use the revenue value. Exclude tax, shipping, and other fees so these metrics reflect the value of the purchased items. Product-level reports use each product’s price and quantity instead.
Allow time for the data layer. The beacon waits for delayForPurchaseRedirect milliseconds before it runs the handler. If your site adds order details to the data layer after the page loads, increase this value. A longer delay increases the chance that the user leaves the page before the signal is sent.

Content Security Policy (CSP) requirements

If your site uses a Content Security Policy (CSP), you must add the following directives to allow the signals beacon to load and send data:

script-src: Add https://storage.googleapis.com because the beacon script is served from Google Cloud Storage.
connect-src: Add the Signal Store API host and, if using Agent Studio, the App Studio API host.

The following example shows the minimum required CSP directives:

Content-Security-Policy:
  script-src 'self' https://storage.googleapis.com;
  connect-src 'self' YOUR_SIGNAL_STORE_API_URL YOUR_APP_STUDIO_API_URL;

Replace YOUR_SIGNAL_STORE_API_URL with the value in the signal-store-api-url attribute of your beacon script, and YOUR_APP_STUDIO_API_URL with the value in the app-studio-api-url attribute when using Agent Studio.

Development and troubleshooting

The signals beacon includes the built-in window.logBeaconInfo() debugging utility that logs verbose information if the debug flag is enabled. To enable the debug flag in your local storage, set localStorage.enableBeaconDev = true.

Get Started

Lucidworks Platform

Lucidworks AI

Core Settings

UI Studio

Agent Studio

Commerce Studio

Analytics Studio

How it works

Prerequisites

Enable the beacon

Example JSON configuration

Example signals script

Field path configuration

Special selectors

Page type configuration

Configure the beacon with Agent Studio or UI Studio

Configure the beacon for multiple pages of search results

Programmatic hooks

Signal handler behavior

Examples of signal payload enhancement

Example of conditional signal suppression

Example of a purchase complete signal from a data layer

Content Security Policy (CSP) requirements

Development and troubleshooting

​How it works

​Prerequisites

​Enable the beacon

​Example JSON configuration

​Example signals script

​Field path configuration

​Special selectors

​Page type configuration

​Configure the beacon with Agent Studio or UI Studio

​Configure the beacon for multiple pages of search results

​Programmatic hooks

​Signal handler behavior

​Examples of signal payload enhancement

​Example of conditional signal suppression

​Example of a purchase complete signal from a data layer

​Content Security Policy (CSP) requirements

​Development and troubleshooting

How it works

Prerequisites

Enable the beacon

Example JSON configuration

Example signals script

Field path configuration

Special selectors

Page type configuration

Configure the beacon with Agent Studio or UI Studio

Configure the beacon for multiple pages of search results

Programmatic hooks

Signal handler behavior

Examples of signal payload enhancement

Example of conditional signal suppression

Example of a purchase complete signal from a data layer

Content Security Policy (CSP) requirements

Development and troubleshooting