Platform Signals API

The Platform Signals API and the embed token feature can be used instead of the signals beacon to collect query, click, cart-add, and purchase complete signals. When the signals are collected, you can use the insights and analytics in Analytics Studio to help refine your site and improve customer interactions. Visit signals are not currently used and are scheduled to be deprecated. While the Javascript signals beacon functionality is versatile and configurable, your organization may need to use the Platform Signals API and embed features instead. For example, your organization may use a mobile app that cannot accept Javascript, have security configuration differences, or already use another framework for sending signals. To use the Platform Signals API and embeds to collect signals, your engineering team must add the appropriate information to the backend codebase on your site. Examples of the fields that need to be added include anonymous visitor ID and session ID values for each customer interaction. The Platform Signals API specification details each signal request.

For detailed API specifications in Swagger/OpenAPI format, see Platform APIs.

UI components required to implement the Platform Signals API

Two values you need to use the Platform Signals API are the Signals Store ID and embed token. This section provides the steps in the necessary order to create and obtain those values from the UI.

1. Create a Signals Store

Navigate to the megamenu and click Signals.
Click Create New.
In the Name field, enter a unique user-defined for the Signals Store.
In the Region field, select the geographical area for the Signals Store.
This selection cannot be changed. If you need a Signals Store in a different region, you need to create another Signals Store with the other region specified.
Click Create.

2. Generate and copy the embed token to your codebase

To generate the embed token, navigate to the megamenu and click Signals.

Click the Signals Store where you want to configure the signals beacon and then click Integrations > Signals Using Embed Token.
If you haven’t configured embeds for this Signals Store, the “No embed token found” message displays.
Click Generate. It may take a few moments to generate the token.
The generated embed token for the Signals Store is permanent and cannot be changed.
In the Embed Token section, click Copy and then paste the token into your codebase. To view the token, click Show or click Hide to prevent it from displaying.
The embed token also displays in asterisks in the Authorization header line of all of the cURL examples. When you copy and then paste the cURL example, the value of the embed token displays instead of the asterisks. For example:
--header 'Authorization: Embed EMBED_TOKEN'

3. Obtain the Signals Store ID

To obtain the Signals Store ID, navigate to the megamenu and click Signals.

Click the Signals Store where you want to configure the signals beacon and then click Integrations > Signals Using Embed Token.
The Signals Store ID displays in first line of all of the cURL examples. Copy that ID to paste into your codebase. For example:
curl 'https://SIGNAL_STORE_ID.applications.lucidworks.com/retail/signals/query'

4. Copy or create code to collect signals

Lucidworks provides cURL command examples for the query, click, cart-add, and purchase complete signals that you can copy into your backend codebase and modify based on the language you use, such as Java, C#, Python, or Nodejs.

For detailed API specifications in Swagger/OpenAPI format, see Platform APIs.

To copy cURL command examples you can paste into your site codebase, navigate to the megamenu and click Signals.

Click the Signals Store where you want to configure the signals beacon and then click Integrations > Signals Using Embed Token.
Click Copy to copy the cURL command example for the signal you want to add to your codebase.
Paste the command in your codebase and modify based on your organizational needs. If you choose not to use the examples Lucidworks provides, enter code into your codebase manually.

Example user flow and signal events

This section provides a typical user interaction flow for browsing and purchasing a product by describing the required API signals and UUID generation necessary for event tracking. You can program your site to generate UUIDs using any standards-compliant method. Each signal depends on proper UUID generation and tracking. Consistent IDs are necessary for signal integrity and accurate metrics for analytics. To successfully create signals and ensure complete signal tracking, your site must generate and persist the following UUIDs:

sessionId is required in every signal (query, click, cartadd, and purchase complete) to identify the session.
visitorId identifies the user. It’s required in the purchase complete signal and optional in the other signals, but send it in every signal so Lucidworks can track each visitor’s activity.
queryId is required in the query, click, and cartadd signals to identify the query. Each facet refinement is a new query and requires a new queryId. queryId is optional in the purchase complete signal.
searchTerms is required in the query signal to return results.
cartId is required in the cartadd and purchase complete signals. Use the same cartId for every cartadd signal in a cart and for the purchase complete signal, then replace it with a new UUID after the purchase.
orderId is optional, and is used on the purchase_complete signal and identifies an actual purchase as opposed to an attempted purchase.

As part of the code you add to your site, you need to implement UUID generation and determine how to store these values and all other parameters. For example, visitorId is typically stored in localStorage to persist across sessions, and sessionId is usually stored in sessionStorage to reset between sessions. Other parameters are detailed in the Platform Signals API specification.

Sample user interaction flow

The following example provides typical interactions when a customer searches for and purchases a refrigerator.

1. Site entry and ID generation

When a user visits your site, the site must generate the visitorId and sessionId universal unique identifiers (UUIDs).

2. Search query and initial query signal

When the user searches for “silver french door bottom freezer refrigerator,” your site must generate a new queryId UUID and send a query signal.

Generate queryID

curl --request POST \
  --url https://SIGNAL_STORE_ID.applications.lucidworks.com/retail/signals/query \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "timestamp": 1744305461169,
    "visitorId": "abcc8e25-d30f-2212-9f60-9b45a71453cf",
    "sessionId": "41a50e2-8e32-4674-5429-e1450dfdbb14",
    "queryId": "2a97fc33-3335-3369-c2dc-456b775eb90f",
    "ipAddress": "111.222.333",
    "searchTerms": "silver french door bottom freezer refrigerator",
    "productDetails": [
      {
        "product": {
          "productId": "1234567",
          "currencyCode": "USD",
          "price": 2592,
          "title": "Silver french door bottom freezer 27.4 cu ft refrigerator",
          "imageuri": "https://example.com/images/refrigerators/silver/bottomfreezer/1234567.jpg"
        },
        "quantity": 1
      }
    ],
    "sourceId": "string",
    "uri": "https://example.com/search?q=silver+french+door+bottom+freezer+refrigerator"
  }
]'

3. Product click and click signal

When the user clicks a product, your site must generate a click signal that uses the same queryId generated in the query request that returned the results on which the user clicks.

Click signal

curl --request POST \
  --url https://SIGNAL_STORE_ID.applications.lucidworks.com/retail/signals/click \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "timestamp": 1744305461169,
    "visitorId": "abcc8e25-d30f-2212-9f60-9b45a71453cf",
    "sessionId": "41a50e2-8e32-4674-5429-e1450dfdbb14",
    "queryId": "2a97fc33-3335-3369-c2dc-456b775eb90f",
    "ipAddress": "111.222.333",
    "productDetails": [
      {
        "product": {
          "productId": "1234567",
          "currencyCode": "USD",
          "price": 2592,
          "title": "Silver french door bottom freezer 27.4 cu ft refrigerator",
          "imageuri": "https://example.com/images/refrigerators/silver/bottomfreezer/1234567.jpg"
        },
        "quantity": 1
      }
    ],
    "sourceId": "string",
    "uri": "https://example.com/refrigerators/silver/bottomfreezer",
    "selectedPosition": 1
  }
]'

The selectedPosition field is critical for calculating Average Click Position analytics. Use one-based indexing where the first item in the search results is 1, the second is 2, and so on. Do not use zero-based indexing.

4. Cart addition and cart-add signal

When the user adds a product to their cart, your site must send a cart-add signal that includes the queryId of the search that led to the product and a cartId. If the user doesn’t have a cart ID yet, generate one. Reuse it for every product added to that cart.

Cart add signal

curl --request POST \
  --url https://SIGNAL_STORE_ID.applications.lucidworks.com/retail/signals/cartadd \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "timestamp": 1744305461169,
    "visitorId": "abcc8e25-d30f-2212-9f60-9b45a71453cf",
    "sessionId": "41a50e2-8e32-4674-5429-e1450dfdbb14",
    "queryId": "2a97fc33-3335-3369-c2dc-456b775eb90f",
    "ipAddress": "111.222.333",
    "productDetails": [
      {
        "product": {
          "productId": "1234567",
          "currencyCode": "USD",
          "price": 2592,
          "title": "Silver french door bottom freezer 27.4 cu ft refrigerator",
          "imageuri": "https://example.com/images/refrigerators/silver/bottomfreezer/1234567.jpg"
        },
        "quantity": 1
      }
    ],
    "sourceId": "string",
    "uri": "https://example.com/refrigerators/silver/bottomfreezer",
    "cartId": "7f626d8c-4176-4f55-b17d-e89531e92ef7"
  }
]'

5. Purchase complete and purchase signal

When the user completes the purchase, your site sends a purchase complete signal with the same cartId used in the cart-add signals and an optional orderId. After the purchase, replace that cartId with a new UUID for the next cart. Purchases are attributed to queries by cartId and the productId of each item in productDetails, not by queryId. Each item is credited to the query in the cart-add signal that added it to the cart. If the cart was built from several searches, the purchase is split across those queries by product. If the same product is added to the cart more than once, the most recent cart-add’s query gets the credit. Each productId in productDetails must match the productId sent in its cart-add signal. queryId is optional in the purchase complete signal and isn’t used to attribute purchases to queries. You can omit it. Lucidworks uses orderId to drop duplicate purchase signals.

Send the purchase complete signal as soon as the purchase completes. Lucidworks keeps the query for each cart item for a limited time after that item’s last cart-add signal. After that time, the item can’t be attributed to a query. Session and product metrics are still recorded.

Set revenue to the total price of the purchased products only. Don’t include tax, shipping, or other fees.

Purchase complete signal

curl --request POST \
  --url https://SIGNAL_STORE_ID.applications.lucidworks.com/retail/signals/purchase \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "timestamp": 1744305461169,
    "visitorId": "abcc8e25-d30f-2212-9f60-9b45a71453cf",
    "sessionId": "41a50e2-8e32-4674-5429-e1450dfdbb14",
    "ipAddress": "111.222.333",
    "productDetails": [
      {
        "product": {
          "productId": "1234567",
          "currencyCode": "USD",
          "price": 2592,
          "title": "Silver french door bottom freezer 27.4 cu ft refrigerator",
          "imageuri": "https://example.com/images/refrigerators/silver/bottomfreezer/1234567.jpg"
        },
        "quantity": 1
      }
    ],
    "sourceId": "string",
    "uri": "https://example.com/order-confirmation",
    "cartId": "7f626d8c-4176-4f55-b17d-e89531e92ef7",
    "orderId": "6a678f11-2265-4d01-a4ed-6e9875bfbda2",
    "revenue": 2592
  }
]'

Additional signal information

A facet refinement is a new query, not a separate signal type. When the user applies a facet, your site must send a new query signal with the following values:

A new queryId UUID.
The same visitorId and sessionId, so the refinement stays attached to the same visitor and session.
A selected_facets array that lists each applied facet by name and its selected values. The Facet Usage metric in Analytics Studio uses this array to count facet selections.
A productDetails array that lists the filtered results returned after the facet is applied.
A uri that is the URL of the refined search results page.

Facet signal

curl --request POST \
  --url https://SIGNAL_STORE_ID.applications.lucidworks.com/retail/signals/query \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "timestamp": 1744305500000,
    "visitorId": "abcc8e25-d30f-2212-9f60-9b45a71453cf",
    "sessionId": "41a50e2-8e32-4674-5429-e1450dfdbb14",
    "queryId": "3be88d22-1c74-44fd-b3a1-6d22078dfed4",
    "ipAddress": "111.222.333",
    "searchTerms": "silver french door bottom freezer refrigerator",
    "selected_facets": [
      {
        "name": "brand",
        "values": ["Example Brand"]
      }
    ],
    "productDetails": [
      {
        "product": {
          "productId": "1234567",
          "currencyCode": "USD",
          "price": 2592,
          "title": "Silver french door bottom freezer 27.4 cu ft refrigerator",
          "imageuri": "https://example.com/images/refrigerators/silver/bottomfreezer/1234567.jpg"
        },
        "quantity": 1
      }
    ],
    "sourceId": "string",
    "uri": "https://example.com/search?q=silver+french+door+bottom+freezer+refrigerator&brand=Example+Brand"
  }
]'

If you use the signals beacon, it captures selected facets from the URL automatically. To configure which URL parameters contain facets, see the facets property in BeaconQueryProps. If facets aren’t in the URL, add selected_facets to the query signal with a signal handler.

Get Started

Lucidworks Platform

Lucidworks AI

Core Settings

UI Studio

Agent Studio

Commerce Studio

Analytics Studio

UI components required to implement the Platform Signals API

1. Create a Signals Store

2. Generate and copy the embed token to your codebase

3. Obtain the Signals Store ID

4. Copy or create code to collect signals

Example user flow and signal events

Sample user interaction flow

1. Site entry and ID generation

2. Search query and initial query signal

3. Product click and click signal

4. Cart addition and cart-add signal

5. Purchase complete and purchase signal

Additional signal information

Facet refinement and query signal generation

​UI components required to implement the Platform Signals API

​1. Create a Signals Store

​2. Generate and copy the embed token to your codebase

​3. Obtain the Signals Store ID

​4. Copy or create code to collect signals

​Example user flow and signal events

​Sample user interaction flow

​1. Site entry and ID generation

​2. Search query and initial query signal

​3. Product click and click signal

​4. Cart addition and cart-add signal

​5. Purchase complete and purchase signal

​Additional signal information

​Facet refinement and query signal generation

UI components required to implement the Platform Signals API

1. Create a Signals Store

2. Generate and copy the embed token to your codebase

3. Obtain the Signals Store ID

4. Copy or create code to collect signals

Example user flow and signal events

Sample user interaction flow

1. Site entry and ID generation

2. Search query and initial query signal

3. Product click and click signal

4. Cart addition and cart-add signal

5. Purchase complete and purchase signal

Additional signal information

Facet refinement and query signal generation