Event reporting

Event reporting is used to track user interactions in the search results page that cannot be automatically registered by LupaSearch server, but are useful for search result relevance and can be used in Statistical Boosting, Personalization and is displayed in Analytics to better understand your users behavior.

User interactions include three action types:

Item click - user clicks on a product in search results and is redirected to the page for that product;
Add to cart click - user clicks on add to cart button in search result page;
Suggestion click - user clicks on autocomplete suggestion string.
Converted items - combination of items that were the part of the conversion event, i.e. cart or order items

Event reporting is completely optional. However, without reported events, some of the LupaSearch features, like Personalization and Statistical Boosting will not be available.

Events API

API Reference: Events API

Item / Add to cart click

All event types have the same request body:

{
  "queryKey": "ax2q422v8f7z",
  "name": "itemClick",
  "searchQuery": "television",
  "itemId": "66419592",
  "sessionId": "x-session-id-1",
  "userId": "x-user-id-1"
}

queryKey - query key that was used to generate search results that the user is interacting with;
name - name of the event. One of the following: itemClick, suggestionClick, addToCart, recommendedItemClick, recommendedAddToCart;
searchQuery - original search query that yielded these search results, i.e. what user has typed in the search box input;
itemId - id of an item that the user is interacting with (id field value that is configured as id in your Search Index Mapping);
sessionId - anonymous search session id. Can be any string, and should correspond to a unique search session in your e-shop. For example, can be generated when a new session is started and saved into browser's session storage.
userId - anonymous user id. Can be any string that should correspond to a unique user in your e-shop. LupaSearch only saves hashed values for this property.

Suggestion click

Suggestion click event body slightly differs in a way that instead of product id for itemId field, you need to pass the string value of a clicked suggestion:

{
  "queryKey": "ax2q422v8f7z",
  "name": "suggestionClick",
  "searchQuery": "tel",
  "itemId": "television",
  "sessionId": "x-session-id-1",
  "userId": "x-user-id-1"
}

Converted items

A converted items event is used to log the moment when a user adds multiple items to their cart, places an order or engages with specific products in a significant way.

These types of conversion events, such as combinations of cart items or order items, provide valuable insights into user behavior patterns and preferences. This information can be utilized to personalize the shopping experience and provide additional insights i.e. bought together items recommendations.

The structure of a converted items event is as follows:

{
  "name": "convertedItems",
  "indexId": "054ed287-f8d2-463b-b185-799f29a819ba",
  "itemIds": ["12345", "67890"],
  "timestamp": 1617765206000,
  "sessionId": "x-session-id-1",
  "userId": "x-user-id-1"
}

name - The name of the event. In this case, it is a predefined string convertedItems.
indexId - The index identifier that the converted items belong to.
itemIds - An array of identifiers of the items that were part of the conversion event (such as items added to a cart or included in an order). These identifiers can either be strings or numbers.
timestamp (optional) - The timestamp of the conversion event. If not provided, the current time will be used.
sessionId (optional) - The unique identifier of the session during which the conversion event happened. This string can be any value that corresponds to a unique session on your site.
userId (optional) - The unique identifier of the user who triggered the conversion event. This string should correspond to a unique user on your site.

Recommendation events

If you are not using LupaSearch client plugin for recommendations, you can still report user interactions with recommended items by sending recommendedItemClick and recommendedAddToCart events.

With these events, it is recommended to additionally attach sourceItemId field, which should indicate the item that the recommendations came from. Additionally, queryKey should be recommendations query key.

For example, if you are showing recommendations on the product page, for item that has id 1234 and user clicked on recommendation with id 56, you should send the following event:

{
  "queryKey": "r-ax2q422v8f7z",
  "name": "recommendedItemClick",
  "searchQuery": "",
  "itemId": "56",
  "sourceItemId": "1234",
  "sessionId": "x-session-id-1",
  "userId": "x-user-id-1"
}

If recommendations came from multiple sources (e.g. user's cart), you can send sourceItemId as an array of item ids:

{
  "queryKey": "r-ax2q422v8f7z",
  "name": "recommendedItemClick",
  "searchQuery": "",
  "itemId": "56",
  "sourceItemId": ["1234", "5678"],
  "sessionId": "x-session-id-1",
  "userId": "x-user-id-1"
}

If you used a wildcard _all in the itemId field when originally requesting recommendations, you should also pass it as a source item id:

{
  "queryKey": "r-ax2q422v8f7z",
  "name": "recommendedItemClick",
  "searchQuery": "",
  "itemId": "57",
  "sourceItemId": "_all",
  "sessionId": "x-session-id-1",
  "userId": "x-user-id-1"
}

User and session reporting for Public Query

LupaSearch automatically tracks generic search events - requests to the public query endpoints.

To enable more detailed tracking (which is required for Personalization), public query request can also include sessionId and userId:

{
  "searchText": "tv",
  "sessionId": "x-session-id-1",
  "userId": "x-user-id-1"
}

If for any reason you need to exclude search text from tracked most frequent search terms, pass trackTerm: false flag with public search query request:

{
  "searchText": "tv",
  "trackTerm": false
}

Note that the query will still be counted in total search query count, but given search text term will be excluded from top search phrases statistics.