Overview

In this article, we'll cover what actions you should take before upgrading to Elevar's new Shopify Source if you are headless, sending custom Data Layer events, or have customized Elevar's built-in Data Layer events. Please follow the instructions that fit your situation:

• How do I make my headless Data Layer compatible?
• I've built my own Data Layer events instead of using Elevar's - how do I make these compatible?
• I've customized Elevar's Data Layer (by adding/overwriting fields) - how do I make this compatible?

Headless Data Layer

To make your headless Data Layer compatible with Elevar's new Shopify Source, you'll need to add in our new initialization code, update your data layer pushes, and update your route change code.

Add Our New Initialization Code

Add this code to run before any of your Data Layer pushes occur (before any window.ElevarPushToDataLayer calls):

 window.ElevarDataLayer = window.ElevarDataLayer ?? [];

If this code is not run before your pushes, those calls will fail, so make sure the above code runs first.

Update Your Data Layer Pushes

You previously needed to call window.ElevarPushToDataLayer to push Data Layer events.

You must now call window.ElevarDataLayer.push instead.

🚧

Warning: This update is not backwards compatible

Do not call window.ElevarDataLayer.push with a Data Layer below version 3.9.0, as these calls will fail.

Update Your Route Change Code

You previously needed to call window.ElevarGtmSuiteAAT.utils.pushContextToDataLayer() to push context changes (like page URL & title changes) when a user navigates to another page on your site without triggering a full page reload (this is often how route changes work on headless sites).

You must now call window.ElevarInvalidateContext?.() instead.

Again, this is not backwards compatible. Do not use this new utility with a Data Layer below version 3.9.0.

📘

Bonus: More accurate data

With this change, your Data Layer pushes will now behave more like they do on initial page load - meaning that when you invalidate the context, our code will wait for the new context information to be available before processing new Data Layer pushes, which ensures that these new events are guaranteed to have data (e.g. page URL, page title) that relate to the current page (not previous page data).

Other Updates

Debug Mode

Previously, you could run window.ElevarGtmSuiteListener.utils.debug(true)in your browser's Developer Console to enable Elevar's Debug Mode, which shows you if your Data Layer event shape matches what we expect (making it simple to tell if you are pushing events in the correct format).

Once you've upgraded to Elevar's new Shopify Source (a.k.a. Elevar's App Embed), you'll instead need to run the following in your console the enable Elevar's Debug Mode: window.ElevarDebugMode(true).

📘

Note: Hard coding Elevar's Debug Mode Calls

We've seen developers hard code Elevar Debug Mode calls on their site instead of using the browser's Developer Console to enable it, perhaps to speed up the QA process as you are building your site.

We do not recommend hard coding Elevar's Debug Mode call in your website's code, as it can impact the performance of your site if it is not removed before going live, and it's easy to forget to remove it. Also, if it's hard coded to be disabled (turned off), it isn't possible to enable Debug Mode via the browser's Developer Console in a way where it stays enabled across page reloads, which would make it harder for you or our support team to diagnose any problems you may run into.

With that being said, if you accept the risks mentioned above and are wanting to use it to enable debug mode for all users when building/QAing your site, be sure to call window?.ElevarDebugMode(true). Adding the question mark after window ensures that trying to enable debug mode before our code has loaded won't result in other code on your site breaking.

Global Removals

Once you've upgraded to Elevar's new Shopify Source (a.k.a. Elevar's App Embed), the following global variables will no longer be available:

• window.ElevarGtmSuite
• window.ElevarGtmSuiteAAT
• window.ElevarGtmSuiteListener
• window.__ElevarIsGtmSuiteCalled
• window.__ElevarIsGtmSuiteAATCalled
• window.__ElevarIsGtmSuiteListenerCalled
• window.__ElevarIsContextSet
• window.__ElevarTransformItem
• window.__ElevarDataLayerQueue
• window.__ElevarListenerQueue

For the majority of customers, this should have no impact on your setup. However, if you are currently referencing any of the above globals (for example, if you were checking for window.ElevarGtmSuiteAAT to be present before calling our context push utility), these will no longer work.

In short, these are the only Elevar globals that should be referenced in your code after upgrading.

• window.ElevarDataLayer
• window.ElevarInvalidateContext
• window.ElevarDebugMode
• window.ElevarTransformFn
• window.ElevarUserIdFn

Custom Data Layer Events

If you are sending your own custom Data Layer events instead of using Elevar's pre-built Data Layer, you must add our new initialization code and use our new utility.

How do I Know if I'm Sending Custom Data Layer Events?

Below are some common example scenarios where a merchant is sending their own custom Data Layer events:

Example #1: You've disabled Elevar's built-in dl_view_item_list event and are pushing your own dl_view_item_list event on your collection pages because our built-in event doesn't work on your theme.

Example #2: You built your own dl_view_item & dl_add_to_cart events to fire on your custom non-Shopify third party landing page.

Add Our New Initialization Code

Add this code to run before any of your Data Layer pushes occur (before any window.ElevarPushToDataLayer calls):

 window.ElevarDataLayer = window.ElevarDataLayer ?? [];

If this code is not run before your pushes, those calls will fail, so make sure the above code runs first.

Update Your Data Layer Pushes

You previously needed to call window.ElevarPushToDataLayer to push Data Layer events.

You must now call window.ElevarDataLayer.push instead.

🚧

Warning: This update is not backwards compatible

Do not call window.ElevarDataLayer.push with a Data Layer below version 3.9.0, as these calls will fail.

Customized Data Layer

If you have customized Elevar's pre-built Data Layer events to add or overwrite a field, you will need to make sure you're using a separate snippet in your theme and are using Elevar's utilities before updating to the new Shopify Source (a.k.a. Elevar's App Embed).

How do I Know if I've Customized my Data Layer?

Below are some common example scenarios where a merchant has customized the existing Elevar Data Layer:

Example #1: You have directly edited the Shopify liquid in an Elevar snippet to pass your own unique product identifier in the product_id field of Elevar's dl_view_item, dl_add_to_cart, dl_begin_checkout, and dl_purchase events.

Example #2: You are pushing your own custom Data Layer event before Elevar's dl_add_to_cart event, and your custom event includes a new product_color field which (because it fired first) is available in Elevar's dl_add_to_cart event in GTM. This means that all your GTM "Add to Cart" tags include this new product_color property, which can be sent to destinations client-side.

Example #3: You are transforming our pre-built Data Layer events via the officially supported utility. You will see a window.ElevarTransformFn function defined in your Shopify Theme.

Example #4: You are using your own user identifier to re-identify shoppers coming back to your website. You will see a window.ElevarUserIdFn function defined in your Shopify Theme.

Use a Separate Snippet

When upgrading to Elevar's App Embed, we will automatically remove the legacy elevar snippets (elevar-head, elevar-head-listener, elevar-body-end, & elevar-checkout-end) from your live theme in order to prevent duplicate tracking. If your customizations lived directly in those snippets, your customizations will be removed.

To prevent this, create a new snippet [Instructions] & move your customizations there.

Add Your Customizations to Shopify's Custom Pixel

If your customizations need to be applied to checkout or purchase events, you'll need to add you customization code to your checkout tracking pixel [Instructions .

Use the Transform or User ID Functions

The new App Embed only supports customizations that use our transform function [Documentation] or the User ID function [Documentation]. If any other methods are used to add or overwrite fields in Elevar's pre-built Data Layer, those customizations may not work after upgrading to Elevar's new Shopify Source.