```json Configuration theme={"dark"}
{
"attributes": {
"productPath": ".main-page-product",
},
"fields": {
"productId": ":scope @sku",
...
}
}
```
```html HTML structure theme={"dark"}
```
```bash Data extracted theme={"dark"}
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:
```json theme={"dark"}
"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:
```json theme={"dark"}
"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:**
```json theme={"dark"}
"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 `` 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:
```html {6-9} theme={"dark"}
```
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`.
```json Configuration theme={"dark"}
{
"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
If your facets are stored somewhere that is inaccessible to the beacon, you can hook into beacon events to transform or suppress signals.
The `BeaconSignalHandlers` mechanism provides a way to modify, enhance, or suppress the signals that the beacon originally constructed before they are sent.
A signal handler can be defined for each of the signal types (`query`, `click`, `cartAdd`, and `purchase`).
Handlers should be called in the site’s code after the beacon is loaded. These functions only need to be set once.
The beacon configuration does not need to change if the intent of using this mechanism is to enhance query signals with facet information that is not available through the URL.
### 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.
The arguments to the `window.addBeaconListener` function should include these:
1. The signal type.
2. Callback function with one argument (signal payload).
### Examples of signal payload enhancement
Enhancing a `click` payload:
```js theme={"dark"}
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:
```js theme={"dark"}
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
```js theme={"dark"}
window.addBeaconListener('query', (payload) => {
// Do not send query signals that contain a blocked search term
if (payload.searchTerms === 'blocked query') {
return false;
}
});
```
## 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`.
