DataLayer collector

The DataLayer-based collector is currently in beta. To get started with it, please reach out to Luigi’s Box support at support@luigisbox.com.

Luigi's Box leverages Google Analytics' ecommerce events for efficient data collection. In simple terms, the process involves the collector monitoring the dataLayer object and gathering all pertinent events that are pushed. If you are not currently pushing ecommerce events to the dataLayer, there are two methods to implement this:

Using gtag manager: Utilize the gtag manager to seamlessly push ecommerce events to the dataLayer.
Using native dataLayer.push method: Alternatively, employ the native dataLayer.push method to achieve the same outcome of logging events to the dataLayer.

Both options yield equivalent results, as they effectively record events in the dataLayer, which the collector can subsequently access. It's worth noting that there is a slight disparity in the structure of events within the dataLayer object between the two methods, but the collector is designed to interpret both seamlessly.

Collector initialization

Insert the LBX script to the <head> element of each page.

javascript

<script async src="https://scripts.luigisbox.com/LBX-XXXXXX.js"></script>

Send a collector configuration event to the dataLayer.

javascript

window.dataLayer.push({
  event: 'luigisbox.collector.configure',
  options: {},
});

Initialize the collector by sending a initialization event to the dataLayer.

javascript

window.dataLayer.push({
    event: 'luigisbox.collector.initialize',
});

Collector option parameters breakdown

Parameter	Description
`GetCookieConsent`	A function that returns a boolean value indicating whether the user has granted cookie consent.
`customDataLayerName`	The name of the object where the collector should look for ecommerce events.

Event parameters breakdown

This section outlines event paramteres related to ecommerce events. When reporting events, include the necessary fields based on the specific context.

Parameter	Description
`event`	The name of the event. Supported event names are: `view_item_list` `select_item`, `add_to_cart`, `purchase`.
`item_list_name`	Name of the reported list. Supported list names are: `Autocomplete`, `Search Results`, `Recommendation`.
`items`	An array containing list results.
`item_id`	Identifier of an item within the reported list.
`item_name`	Name of an item within the reported list.
`index`	Position of an item within the reported list.
`price`	Price of an item within the reported list.
`query`	The query that the user entered (required only for search results and autocomplete).
`filters`	Object containing filter name(s) with their respective value(s). When a single filter has multiple values, you can include all values at once in an array.
`transaction_id`	The unique identifier of a transaction.
`value`	The monetary value of the event.
`currency`	Currency of the items associated with the event, in 3-letter ISO 4217 format.

Event examples

The collector is equipped to read and interpret data from the following ecommerce events. Please be aware that the examples use a structure that represents the minimum required parameters. If you choose to include additional parameters for your own needs, it is completely acceptable.

Autocomplete example

Luigis box's collector utilizes view_item_list ecommerce event to gather a list of autocomplete results that a user is presented with.

javascript

window.dataLayer.push({
  event: "view_item_list",
  ecommerce: {
    item_list_name: "Autocomplete",
    search_term: "phone",
    items: [
      {
        item_id: "SKU_12345",
        item_name: "Stan and Friends Tee",
        index: 0,
        price: 9.99,
      },
      {
        item_id: "SKU_12346",
        item_name: "Google Grey Women's Tee",
        index: 1,
        price: 20.99,
      }
    ],
    filters: {
      "Color": ["Black", "Silver"],
      "Operating system": "Android"
    }
  },
});

gtag alternative

javascript

gtag("event", "view_item_list", {
  item_list_id: "autocomplete",
  item_list_name: "Autocomplete",
  search_term: "Phone",
  items: [
    {
      item_id: "SKU_12345",
      item_name: "Stan and Friends Tee",
      index: 0,
      price: 9.99,
    },
    {
      item_id: "SKU_12346",
      item_name: "Google Grey Women's Tee",
      index: 1,
      price: 20.99,
    }
  ],
  filters: {
    "Color": ["Black", "Silver"],
    "Operating system": "Android"
  }
});

Search example

Luigis box's collector utilizes view_item_list ecommerce event to gather a list of search results that a user is presented with.

javascript

window.dataLayer.push({
  event: "view_item_list",
  ecommerce: {
    item_list_name: "Search Results",
    search_term: "Phone",
    items: [
      {
        item_id: "SKU_12345",
        item_name: "Stan and Friends Tee",
        index: 0,
        price: 9.99,
      },
      {
        item_id: "SKU_12346",
        item_name: "Google Grey Women's Tee",
        index: 1,
        price: 20.99,
      }
    ],
    filters: {
      "Color": ["Black", "Silver"],
      "Operating system": "Android"
    }
  }
});

gtag alternative

javascript

gtag("event", "view_item_list", {
  item_list_name: "Search Results",
  search_term: "Phone",
  items: [
    {
      item_id: "SKU_12345",
      item_name: "Stan and Friends Tee",
      index: 0,
      price: 9.99,
    },
    {
      item_id: "SKU_12346",
      item_name: "Google Grey Women's Tee",
      index: 1,
      price: 20.99,
    }
  ],
  filters: {
    "Color": ["Black", "Silver"],
    "Operating system": "Android"
  }
});

Recommender example

Luigis box's collector utilizes view_item_list ecommerce event to gather a list of recommender results that a user is presented with.

javascript

window.dataLayer.push({
  event: "view_item_list",
  ecommerce: {
    item_list_name: "Recommendation",
    items: [
      {
        item_id: "SKU_12345",
        item_name: "Stan and Friends Tee",
        index: 0,
        price: 9.99,
      },
      {
        item_id: "SKU_12346",
        item_name: "Google Grey Women's Tee",
        index: 1,
        price: 20.99,
      }
    ],
    filters: {
      "RecommenderClientId": "Basket",
      "ItemIds": ["/products/123", "/products/129"]
    }
  }
});

gtag alternative

javascript

gtag("event", "view_item_list", {
  item_list_name: "Recommendation",
  items: [
    {
      item_id: "SKU_12345",
      item_name: "Stan and Friends Tee",
      index: 0,
      price: 9.99,
    },
    {
      item_id: "SKU_12346",
      item_name: "Google Grey Women's Tee",
      index: 1,
      price: 20.99,
    }
  ],
  filters: {
    "RecommenderClientId": "Basket",
    "ItemIds": ["/products/123", "/products/129"]
  }
});

For the recommendation, you can use the following filters (and you must always include at least RecommenderClientId):

Filter name	Filter value
`RecommenderClientId`REQUIRED	Unique identifier of the recommender (`recommender_client_identifier` from recommendation result). Its value should define type of recommender user along with its position on the site (e.g., `product_detail_bottom_alternatives`).
`ItemIds`optional	List of input items of a recommendation request (`item_ids` from recommendation request).
`Recommender`optional	Name of the recommender (`recommender` from recommendation result).
`Type`optional	Type of the recommender (`recommendation_type` from recommendation result).
`_Variant`optional	Determines variant in A/B

No results example

When your search returns no results, you need to add push an event to dataLayer anyway. You must add parameters for the query, the used filters and the search name (Search Results/Autocomplete). Since your search returned no results, set items to empty array.

javascript

window.dataLayer.push({
  event: "view_item_list",
  query: "Phone",
  ecommerce: {
    item_list_id: "search_results",
    item_list_name: "Search Results",
    items: [],
    filters: {
      "Color": "Yellow"
    }
  }
});

gtag alternative

javascript

gtag("event", "view_item_list", {
  item_list_id: "search_results",
  item_list_name: "Search Results",
  search_term: "Phone",
  items: [],
  filters: {
    "Color": "Yellow"
  }
});

Click example

Luigis box's collector utilizes select_item ecommerce event to collect a click action that was performed on a result.

javascript

window.dataLayer.push({
  event: "select_item",
  ecommerce: {
    item_list_id: "related_products",
    item_list_name: "Related products",
    items: [
      {
        item_id: "SKU_12345",
        item_name: "Stan and Friends Tee",
      }
    ]
  }
});

gtag alternative

javascript

gtag("event", "select_item", {
  item_list_id: "related_products",
  item_list_name: "Related products",
  items: [
    {
      item_id: "SKU_12345",
      item_name: "Stan and Friends Tee",
    }
  ]
});

Add to cart example

Luigis box's collector utilizes add_to_cart ecommerce event to collect a click action that was performed on a result.

javascript

window.dataLayer.push({
  event: "add_to_cart",
  ecommerce: {
    currency: "EUR",
    value: 7.77,
    items: [
      {
        item_id: "SKU_12345",
        item_name: "Product Name",
      }
    ]
  }
});

gtag alternative

javascript

gtag("event", "add_to_cart", {
  currency: "EUR",
  value: 7.77,
  items: [
    {
      item_id: "SKU_12345",
      item_name: "Product Name"
    }
  ]
});

Transaction example

Luigis box's collector utilizes purchase ecommerce event to collect a click action that was performed on a result.

javascript

window.dataLayer.push({
  event: "purchase",
  ecommerce: {
    transaction_id: "T_12345",
    value: 25.42,
    currency: "EUR",
    items: [
      {
        item_id: "SKU_12345",
        item_name: "Stan and Friends Tee",
        index: 0,
        price: 9.99,
        quantity: 1
      },
      {
        item_id: "SKU_12346",
        item_name: "Google Grey Women's Tee",
        index: 1,
        price: 20.99,
        quantity: 1
      }
    ]
  }
});

gtag alternative

javascript

gtag("event", "purchase", {
  transaction_id: "T_12345",
  value: 25.42,
  currency: "EUR",
  items: [
    {
      item_id: "SKU_12345",
      item_name: "Stan and Friends Tee",
      index: 0,
      price: 9.99,
      quantity: 1
    },
    {
      item_id: "SKU_12346",
      item_name: "Google Grey Women's Tee",
      index: 1,
      price: 20.99,
      quantity: 1
    }
  ]
});

Impression example

Luigis box's collector utilizes view_item ecommerce event to collect an item impression, when the product detail page is visited.

javascript

window.dataLayer.push({
  event: "view_item",
  ecommerce: {
    items: [
    {
      item_id: "SKU_12345",
      }
    ]
  }
});

gtag alternative

javascript

gtag("event", "view_item", {
  items: [
    {
      item_id: "SKU_12345",
    }
  ]
});

User identifiers

By default Luigi's Box Search Analytics script assigns each user a unique identifier and saves it in a _lb cookie. We use this cookie to count various usage metrics in Luigi's Box application and it serves also as a basis for personalization of search and recommendation services. However, there are some use cases when it might be better to use your own unique user identifiers:

If you would like to integrate Luigi's Box Search as a Service with personalization enabled or Recommender on backend without using our JavaScript libraries, using you own unique user identifiers enables you to use the services up to their full potential by sending user identifier also for the first visit of a user, when you do not have our _lb cookie identifier available on your backend.
If you know that most or all of your users are logged in while browsing your site, you may leverage your user identifiers to get insight into their behavior cross-device.

If you would like to set your own unique user identifiers, you can provide a function that returns the customer ID in the collector configuration:

javascript

window.dataLayer.push({
  event: 'luigisbox.collector.configure',
  options: {
    getCustomerId: () => {
      return customerId; // Replace with your method of getting the customer ID
    }
  },
});

If the getCustomerId function is not provided or returns null/undefined, the default behavior will be triggered and Luigi's Box Search Analytics script will assign a unique identifier as described above.

Troubleshooting

While you are developing the integration, we recommend that you turn on data linter to see debugging information. Make sure that Luigi's Box integration script is included in the page and then, in your web browser, open the developer console (usually by pressing the F12 key), find the "Console" tab and type in the following command: Luigis.lint = true

After that, reload the page, but do not close the developer console. Each time, the integration collects search-related data, you will see what was parsed from your site and you'll get a report about data quality in the console tab of the developer tools.

If you've done everything correctly, you should see a blue Luigi's Box logo. If there were some problems with the data, you will see a red logo and a list of errors.

If you are not seeing the linter messages and logos, the most probable cause is that you are already running an early version of integration that does not support linting. Let us know and we will upgrade your integration.

Left side: no errors found. Right side: linter found some errors.

Support

Troubles? Different nesting? Cannot get it to work? Contact us at support@luigisbox.com, we are glad to help!