Experience Cloud Developer Guide

Get Up to Speed with Experience Builder Sites
Develop Experience Builder Sites: The Basics
Brand Your Aura Site
Develop Secure Sites: Authenticated and Guest Users
Develop Secure Sites: CSP, LWS, and Lightning Locker
Resolve Lightning Locker Conflicts in Aura Sites
Enable Third-Party Components to Run When Lightning Locker Is Off
Example: Adobe Analytics and Lightning Locker in Aura Sites
Analyze and Improve Experience Builder Site Performance
Add Pardot Tracking to Your Experience Builder Site
Use a CMS with Your Experience Builder Site
Report on Deflections: The Deflection Signals Framework
Deploy an Experience Cloud Site from Sandbox to Production
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Resolve Lightning Locker Conflicts in Aura Sites

Lightning Locker is enabled by default for all new Aura sites in Experience Cloud. However, occasionally a third-party component on the page or custom code in your head markup doesn’t work as expected due to a conflict with Lightning Locker. In such a situation, Salesforce recommends using one of the workarounds described here.

Use JavaScript Custom Events

Lightning Locker protects third-party components and custom code from interacting with resources from other namespaces, but not from the head markup. This limitation means that your head markup can contain custom code that bypasses Lightning Locker and introduces security vulnerabilities.

To address this limitation, isolate your third-party Aura and Lightning web components and custom code by using the CustomEvent constructor in your head markup. Third-party components and custom code can then interact with your resources without being responsible for loading or referencing that resource directly.

Any data that must be passed through the event to the listener is passed in the detail property, which is created when initializing the event. The detail property is mapped to the dataLayer in your head markup listener. The custom events are then dispatched to any resource that extends EventTarget. For an example of using custom events, see Adobe Analytics and Lightning Locker.

Be aware of the data that you’re passing with the JavaScript CustomEvent constructor, and ensure that your usage is secure. Any JavaScript running on your page, including any third-party App Exchange components that you’re using, can potentially listen for your event names and read this data.

Warning

Set an Aura Component to API 39.0

If your third-party component or custom code doesn’t interact with an Aura component as expected, you can set the Aura component to Salesforce API version 39.0, which disables Lightning Locker for the component. See Disable Lightning Locker for a Component in the Lightning Aura Components Developer Guide.

Disabling Lightning Locker for an Aura component can introduce security flaws into your site and prevent the component from being available at design time or rendering at runtime.

Warning

For consistency and ease of debugging, avoid having a parent Aura component and a child component on different API versions. Therefore, don’t use any Aura component set to API version 39.0 in a component hierarchy, such as a component within a component or a component that’s extending another component.

If LWS is enabled in the org, setting API version 39.0 in the component doesn’t disable LWS for the component. However, LWS is likely to allow behaviors of components that Lightning Locker blocks, removing the need to disable it.

Turn Off Lightning Locker

Use this workaround only as a last resort.

Warning

If you turn off Lightning Locker in your site, you disable it for all your site’s third-party components and custom code. The ramifications can be far-ranging and unexpected, such as introducing security flaws into your site. And if a third-party component hasn’t been enabled to work without Lightning Locker, it can prevent that component from being available at design time and rendering at runtime. When Lightning Locker is turned off, components from different namespaces can interact with and access each other’s Document Object Model (DOM), and restrictions around custom resources interacting with your site are relaxed.

For more information on disabling Lightning Locker, see Select a Security Level in Experience Builder Sites in Salesforce Help.

If LWS is enabled in the org, when you disable Lightning Locker in an Aura site, you actually disable LWS in the site. If you disable Lightning Locker in the LWR site, the site’s instance of LWS is disabled, even if LWS is enabled in the org.

Note