Search and discovery

Search and discovery analytics tell Luigi’s Box what users asked for and what they actually saw. This is what powers metrics like click-through rate, zero-result rate, position-based performance, and recommendation attribution.

Search

Search is reported as a list event with the exact list name Search Results.

What to send

• The exact query string
• All active filters and sorting values
• The final visible results with their absolute positions
• _Guid when you have the Search API response guid
• _Variant when the list is part of an A/B test

{
  "type": "event",
  "id": "ff0d53c8-f791-4518-9335-13a72f3a3f09",
  "tracker_id": "YOUR_TRACKER_ID",
  "client_id": "web-user-1",
  "lists": {
    "Search Results": {
      "query": {
        "string": "running shoes",
        "filters": {
          "brand": "Nike",
          "sort by": "price_amount:asc",
          "_Guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        }
      },
      "items": [
        {
          "title": "Runner One",
          "type": "item",
          "url": "shoe_1",
          "position": 1,
          "price": 99
        }
      ]
    }
  }
}

Position rules

Positions must be absolute across pagination:

• Page 1 starts at 1
• Page 2 starts at the first item after the previous page
• Infinite scroll should report only the newly appended items, not the whole list again

Autocomplete

Autocomplete is also a list event, but the list name must be exactly Autocomplete.

{
  "type": "event",
  "id": "5c7870e5-b8d0-495b-93a3-dbfec1e63244",
  "tracker_id": "YOUR_TRACKER_ID",
  "client_id": "web-user-1",
  "lists": {
    "Autocomplete": {
      "query": {
        "string": "run"
      },
      "items": [
        {
          "title": "Running shoes",
          "type": "query",
          "url": "running shoes",
          "position": 1
        },
        {
          "title": "Runner One",
          "type": "item",
          "url": "shoe_1",
          "position": 2,
          "price": 99
        }
      ]
    }
  }
}

Important autocomplete rules

• Debounce tracking so you report the settled suggestion list, not every keystroke
• If the user clicks a suggestion of type query, send the query text as resource_identifier in the click event
• If autocomplete shows top items on focus, track that block as a recommendation, not as autocomplete

Product listing

Category pages, brand pages, campaign pages, and other browse-first surfaces use the list name Product Listing.

Required scopes

For categories:

• _category_label
• _category_identity

For brands:

• _brand_label
• _brand_identity

{
  "type": "event",
  "id": "20ce9f0e-e83b-4f83-93ca-12780fd8c0c3",
  "tracker_id": "YOUR_TRACKER_ID",
  "client_id": "web-user-1",
  "lists": {
    "Product Listing": {
      "query": {
        "filters": {
          "sort by": "price_amount:asc",
          "_Guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        },
        "scopes": {
          "_category_label": "Shoes||Running",
          "_category_identity": "cat_running_shoes"
        }
      },
      "items": [
        {
          "title": "Runner One",
          "type": "item",
          "url": "shoe_1",
          "position": 1,
          "price": 99
        }
      ]
    }
  }
}

Recommendations

Recommendation widgets use the list name Recommendation.

The critical metadata lives inside query.filters:

• RecommenderClientId
• RecommendationId
• optional ItemIds
• optional Recommender
• optional Type
• optional _Variant

{
  "type": "event",
  "id": "ff61de98-1afe-45a1-b1a7-1a319bf6639a",
  "tracker_id": "YOUR_TRACKER_ID",
  "client_id": "web-user-1",
  "lists": {
    "Recommendation": {
      "query": {
        "filters": {
          "RecommenderClientId": "item_detail_alternatives",
          "RecommendationId": "rec_1abc2de3-f456-7890",
          "ItemIds": ["shoe_1"]
        }
      },
      "items": [
        {
          "title": "Runner Two",
          "type": "item",
          "url": "shoe_2",
          "position": 1,
          "price": 109
        }
      ]
    }
  }
}

Treat RecommendationId as required for all new integrations. It is the key that allows Luigi’s Box to attribute downstream clicks and purchases to the exact recommendation set.

Click attribution

Whenever a user clicks a result from any discovery surface, send a click event:

{
  "type": "click",
  "id": "3a851362-9320-4762-a3d1-4770f1798f1d",
  "tracker_id": "YOUR_TRACKER_ID",
  "client_id": "web-user-1",
  "action": {
    "type": "click",
    "resource_identifier": "shoe_1"
  }
}

Luigi’s Box uses the earlier event stream to attribute that click to the correct search, autocomplete, listing, or recommendation impression.

Conversion attribution

Use the same pattern for add-to-cart or wishlist actions, but change action.type.

{
  "type": "click",
  "id": "b37f526c-d417-49f0-925e-06f74778aa75",
  "tracker_id": "YOUR_TRACKER_ID",
  "client_id": "web-user-1",
  "action": {
    "type": "add-to-cart",
    "resource_identifier": "shoe_1"
  }
}

This lets Luigi’s Box connect the conversion back to the discovery surface that led to it.

Recommended implementation order

1. Track Search Results and Autocomplete
2. Add click tracking for every result click
3. Track Product Listing and Recommendation surfaces
4. Add conversions and transactions so attribution reaches business outcomes

Next steps

• Review the Event API reference
• Add ecommerce events
• Verify the payloads in Debugging