Quickstart: 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: 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.
For a successful parse you will see a blue Luigi's Box logo.
If something goes wrong you will see a red logo with a list of errors.
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 emptyitems
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 haveindex: 11
, notindex: 1
.
Next Steps
Now that you have foundational search tracking in place, you can enhance your analytics by tracking key conversions: