Beacon configuration interface

This topic details the BeaconConfig interface, including related interfaces, types, and default values.

For more information about the script to paste into the <head> tag of your website’s HTML file and the JSON configuration, see Signals Beacon.

BeaconConfig

This object details the primary configuration interface for the signals beacon. The signal sections query, click, cartAdd, purchase, and purchase_complete are top-level keys, at the same level as attributes and fields.

BeaconConfig · object

type · string · default: "RETAIL"

The signal type. Valid values are RETAIL and SITE_SEARCH. SITE_SEARCH is a legacy type that only supports query and click signals.

attributes · BeaconAttributes

The global configuration inherited by each signal section. See BeaconAttributes.

labels · object

Static values attached as-is to every signal. Supported keys are componentId, initialCompositionId, and compositionId. Unlike attributes, these values don’t tell the beacon how to find data on the page.

fields · { [field: string]: BeaconFieldConfig } · default: "{ productId: ':scope @id' }"

The main section for extracting product field values from your site. Each signal section inherits these fields unless it defines its own. Use the field names productId, title, price, uri, and imageuri. The beacon doesn’t rename fields, so other names such as id, image, or url aren’t recognized.

query · BeaconQueryProps

The configuration for query signals. See BeaconQueryProps.

click · BeaconClickProps

The configuration for signals sent when a product is clicked. See BeaconClickProps.

cartAdd · BeaconCartAddProps

The configuration for signals sent when a product is added to the shopping cart or bag. See BeaconCartAddProps.

purchase · BeaconPurchaseProps

The configuration for purchase signals sent when the user clicks a checkout element, such as a Place order button. This represents a purchase attempt, not a completed purchase. See BeaconPurchaseProps.

purchase_complete · BeaconPurchaseCompleteProps

The configuration for purchase signals sent when the user lands on the order confirmation page. This represents a completed purchase and is the recommended way to track purchases. See BeaconPurchaseCompleteProps.

visit · object

The configuration for site visit signals. Visit signals are off unless you set enabled to true.

Show properties

enabled · boolean · required

Set to true to send visit signals.

threshold · number · default: "1800000"

The minimum time, in milliseconds, between visit signals for the same URL.

embeddable_activity · object

The configuration for signals sent by Lucidworks conversational agent components.

Show properties

enabled · boolean

Set to true to send embeddable product and interaction signals.

productPagePattern · string

A substring or /regex/ pattern that identifies product detail pages.

productIdUrlParam · string

The URL query parameter that contains the product ID. If both productIdUrlParam and productIdSelector are set, productIdUrlParam is used.

productIdSelector · string

The CSS selector for the element that contains the product ID.

delayForRedirect · number · default: "2000"

The delay, in milliseconds, after landing on a product page before the signal is sent.

pagination · object

The configuration for calculating a clicked product’s position across paginated results. The position is calculated as (page - pageBase) × rpp + (index on page + 1).

Show properties

rpp · number | { queryParam: string } | { handler: string } · required

The number of results per page. Set a fixed number, the URL query parameter that contains the value, or a function as a string that returns the value.

page · number | { queryParam: string } | { handler: string } · required

The current page number. Set a fixed number, the URL query parameter that contains the value, or a function as a string that returns the value.

pageBase · number · default: "1"

The number of the first page, either 0 or 1.

BeaconFieldConfig

This is a type alias for field configuration. The value can be a string, or a BeaconFieldRichConfig object.

BeaconFieldRichConfig

This object details the interface to fine tune field details.

BeaconFieldRichConfig · object

path · string · required

This is the field value path.

exclude · string

This string is excluded from the raw value. For example, with "exclude": "Sale Price: ", the raw value Sale Price: 100 is extracted as 100. If the value is a /regex/ pattern, the field value is the pattern’s first capture group.

type · string · default: "string"

This property provides additional typing information that allows for proper transformation of the value. Set to number to parse the value as a number, even if the field isn’t listed in numberTypeFields.

queryParamFromUrl · string

Treats the raw value as a URL and extracts the value of this query parameter. For example, with "path": ":scope a.product-link @href" and "queryParamFromUrl": "uid", the link http://example.com?uid=123 is extracted as 123.

jsFunction · string

A function, written as a string, that returns the field value. The function receives an object with origValue, window, field, fieldConfig, beaconConfig, and element. If the function returns nothing, the original value is used.

BeaconAttributes

This object details the interface for the global configuration inherited by each signal section.

BeaconAttributes · object

idQueryParam · string · default: "pid"

The URL query parameter used to get the product ID from the product page.

cartId · string · default: "lwRetailCartId"

The local storage key for the consumer page storing the cart UUID. The beacon replaces the cart ID after a purchase signal is sent.

productPath · string · default: ".lw-product-item"

The CSS selector for targeting product elements. This is the global path inherited by each signal section.

sessionTimeoutThreshold · number · default: "1800000"

Optional inactivity threshold in milliseconds that ends a session and starts a new one. The default is 1800000 ms (30 minutes).

numberTypeFields · string[] · default: "[\"price\", \"quantity\", \"revenue\"]"

This specifies the fields that are treated as number type fields.

bulkSignalsInterval · number · default: "0"

The interval, in milliseconds, for sending signals in batches. When set, signals are queued in local storage and sent on this interval instead of immediately. The default value 0 disables batching.

data · string

The name of an element attribute that contains serialized JSON product details.

This property is not currently functional. Use fields or a signal handler instead.

BeaconSignalProps

This object details the interface that provides common properties for all signal sections. BeaconQueryProps, BeaconClickProps, BeaconCartAddProps, BeaconPurchaseProps, and BeaconPurchaseCompleteProps all include these properties.

BeaconSignalProps · object

productPath · string

The custom selector to target product elements for this signal section. If not set, the value of attributes.productPath is used.

fields · { [field: string]: BeaconFieldConfig }

The fields to extract for this signal section. Fields defined here override the matching top-level fields. Fields not defined here fall back to the top-level fields.

handler · string

A function, written as a string, that modifies or suppresses the signal before it is sent. The function receives an object with window and payload. Return the modified payload to send it, or return false to suppress the signal. If the function returns undefined or null, or throws an error, the original signal is sent. A handler in the configuration takes precedence over a handler registered with window.addBeaconListener. For details and examples, see Programmatic hooks.

BeaconQueryProps

This object details the interface for configuring beacon signals sent during a product search.

BeaconQueryProps · object

queryParam · string | string[] · default: "query"

The URL query parameter the beacon uses to monitor query updates. If you provide a list, the parameters are checked in order and the first one with a value is used.

trigger · string

The CSS selector for targeting multiple page elements related to product query activities. The beacon analyzes the comma-separated elements, monitors when the ‘Enter’ key is pressed on the input element as well as clicks on the remaining elements, then sends query signals accordingly.

In addition, the beacon supports the ability to track the ‘Enter’ key along with clicks on the search button for scenarios where there is no query parameter if the trigger property is used. For example, the main search flow could use the query parameter q while the search within the search uses the beacon properties to record both the input and the search button clicks. An example configuration is:

"query": {
  "queryParam": "q",
  "trigger": ".search-box input, .search-box .btn"
}

delayForTrackQueryUpdate · number · default: "1000"

This specifies the delay, in milliseconds, for tracking element updates in the query.

sendSignalDebounceDelay · number · default: "200"

The delay, in milliseconds, for debouncing query signals.

urlPattern · string

A substring or /regex/ pattern. When set, a query signal is sent on pages whose URL matches this pattern.

allowUrls · string[]

Restricts query tracking to URLs that contain one of these substrings. If empty or not set, query tracking is allowed on all URLs.

categoryPageQueryMap · { [urlMatch: string]: string }

Maps a category page URL pattern to a search term. Use this for category pages that don’t have a query parameter.

pageTypes · { [pageType: string]: string[] }

Maps page types to URL patterns, which can be substrings or /regex/ patterns. See Page type configuration.

facets · object

The configuration for capturing selected facets from the URL.

Show properties

queryParams · string | string[] · required

The URL query parameters that contain facet data.

excludeFacetsThatContain · string[]

Facet keys to skip.

keyValueDelimiter · string

The separator between a facet name and its values.

facetDelimiter · string

The separator between facets.

valuesDelimiter · string

The separator between multiple values for the same facet.

valueExtractorRegex · string

A /regex/ pattern whose first capture group is used as the facet value. For example, with "queryParams": "fq", "keyValueDelimiter": ":", and "valueExtractorRegex": "/\"(.*)\"/", the URL parameter fq=category:["type1,type2"] is captured as the facet category with the values type1 and type2.

BeaconClickProps

This object details the interface for configuring beacon signals when the user clicks a product. It includes the properties in BeaconSignalProps.

BeaconClickProps · object

trigger · string

The CSS selector for targeting page elements that trigger click signals. Separate multiple selectors with commas.

BeaconCartAddProps

This object details the interface for configuring beacon signals sent when a product is added to the shopping cart or bag. It includes the properties in BeaconSignalProps.

BeaconCartAddProps · object

trigger · string

The CSS selector for targeting page elements that trigger add-to-cart signals. Separate multiple selectors with commas.

BeaconPurchaseProps

This object details the interface for configuring purchase signals sent when the user clicks a checkout element, such as a Place order button. It includes the properties in BeaconSignalProps.

Because the order can still fail after the click, this signal represents a purchase attempt. To track completed purchases, configure purchase_complete and set purchase.enabled to false. Both sections send signals to the same purchase endpoint, so enabling both can record the same order twice.

BeaconPurchaseProps · object

trigger · string · default: ".lw-purchase-trigger"

The CSS selector for targeting page elements that trigger purchase signals. Separate multiple selectors with commas.

revenue · string

The path to the element that displays the total amount of the items in the cart. If not set, revenue is calculated from the price and quantity of each product.

enabled · boolean · default: "true"

Set to false to turn off this signal without removing its configuration.

BeaconPurchaseCompleteProps

This object details the interface for configuring purchase signals sent when the user lands on the order confirmation page. It includes the properties in BeaconSignalProps.

This is the recommended way to track purchases. The signal includes an order ID, which identifies a completed purchase.

BeaconPurchaseCompleteProps · object

urlPattern · string · required

A substring of the order confirmation page URL, such as /order-confirmation. When the current URL contains this value, the beacon sends a purchase signal. This value is always matched as a literal substring; /regex/ patterns aren’t supported.

orderIdUrlParam · string

The URL query parameter that contains the order ID. If both orderIdUrlParam and orderIdSelector are set, orderIdUrlParam is used.

orderIdSelector · string

The CSS selector for the element that contains the order ID.

revenue · string

The path to the element that displays the order total. If not set, revenue is calculated from the price and quantity of each product.

delayForPurchaseRedirect · number · default: "1000"

The delay, in milliseconds, after the confirmation page loads before the beacon reads the page and sends the signal. Increase this value if your site adds order data to the page after it loads. If the delay is too short, the data might not be available yet. If the delay is too long, the user might leave the page before the signal is sent.

enabled · boolean · default: "true"

Set to false to turn off this signal without removing its configuration.

The beacon sends a purchase signal only if it includes at least one product. If your confirmation page doesn’t display product details, use a handler to add them to the signal from another source, such as your site’s data layer. For an example, see Example of a purchase complete signal from a data layer.