Track your first search with DataLayer collector

Introduction

This guide provides the foundational steps for integrating Luigi’s Box Analytics on a website that uses a dataLayer. You will learn how to capture the most essential user interactions for the search service: what users search for, what results they see, and which results they click on. Implementing this tracking correctly is the most essential step to power Luigi’s Box AI models and improve your search relevance.

What you’ll learn

How to structure and push a view_item_list event to track which search results a user sees.
How to send a select_item event to report a user’s click on a specific result.
How to use the Luigi’s Box linter tool to verify that your analytics integration is working correctly.

Who is this guide for

Developers working on websites that already have a dataLayer object implemented. This is common for sites using Google Analytics or Google Tag Manager.

Prerequisites

Before you start, please ensure you have the following in place:

The main Luigi’s Box script installed in the <head> of your website pages.
Your website has a working dataLayer object that can receive pushed events.

Step-by-step

Step 1: Track your search results view

The first step is to inform Luigi’s Box about the search results presented to a user. This is done by pushing a view_item_list event to the dataLayer as soon as the search results are loaded on the page.

Example: push a `view_item_list` event when search results load

window.dataLayer.push({
  event: "view_item_list",
  ecommerce: {
    item_list_name: "Search Results"  //this name is critical
    search_term: "phone", // The users actual query
    items : [
      {
        item_id: "SKU_12345",         // Must match your catalog ID
        item_name: "Stan and Friends Tee",
        index: 1,                     // Absolute position on the page
        price: 9.99,
        type: "item"
      },
      {
        item_id: "CAT_12345",
        item_name: "Phones",          // This result is a category
        index: 2,
        type: "category"
      }
      // ... add all other visible results here

    ]
  }
})

Step 2: Track a click on a result

When a user clicks on one of the results, you must report this interaction. this click provides a strong signal to the AI model about the relevance of that item. Use the select_item event for this action.

Example: report user clicks with a `select_item` event

// When a user clicks on the item with ID "SKU_12345"
window.dataLayer.push({
  event: "select_item",
  ecommerce: {
    items: [
      {
        item_id: "SKU_12345" // The ID of the clicked item
      }
    ]
  }
});

Luigi’s Box uses the item_id to attribute this click to the list of items you provided in Step 1.

Step 3: Track no results queries

You must send a view_item_list event even when a search returns zero results. This is critical for Luigi’s Box to identify queries that need improvement. Set items to an empty array.

Example: push a `view_item_list` event for a no-results search

window.dataLayer.push({
  event: "view_item_list",
  ecommerce: {
    item_list_name: "Search Results",
    search_term: "xyznonexistent",  // The user's query that returned no results
    items: []                       // Empty array signals zero results
  }
});

Step 4: Verify your integration

You can easily check your work directly in your browser using the built-in data linter.

Open your website page where the search is implemented.
Open your browser’s Developer Console (usually by pressing the F12 key).
In the console, type the following command and press Enter:

Luigis.lint = true

Reload the page and perform a search. Do not close the developer console.

Best practices

To avoid common issues and ensure high-quality data collection, keep these points in mind:

Use exact list names: The item_list_name attribute must be exactly “Search Results” (or “Autocomplete” for autocomplete results), including capitalization. Any other name will cause the event to be ignored.
Always send an event: Push a view_item_list event even when a search returns zero results. In this case, simply provide an empty items array []. This helps Luigi’s Box track queries that need improvement.
Use stable IDs: The item_id you provide must be a unique and immutable (unchanging) identifier that perfectly matches the ID in your catalog feed. Using product URLs is discouraged as they can change.
Handle pagination correctly: The index for each item must be its absolute position in the full list of results. For example, if you show 10 items per page, the first item on page 2 should have index: 11, not index: 1.

Next steps

Now that you have foundational search tracking in place, you can enhance your analytics by tracking key conversions:

Track add to cart: Use the add_to_cart event to report when a user adds an item to their shopping cart.
Track purchases: Use the purchase event when a user completes a transaction. This provides the strongest positive signal to our AI.

Was this page helpful?

Thanks.