Klevu GTM dataLayer events (for custom implementations)

Introduction

By utilizing GTM, it is possible to monitor shopper activities on your website and transfer this activity data to GA4. GA4 performs the role of event tracking and summarising this data.

This document highlights the steps you need to take to track all Klevu-led activities (events) using GTM and GA4.

This guide is aimed at implementations that have integrated via Klevu's SDK, Klevu's API, and the "Preserved Theme Layout" option available in certain versions of Klevu modules.

If you are using the latest JS Library (aka JSv2), please rather refer to this guide where a template GTM container is provided.

Klevu Component Events

Event: klevu_search

The klevu_search event tracks when search results are displayed to the user. This event provides critical data about user behavior during search interactions, including search terms, results shown, and engagement metrics.

Trigger: The event should be triggered when the search results page loads or when a new set of results is fetched (e.g., pagination, infinite scroll).

Screenshot:

Parameters:

Notes: 

• Dynamic data population: Ensure that the index field reflects the product’s position in the entire result set, not just within the current chunk.
• Zero results: If no products are returned, dispatch the event with klevu_search_results_num set to 0.
• Nice to do: To improve reporting accuracy, split events into manageable chunks. This approach increases the chance that displayed products are captured in analytics. For an example, divide the list of products into sets of 16/12/etc items. This allows better granularity in tracking and ensures visibility metrics for individual products are more reliable. Dispatch the next event when a new set of products comes into the viewport (e.g., during scrolling, pagination).

klevu_search event template/example:

[Check parameters for details]

dataLayer.push({
event: "klevu_search",

klevu_store_id: "{{KLEVU_STORE_ID}}",
klevu_component: "smart_search",
klevu_page_type: "search",
klevu_search_type: "{{KLEVU_SEARCH_TYPE}}",
klevu_search_term: "{{KLEVU_SEARCH_TERM}}",  // search query
klevu_filter_used: "{{KLEVU_FILTER_USED}}",
klevu_page_num: "{{KLEVU_PAGE_NUM}}",
klevu_search_results_num: 27,  // number of search results, fire if 0 too!

ecommerce: {
item_list_id: {{klevu_component}},
item_list_name: {{klevu_search_term}},
       currency: '{{CURRENCY}}',
      items: [
       {
item_id: {{GROUP_ITEM_ID|ITEM_ID|SKU}},
item_name: {{PRODUCT_NAME}},
price: {{PRICE}},
item_brand: {{BRAND},
item_category: {{CATEGORY L1}},
item_category2: {{CATEGORY L2}},
item_category3: {{CATEGORY L3}},
item_category4: {{CATEGORY L4}},
item_variant: {{VARIANT}},
index: 1,
item_klevu_component: "{{klevu_component}}",
item_klevu_category: "{{klevu_search_term}}"  
       }
//subsequent products here 

    ] //close of items array
  }
})

Event: klevu_quick_search

The klevu_quick_search event tracks when the quick search results pane is displayed. This event provides insights into user interactions with the quick search feature and allows tracking of search terms, results shown, and engagement metrics.

Trigger: The event should be triggered when the quick search pane is opened or when search results are displayed within the pane, with a 500ms delay (to prevent event flooding).

Screenshot:

Parameters:

Notes:

• Zero results: If no products are returned, dispatch the event with klevu_search_results_num set to 0.
• Delay mechanism: To prevent event flooding, add a small delay (e.g., 500ms) before dispatching the event to ensure the pane is fully loaded.

klevu_quick_search event template/example:

[see Klevu common parameters and Ecommerce parameters reference for parameter details]

dataLayer.push({
event: "klevu_quick_search",

klevu_store_id: "{{KLEVU_STORE_ID}}",
klevu_component: "smart_quick_search",
klevu_component_method: {{KLEVU_PERSONALIZATION}},
klevu_search_type: "{{KLEVU_SEARCH_TYPE}}",
klevu_search_term: "{{KLEVU_SEARCH_TERM}}",  // search query
klevu_filter_used: "{{KLEVU_FILTER_USED}}",
klevu_search_results_num: 12,  // number of search results, fire if 0 too!

ecommerce: {
item_list_id: {{klevu_component}},
item_list_name: {{klevu_search_term}},
       currency: '{{CURRENCY}}',

    items: [
     {
item_id: {{SKU}},
item_name: {{PRODUCT_NAME}},
price: {{PRICE}},
item_brand: {{BRAND},
item_category: {{CATEGORY L1}},
item_category2: {{CATEGORY L2}},
item_category3: {{CATEGORY L3}},
item_category4: {{CATEGORY L4}},
item_variant: {{VARIANT}},
index: {{POSITION_IN_LIST}}",
item_klevu_component: "{{klevu_component}}",
item_klevu_category: '{{klevu_search_term}}'

     }
//subsequent products here 

    ] //close of items array
  }
})

Event: klevu_category

The klevu_category event tracks when a category page is opened or when additional products are loaded within the category listing.

Trigger: The event should be triggered when the category page is loaded or when new products are fetched within the category (e.g., scrolling, pagination)

Screenshot:

Parameters:

Notes:

• Zero results: If no products are found in the category, dispatch the event with klevu_search_results_num set to 0.
• Dynamic pagination: Trigger the event for each new set of products loaded via scrolling or pagination.

klevu_category event template/example:

[see Klevu common parameters and Ecommerce parameters reference for parameter details]

dataLayer.push({
event: "klevu_category",

klevu_store_id: "{{KLEVU_STORE_ID}}",
klevu_component: "smart_category",
klevu_component_method: "{{KLEVU_COMPONENT_METHOD}}",
klevu_page_type: "category",
klevu_category_name: '{{CATEGORY_NAME}}'
klevu_page_num: "{{KLEVU_PAGE_NUM}}",
klevu_search_results_num: 27,  // number of products in the category listing, dispatch if no products in category listing - "0" too!

ecommerce: {
item_list_id: {{ITEM_LIST_ID}},
item_list_name: {{ITEM_LIST_NAME}},
       currency: '{{CURRENCY}}',

    items: [
     {
item_id: {{SKU}},
item_name: {{PRODUCT_NAME}},
price: {{PRICE}},
item_brand: {{BRAND},
item_category: {{CATEGORY L1}},
item_category2: {{CATEGORY L2}},
item_category3: {{CATEGORY L3}},
item_category4: {{CATEGORY L4}},
item_variant: {{VARIANT}},
index: {{POSITION_IN_LIST}}",
item_klevu_component: "{{KLEVU_COMPONENT}}",
item_klevu_category: '{{CATEGORY_NAME}}'
     }
//subsequent products here 

    ] //close of items array
  }
})

Event: klevu_recommendations

The klevu_recommendations event tracks when a recommendation widget is displayed to the user. This event captures engagement with personalized recommendations provided by Klevu.

Trigger: The event should be triggered when a recommendation widget is displayed or refreshed.

Screenshot:

Parameters:

Notes:

• Dynamic widgets: Ensure the klevu_recommendation_name dynamically reflects the name of the widget displayed.
• Event frequency: Dispatch the event each time the recommendation widget is refreshed or newly loaded.

klevu_recommendations event template/example:

[see Klevu common parameters and Ecommerce parameters reference for parameter details]

dataLayer.push({
event: "klevu_recommendations",

klevu_store_id: "{{KLEVU_STORE_ID}}",
klevu_component: "smart_recommendations",
klevu_component_method: "{{KLEVU_COMPONENT_METHOD}}",
klevu_page_type: "{{KLEVU_PAGE_TYPE}}",
klevu_category_name: '{{RECOMMENDATION_NAME}}'

ecommerce: {
item_list_id: "klevu_recommendations",
item_list_name: {{RECOMMENDATION_NAME}},
       currency: '{{CURRENCY}}',
items: [
{
item_id: {{SKU}},
item_name: {{PRODUCT_NAME}},
price: {{PRICE}},
item_brand: {{BRAND},
item_category: {{CATEGORY L1}},
item_category2: {{CATEGORY L2}},
item_category3: {{CATEGORY L3}},
item_category4: {{CATEGORY L4}},
item_variant: {{VARIANT}},
index: {{POSITION_IN_LIST}}",
item_klevu_component: "smart_recommendations",
item_klevu_category: '{{RECOMMENDATION_NAME}}'
       }
//subsequent products here 

    ] //close of items array
  }
})

Klevu Component Parameters

Klevu Interaction Events

Event: klevu_click

Purpose: Tracks product/category/cms clicks in Klevu components.

Trigger: Push when a product or link is clicked.

Parameters:

• klevu_store_id - Klevu store ID (example value: klevu-170073214294916924)
• klevu_component - Component where click occurred (example value: smart_search)
• klevu_page_num (pagination number where click occurred)
• klevu_category_name (
  {{SEARCH TERM}} for “smart_quick_search” and “smart_search”
  {{CATEGORY_NAME}} for “smart_category”
  {{RECOMMENDATION_NAME}} for “smart_recommendations”
• klevu_filter_used - Whether filters were used (example value: yes|no)
• Ecommerce object:
  item_list_id (klevu_quick_search, klevu_search, klevu_category, klevu_recommendations)
  item_list_name (same as klevu_category_name)
• Ecommerce items array:
  item_klevu_component (same as klevu_component)
  item_klevu_category (same as klevu_category_name)

For Klevu search, add parameters:

klevu_search_type (is it clicked on products, category or cms - “KLEVU_PRODUCT”|”KLEVU_CMS”|”KLEVU_CATEGORY”)

klevu_search_term - {{SEARCH TERM}}

klevu_click event template/example for quick search product click:

[see Klevu common parameters and Ecommerce parameters reference for parameter details]

dataLayer.push({
event: "klevu_click",

klevu_store_id: "{{KLEVU_STORE_ID}}",
klevu_component: "smart_quick_search",
klevu_component_method: {{KLEVU_PERSONALIZATION}},
klevu_search_type="{{KLEVU_SEARCH_TYPE}}",
klevu_search_term: "{{SEARCH QUERY}}",
klevu_page_num: "{{KLEVU_PAGE_NUM}}", // pagination number where click occurred
klevu_category_name: '',
klevu_recommendation_name: '',
klevu_filter_used: "{{KLEVU_FILTER_USED}}",

ecommerce: {
item_list_id: {{KLEVU_COMPONENT}},
item_list_name: '{{SEARCH QUERY}},
       currency: '{{CURRENCY}}',
    items: [
     {
item_id: {{GROUP_ID}},
item_name: {{PRODUCT_NAME}},
item_type: {{PRODUCT_TYPE}},
price: {{PRICE}},
item_brand: {{BRAND},
item_category: {{CATEGORY L1}},
item_category2: {{CATEGORY L2}},
item_category3: {{CATEGORY L3}},
item_category4: {{CATEGORY L4}},
item_variant: {{VARIANT}},
index: {{POSITION_IN_LIST}}",
item_klevu_component: "{{KLEVU_COMPONENT}}",
item_klevu_category: {{SEARCH QUERY}}'

     }
    ] //close of items array
  }
})

klevu_click event template/example for quick search category/cms click:

[see Klevu common parameters and Ecommerce parameters reference for parameter details]

dataLayer.push({
event: "klevu_click",

klevu_component: "{{KLEVU_COMPONENT}}",
klevu_search_type="{{KLEVU_SEARCH_TYPE}}",
klevu_search_term: "{{KLEVU_SEARCH_TERM}}"

klevu_category_name: '{{CATEGORY_NAME}}|{{CMS_NAME}}'

// klevu_quick_search do not contain ecommerce/item array

})

Event: klevu_filter

Tracks filter usage when a user selects a klevu filter on a page or modal window.

klevu_filter event template/example for search:

[see Klevu common parameters and Ecommerce parameters reference for parameter details]

dataLayer.push({
event: "klevu_filter",

klevu_store_id: "{{KLEVU_STORE_ID}}",
klevu_component: "smart_search",
klevu_component_method: {{KLEVU_PERSONALIZATION}},
klevu_filter_attribute: "brand", 
klevu_filter_option: "nike",
klevu_search_term: "{{KLEVU_SEARCH_TERM}}",
klevu_category_name: '',
klevu_recommendation_name: '',
})

klevu_filter event template/example for category filter:

[see Klevu common parameters and Ecommerce parameters reference for parameter details]

dataLayer.push({
event: "klevu_filter",

klevu_store_id: "{{KLEVU_STORE_ID}}",

klevu_component: "smart_category",
klevu_filter_attribute: "color", 
klevu_filter_option: "red",

klevu_search_term: '',
klevu_category_name: '{{KLEVU_CATEGORY_NAME}}',
klevu_recommnendation_name: ''
})

Klevu parameters:

• klevu_store_id
• klevu_component
• klevu_category_name
• klevu_filter_attribute - The name of the attribute being filtered, e.g., "Category", "Color".
• klevu_filter_option - The selected filter option label, e.g., "Performance Fabrics", "red".
• klevu_filter_type - The klevu_component where the filter was applied.

for Klevu Search filters, add parameters:

• klevu_search_type
• klevu_search_term

Event: klevu_add_to_cart

For tracking product adds to cart

• dispatch klevu_add_to_cart when a product is added to cart from a Klevu component's "Add to cart" button
• parameters:
  item_list_id
  item_list_name
      item_list_id and item_list_name should have the same value as originating [list] event 
• for Smart Search, add parameters:
  klevu_search_type
  klevu_search_term
  klevu_component
  klevu_category_name
      [product click]: set to product category name  [breadcrumb type]
• for Smart Category, add parameters
  klevu_category_name

klevu_add_to_cart event template/example for quick search:

[see Klevu common parameters and Ecommerce parameters reference for parameter details]

dataLayer.push({
event: "klevu_add_to_cart",

klevu_store_id: "{{KLEVU_STORE_ID}}",
klevu_component: "{{KLEVU_COMPONENT}}",
klevu_search_type="{{KLEVU_SEARCH_TYPE}}",
klevu_search_term: "{{KLEVU_SEARCH_TERM}}"

klevu_page_num: "{{KLEVU_PAGE_NUM}}", // pagination number where add_to_cart occurred - for klevu_search and klevu_category

klevu_category_name: '{{CATEGORY_NAME}}||{{RECOMMENDATION_NAME}}',

ecommerce: {
item_list_id: {{ITEM_LIST_ID}},
item_list_name: {{ITEM_LIST_NAME}},
       currency: '{{CURRENCY}}',
  value: "{{VALUE}}",
    items: [
     {
item_id: {{SKU}},
item_name: {{PRODUCT_NAME}},
item_type: {{PRODUCT_TYPE}},
price: {{PRICE}},
quantity: 1,
item_brand: {{BRAND},
item_category: {{CATEGORY L1}},
item_category2: {{CATEGORY L2}},
item_category3: {{CATEGORY L3}},
item_category4: {{CATEGORY L4}},
item_variant: {{VARIANT}},
index: {{POSITION_IN_LIST}}",
item_klevu_component: "{{KLEVU_COMPONENT}}",
item_klevu_category: '{{CATEGORY_NAME}}||{{RECOMMENDATION_NAME}}'

     }
    ] //close of items array
  }
})

Events & parameters Reference

Klevu common parameters:
common Klevu parameters - used in events where available
in all Klevu-related events

Ecommerce parameters reference: