Tracking

To support advanced analytics and user engagement tracking, Koral provides a set of custom events that you can use to monitor how users interact with your visual search features. These events can be used to gather insights into user behavior, improve the search experience, and optimize product discovery.

Custom Events

The list of custom events that Koral supports includes:

Search frame open

This event is triggered when the search frame is opened. It can be used to track how often users initiate a search.

To track this event, you can use the following code snippet:

window.addEventListener('koral_open', (event: CustomEvent) => {
  // Your custom tracking logic here
});

Search frame close

This event is triggered when the search frame is closed. It can be used to track how often users actively closes the search frame.

To track this event, you can use the following code snippet:

window.addEventListener('koral_close', (event: CustomEvent) => {
  // Your custom tracking logic here
});

Click similar search

This event is triggered when a user clicks on the similar search icon. It can be used to track how often users engage with the similar search feature.

To track this event, you can use the following code snippet:

window.addEventListener('koral_similar_search', (event: CustomEvent) => {
  // Your custom tracking logic here
  console.log('koral_similar_search event received:', event.detail);
});

The event details contains the following properties:

• productId: the ID of the product that was clicked
• image: the URL of the image that was clicked
• filters: an array of filters applied to the search, if any

Product click

This event is triggered when a user clicks on a product. It can be used to track how often users engage with products.

To track this event, you can use the following code snippet:

window.addEventListener('koral_product_click', (event: CustomEvent) => {
  // Your custom tracking logic here
  console.log('koral_product_click event received:', event.detail);
});

The event details contains the following properties:

• link: the URL of the product that was clicked
• productId: the ID of the product that was clicked
• variantId: the ID of the product variant that was clicked
• image_url: the URL of the product image
• brand: the brand of the product
• itemGroupId: the ID of the item group
• name: the title of the product
• productType: the type of the product
• productCategory: the category of the product
• searchImageId: the ID of the search image
• price: the price of the product
• discount: the discount applied to the product
• currency: the currency of the product price
• index: the index of the product in the search results
• category: the primary category of the product
• category2: the secondary category of the product
• variant: the color of the product variant
• quantity: the quantity of the product

Example event detail:

{
  "link": "https://yourstore.com/product-page",
  "productId": "1234567",
  "variantId": "7654321",
  "imageUrl": "https://yourstore.com/product-image.jpg",
  "brand": "Your Brand",
  "itemGroupId": "9876543",
  "name": "Product Title",
  "productType": "Product Type",
  "productCategory": "Product Category",
  "searchImageId": "Search Image ID",
  "price": 100.00,
  "discount": 10.00,
  "currency": "USD",
  "index": 0,
  "category": "Category 1",
  "category2": "Category 2",
  "variant": "Color Variant",
  "quantity": 1
}

Impressions

This event is triggered when a product is displayed in the search results. It can be used to track how often users see a particular product.

To track this event, you can use the following code snippet:

window.addEventListener('koral_product_impression', (event: CustomEvent) => {
  // Your custom tracking logic here
  console.log('koral_product_impression event received:', event.detail);
});

The event details contains the following properties:

• productId: the ID of the product that was displayed
• imageId: Internal id of the image
• position: the position of the product in the search results
• brand: the brand of the product from the product feed
• category: the category of the product from the product feed
• type: the type of the product from the product feed
• title: the title of the product from the product feed
• gtin: the GTIN of the product from the product feed

Example event detail:

{
  "productId": "1234567",
  "imageId": "image_001",
  "position": 1,
  "brand": "Your Brand",
  "category": "Category 1",
  "type": "Product Type",
  "title": "Product Title",
  "gtin": "0001234567890"
}

Image upload

This event is triggered when a user uploads an image to initiate a search. It is only sent for users who successfully upload an image.

To track this event, you can use the following code snippet:

window.addEventListener('koral_image_upload', (event: CustomEvent) => {
  // Your custom tracking logic here
  console.log('koral_image_upload event received:', event.detail);
});

The event has no special properties.

Image upload search

This event is triggered when a search using an uploaded image is completed.

To track this event, you can use the following code snippet:

window.addEventListener('koral_image_upload_search', (event: CustomEvent) => {
  // Your custom tracking logic here
  console.log('koral_image_upload_search event received:', event.detail);
});

The event has no special properties.