Quickstart: A Guide to debugging your analytics

Introduction

You've implemented the tracking code, but how do you know it's working correctly? Debugging is a crucial final step to ensure you're sending high-quality data to Luigi's Box. Inaccurate or incomplete data can prevent the AI models from learning effectively. This guide will teach you how to use the two primary tools Luigi's Box provides to verify your work and troubleshoot common problems.

What you'll learn

• How to use the browser-based Linter for real-time validation on your website.
• How to use the Live Session Explorer to inspect raw event data from any integration (web, mobile, or backend).
• How to identify and fix the most common integration mistakes.

Who is this guide for

• Developers who are currently implementing or have finished implementing Luigi's Box Analytics and want to verify their setup.

Prerequisites

• An active Luigi's Box integration (in a development or production environment).
• Access to your website's developer console (for the Web Linter).
• Login access to your Luigi's Box application account (for the Live Session Explorer).

Step by step: Using the debugging tools

Method 1: The web linter (for website integrations)

If you are integrating on a website (e.g., using the DataLayer Collector), the Linter is your best first stop for debugging. It provides instant feedback directly in your browser.

1. Open your website page where the integration is active.
2. Open your browser's Developer Console (usually by pressing the F12 key).

3. In the console tab, type the following command and press Enter:

   • javascript

   Luigis.lint = true
   

4. Reload the page and perform the actions you want to test (e.g., make a search). Do not close the developer console.

Interpreting the Output

• Success: A blue Luigi's Box logo will appear in the console. This confirms that the integration collected data and its structure is valid.
• Errors: A red logo will appear, followed by a list of specific errors and warnings about the data quality. This tells you exactly what needs to be fixed.

Method 2: The live session explorer (for all integrations)

This is the universal tool for seeing the raw event data as it arrives at our servers. It works for all integration types, including mobile apps and backend API calls. Log in to your Luigi's Box application.

1. In the left-hand menu, navigate to General settings and then click on Live session explorer.
2. In your application or website, perform the actions you want to test (e.g., make a search, click a product, complete a purchase).
3. In the Session Explorer, you will see a list of active sessions in real-time. Find your session (you can identify it by the User ID) and click on it. The view will expand to show you the complete, ordered stream of events received for that session, allowing you to inspect the raw JSON data you sent.

Troubleshooting checklist: Common mistakes

If your data isn't appearing correctly, check for these frequent issues:

• Incorrect list name: The item_list_name (in DataLayer) or the list key (in Events API) must be exactly "Search Results" or "Autocomplete". Check for typos and proper capitalization.
• Missing "no results" event: You must send an analytics event even when a search returns zero results. The items array should just be empty ([]).
• Incorrect item positions: For paginated results, the index or position must be absolute. The first item on page 2 (with 20 items per page) should be position 21, not 1. A very common problem is restarting positions from 1 on each page.
• URL-encoded query: The search query string should be sent raw, exactly as the user typed it. Do not URL-encode it (e.g., with percent-encoding). Luigi's Box will handle any necessary encoding.
• Missing conversion tracking: A frequent oversight is to track search results but forget to track conversions (like "add to cart") on both the search results page and the product detail pages.
• Invalid JSON (Events API): If using the Events API, ensure your JSON is perfectly valid. The most common error is a trailing comma at the end of an array or list of object properties.

Next Steps