Setting up Lazy Load for pixel apps

Lazy Load for pixel apps consists of delaying the injection of the pixel script snippet via render-server or by the app itself. For more information about pixel apps, read this doc.

This feature is in beta. Lazily loading pixel apps can cause misbehavior on all pixel apps. So, after setup, ensure all pixel apps are working properly.
To set this up, you must have access to a VTEX account and the VTEX IO CLI.

Setting up the Lazy Load on an account

The setup consists of enabling the experimentalLazyLoadAllPixels setting on the vtex.store app and then enabling the experimentalLazyLoad setting for each pixel app.

All ecommerce stores built on VTEX IO use vtex.store. To learn more, check the vtex.store app repository.

Setting	Description	Apply to	Values
experimentalLazyLoadAllPixels	Enable or disable the lazy load feature for all pixel apps.	vtex.store	`true` - enable the lazy load. `false` - disable the lazy load.
experimentalLazyLoad	This setting allows overriding the `experimentalLazyLoadAllPixels` setting.	Any pixel app	`"never"` - never loads lazily the pixel snippet. `"default"` - load lazy according to experimentalLazyLoadAllPixels setting. `"always"` - always loads lazily the pixel snippet. If the value of this setting is empty, it behaves equally to `"default"`.

Each of these settings can also be used on its own.

To set a value for any of those settings, you can use this command:


_10vtex settings set {vendor}.{appname} {name of the setting} {value of this setting}

Example of setting up the value true to the experimentalLazyLoadAllPixels setting:


_10vtex settings set vtex.store experimentalLazyLoadAllPixels true

Making the Pixel App load itself lazily

To make the pixel app load itself lazily, you must add the experimentalLazyLoad property on the app settingsSchema. By doing this, the vtex.pixel-server app will create a local setting experimentalHasOwnLazyLoad with value true.

Do not add the experimentalHasOwnLazyLoad setting on the app settingsSchema, nor set it via VTEX IO CLI. This is an internal setting.

The pixel app can access the experimentalLazyLoad setting like in this code example:


_10const experimentalLazyLoad = "{{settings.experimentalLazyLoad}}"

Example of how to do the lazy load:


_22(function() {
_22  const experimentalLazyLoad = "{{settings.experimentalLazyLoad}}" === "always"
_22
_22  function whatShouldBeLazyLoadHere() { ... }
_22
_22  if (experimentalLazyLoad) {
_22    function lazyTimeout() {
_22      setTimeout(whatShouldBeLazyLoadHere, 5000)
_22      window.removeEventListener('load', lazyTimeout)
_22    }
_22
_22    if (document.readyState === 'complete') {
_22      lazyTimeout()
_22    } else {
_22      window.addEventListener('load', lazyTimeout)
_22    }
_22
_22    return
_22  }
_22
_22  whatShouldBeLazyLoadHere()
_22})()

Combination of all settings

experimentalHasOwnLazyLoad	experimentalLazyLoad	experimentalLazyLoadAllPixels	Result
false	never	false	Apps load normally.
false	never	true	A specific app loads normally, and all others load lazily.
false	default	false	Apps load normally.
false	default	true	All apps load lazily, including the specific app.
false	always	false	A specific app loads lazily, and all others load normally.
false	always	true	All apps load lazily.
true	never	false	Apps load normally.
true	never	true	A specific app loads normally, and all others load lazily.
true	default	false	Apps load normally.
true	default	true	A specific app loads itself lazily, and all others load lazily by render.
true	always	false	A specific app loads itself lazily.
true	always	true	A specific app loads itself lazily, and all others load lazily by render.

Lazy loading is one of many actions you can take to optimize performance. To know more about other possible practices, check Best practices for optimizing performance.