Shopify Source Upgrade Guide for Users with Customizations
When upgrading to Elevar's new Shopify Source (a.k.a. Elevar's App Embed), you may need to make modifications to any custom Data Layer code you might have.
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) - If this code is not run before your pushes, those calls will fail, so make sure the above code runs first.
window.ElevarDataLayer = window.ElevarDataLayer ?? [];
Update Your Data Layer Pushes:
- You previously needed to call
window.ElevarPushToDataLayer
to push Data Layer events. - Now, you must 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 have upgraded to Elevar's new Shopify Source (a.k.a. Elevar's App Embed), you will 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 afterwindow
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) - If this code is not run before your pushes, those calls will fail, so make sure the above code runs first.
window.ElevarDataLayer = window.ElevarDataLayer ?? [];
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.
Updated 4 months ago