Tracking user journey

Understanding the user journey is what makes Luigi’s Box analytics useful. The system needs to know who the user is, what they saw, what they clicked, and what they eventually purchased. This guide explains how to model that journey with the supported v1 Events API.

Start with stable user identifiers

Luigi’s Box uses two identifiers to stitch a journey together:

• client_id identifies the current browser, device, or app install
• customer_id identifies the logged-in customer when that information is available

How to use them

1. Always send client_id.
2. When the user signs in, keep the same client_id and add customer_id.
3. When the user signs out, remove customer_id but keep the same client_id.

If you change client_id in the middle of a session, Luigi’s Box interprets that as a new user stream and breaks attribution in that browser or app context.

client_id continuity matters more than whether the user is anonymous or authenticated. Do not rotate it on login or logout.

Choose the right event for each step

The supported v1 event model is intentionally small:

Journey step	Event type	When to use it
User views a generic page or detail page	pv	Homepage, cart, CMS page, product detail, category detail
User sees search, autocomplete, listing, or recommendation results	event	Any list of items rendered to the user
User clicks a result	click with action.type: "click"	Search, autocomplete, recommendation, listing result click
User adds to cart or performs another micro-conversion	click with a custom action type	add-to-cart, add-to-wishlist, buy, and similar
User completes checkout	transaction	Final order confirmation

pv: page views and detail views

Use pv for both generic pages and catalog object detail pages.

• For a generic page, set url to the canonical URL or route
• For a catalog detail page, set url to the indexed object identity

{
  "type": "pv",
  "id": "7ef5e0ec-f9a5-4f2c-b363-a6c86e31f652",
  "tracker_id": "YOUR_TRACKER_ID",
  "client_id": "web-user-1",
  "customer_id": "customer-42",
  "url": "sku-2372711",
  "title": "White sneakers GLX 23"
}

event: lists that shape discovery

Use event whenever the user sees a list of items:

• Search Results
• Autocomplete
• Product Listing
• Recommendation

These events should describe the final list the user actually saw, including positions, filters, and recommendation metadata where relevant.

{
  "type": "event",
  "id": "73cdff18-c6b3-4a3a-8cb4-2f7455a0f7d6",
  "tracker_id": "YOUR_TRACKER_ID",
  "client_id": "web-user-1",
  "lists": {
    "Search Results": {
      "query": {
        "string": "running shoes"
      },
      "items": [
        {
          "title": "Runner One",
          "type": "item",
          "url": "shoe_1",
          "position": 1,
          "price": 99
        }
      ]
    }
  }
}

click: result clicks and micro-conversions

Use the same outer event type for both clicks and non-purchase conversions.

Result click

{
  "type": "click",
  "id": "3d7188fd-5b68-4bb8-898f-f0a4264790ef",
  "tracker_id": "YOUR_TRACKER_ID",
  "client_id": "web-user-1",
  "action": {
    "type": "click",
    "resource_identifier": "shoe_1"
  }
}

Add to cart

{
  "type": "click",
  "id": "9f42bba5-06f0-48c2-8446-f25eabf8f174",
  "tracker_id": "YOUR_TRACKER_ID",
  "client_id": "web-user-1",
  "action": {
    "type": "add-to-cart",
    "resource_identifier": "shoe_1"
  }
}

Anything other than action.type: "click" is treated as a conversion signal.

transaction: the end of the journey

Use transaction only when the order is complete.

{
  "type": "transaction",
  "id": "c2d72b44-9274-4ef6-b35f-db7322d36730",
  "tracker_id": "YOUR_TRACKER_ID",
  "client_id": "web-user-1",
  "items": [
    {
      "url": "shoe_1",
      "count": 1,
      "total_price": 99
    },
    {
      "url": "sock_2",
      "count": 2,
      "total_price": 18
    }
  ]
}

Include the full order, not only the items that came from Luigi’s Box results.

Typical journey mapping

Website flow

User action	Event
Visits homepage	pv
Opens product detail	pv with indexed identity in url
Performs search	event with Search Results
Clicks result	click
Adds product to cart	conversion click
Completes purchase	transaction

Mobile app flow

User action	Event
Opens a screen	pv or event, depending on the screen type
Sees autocomplete suggestions	event with Autocomplete
Sees recommendation widget	event with Recommendation
Taps a result	click
Adds item to favorites or cart	conversion click
Completes checkout	transaction

A/B testing and session context

Use ab_test_variant for session-level A/B reporting. For list-specific experiments, send _Variant inside the list filters.

You can also send context when ranking depends on operational conditions such as warehouse, country, or inventory pool. Make sure those context keys are consistent with your indexed data.

Next steps

• Read the full Event API reference
• Implement search and discovery tracking
• Add ecommerce events once journey attribution is in place