Contact Support

Customizing Elevar's Data Layer

Learn how to transform existing events + build your our events.

Suggest Edits

📘

This guide is is for version 3.9+

On an older version? Follow our guide to upgrade.

If the event data our Data Layer sends by default doesn't work for you, you have two options:

Option 1: Transform Existing Events
Option 2: Build Your Own Events

Regardless of which option you choose, we recommend keeping your code separate from our snippets.

Best Practice: Keep Your Code Separate from Elevar's Snippets

When our Data Layer is updated or reinstalled from our app, our snippets (and the lines of code where we include these snippets) are completely replaced. This means that any changes made to them manually will be overwritten. For this reason, we strongly advise against modifying our snippets directly to avoid you losing your changes.

Instead, we recommend that your create your own snippets that call our utilities. Although it is ultimately for you to decide how to go about doing this, here's the process we recommend for making such changes:

  1. Duplicate your theme into a theme with a name prefixed with "Elevar".
  2. Add a new snippet. Prefix the snippet's name with "elevar-" (for example, elevar-customizations.liquid):
  1. Add the following to the snippet as a starting point: 
<script>
// Add JavaScript code here - see options 1 + 2 in sections below
</script>
  1. Include the snippet in the <head> of theme.liquid and/or checkout.liquid (depending on if you want it to execute in checkout or not, and if you have access to checkout.liquid). Note that any custom snippets that are calling Elevar's utilities need to be placed below Elevar's snippets:
{% render 'elevar-customizations' %}

Option 1: Transform Existing Events

Before an event is pushed to our Data Layer, we look to see if window.ElevarTransformFn exists. If it does exist, we call it, passing it the event that was going to be pushed. The return value of this function is what will now be pushed to the Data Layer. This allows you to write code to transform what data is sent in events.

For example, if you add the following code to your snippet:

window.ElevarTransformFn = item => {
	if (item.event === "dl_add_to_cart") {
		return {...item, custom_property: "my_custom_property"};
	} else {
		return item;
	}
};

Any add to cart events with include the custom_property value shown above.

console.log(window.dataLayer[...].custom_property); // logs `my_custom_property`

You are in control of the logic here, but there are few things to keep in mind:

  • The function provided must always return a value. This means that if you are only wanting to transform certain events, make sure that you return the passed event object in all other cases.
  • Do not directly mutate the event object that is passed into the function. This event object is shown in our debugger, so mutating it directly will result in a degraded debugging experience.
  • We rely on all properties existing in the events we push, so to ensure that our app continues to work as expected, do not omit any properties that exist in the base event passed to the function.
  • If you are wanting to modify an existing property's value (which we advise against in most cases, as it can easily break things), make sure that the value you use matches the existing value's type. For example, if the property contains a string, don't change it to contain a number.

Option 2: Build Your Own Events

There are two reasons why you'd want or need to build and send your own events via our Data Layer:

  1. The built-in event handlers don't work well for your sites theme (please let us know if this is the case, as we'll see if we can improve our built-in handlers to get them working on a wider selection of themes). If this is the case, be sure to turn off the relevant event in your Data Layer settings (in step 1) before continuing.
  2. You want to push your own client-side events to GTM but need to ensure that they include our contextual event information (user ID, device info, tracking cookie + query parameter values. etc.).

Both of these scenarios require you to use another one of our code utilities, window.ElevarDataLayer.push.

For scenario 1, you'll need to ensure that the data pushed matches what our built-in handlers push:

window.ElevarDataLayer.push({ event: "dl_add_to_cart", ... });

For scenario 2, you can push whatever data you want (as it's up to you to read from it in GTM):

window.ElevarDataLayer.push({ event: "custom_event", ... });

Updated about 1 month ago