DataLayer collector

The DataLayer-based collector is currently in beta.

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:

  1. Using gtag manager: Utilize the gtag manager to seamlessly push ecommerce events to the dataLayer.

  2. 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

Collector script will be added via LBX script. Please insert the LBX script to the <head> element of each page.

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

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, view_item, select_item, add_to_cart, purchase.
item_list_name Name of the reported list. Supported list names are: Autocomplete, Search Results, Product Listing, Recommendation.
items An array containing list results.
item_id Identity 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.

Identity

Ensure that the item_id event property matches the identity of the indexed data.

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.

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

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.

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

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"
  }
});

Product Listing example

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

window.dataLayer.push({
  event: "view_item_list",
  ecommerce: {
    item_list_name: "Product Listing",
    items: [
      {
        item_id: "SKU_12345",
        item_name: "Black phone 256gb",
        index: 0,
        price: 9.99,
      },
      {
        item_id: "SKU_12346",
        item_name: "Black phone 128gb",
        index: 1,
        price: 20.99,
      }
    ],
    scopes: {
      "CategoryLabel": "Electronics | Phones | Black Phones",
      "CategoryIdentity": "12345",
    },
    filters: {
      "Operating system": "Android" // Pass additional filters selected by the user
    }
  }
});

gtag alternative

gtag("event", "view_item_list", {
  item_list_name: "Product Listing",
  items: [
    {
      item_id: "SKU_12345",
      item_name: "Black phone 256gb",
      index: 0,
      price: 9.99,
    },
    {
      item_id: "SKU_12346",
      item_name: "Black phone 128gb",
      index: 1,
      price: 20.99,
    }
  ],
  scopes: {
    "CategoryLabel": "Electronics | Phones | Black Phones",
    "CategoryIdentity": "12345",
  },
  filters: {
    "Operating system": "Android" // Pass additional filters selected by the user
  }
});

For product listing events, you must include scopes object with these parameters:

Scope name Scope value
CategoryLabelREQUIRED Category path in a human-readable format, with specific categories separated by a pipe. The current category name has to be included in the path. If the full path is not available, the current category name suffices.
CategoryIdentityREQUIRED An identifier of the category, which must match the identity in the catalog.

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.

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

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
RecommenderClientIdREQUIRED 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).
ItemIdsoptional List of input items of a recommendation request (item_ids from recommendation request).
Recommenderoptional Name of the recommender (recommender from recommendation result).
Typeoptional Type of the recommender (recommendation_type from recommendation result).
_Variantoptional 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.

window.dataLayer.push({
  event: "view_item_list",
  ecommerce: {
    item_list_name: "Search Results",
    search_term: "Phone",
    items: [],
    filters: {
      "Color": ["Burgundy"],
      "Operating system": "Android"
    }
  }
});

gtag alternative

gtag("event", "view_item_list", {
  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.

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

gtag alternative

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

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.

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

gtag alternative

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

Transaction example

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

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

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.

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

gtag alternative

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:

  1. 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.
  2. 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 send a luigisbox.collector.customer_id event to the dataLayer as shown below:

window.dataLayer.push({
  event: 'luigisbox.collector.customer_id',
  customer_id: "12345"; // Replace with the actual ID 
  },
});

If the luigisbox.collector.customer_id event is not sent, the default behavior will apply. In this case, Luigi's Box Search Analytics will automatically assign a unique identifier using the _lb cookie as described earlier.

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!