Which Magento versions are supported?

Magento Open Source 2.x and Adobe Commerce. The script tag is theme-agnostic, so Luma, Hyva and custom themes all work as long as the tag reaches the rendered page; what changes between versions is the default CSP mode, not the install.

Admin configuration or layout XML, which should I use?

Layout XML if the store is deployed from version control, because the change ships with the code and is reproducible across environments and scopes. The admin field is faster for a one-off, needs no deploy, and is scoped to a store view.

Do I need to whitelist the domain for CSP?

For checkout, yes: Adobe states that JavaScript in Miscellaneous HTML must be whitelisted or it will not execute on the Checkout pages. Elsewhere on 2.4.7 and later the default is report-only, which logs a violation without blocking, so the widget still loads; adding app.inclusifyapp.com to script-src in a csp_whitelist.xml keeps it working when a theme, an extension or your server tightens the policy.

Does the widget load on checkout?

Yes, once the host is whitelisted in your CSP settings and the tag is in a container the checkout layout renders. before.body.end is rendered on checkout; some header-only containers are not.

Magento

Inclusify installs on Magento 2 and Adobe Commerce as one script tag, either pasted into Content Design Configuration under the Footer section’s Miscellaneous HTML field, which Adobe documents as rendering just before the closing </body> tag, or added through your theme’s layout XML. You need an admin account with the Design Configuration permission, and there is no edition requirement: Open Source and Adobe Commerce both take it. Budget one cache flush rather than a deploy for the admin route, and a deploy plus a static-content deploy for the layout route. Two Magento-specific things decide whether it works: the field is scoped to a store view, and checkout needs the host in your Content Security Policy.

Register the domain first

Add your domain in the Inclusify panel before you paste the script tag. Bundles are built per registered domain, and an unregistered one fails silently: the script URL still returns HTTP 200, but what it serves is a single console.log saying the domain is not registered. There is no error to find and no widget appears.

Method 1: Admin Panel

Open Design Configuration

Go to Content Design Configuration in your Magento admin.

Edit the scope you want

The grid has one row per scope, and Adobe lists Miscellaneous HTML with a scope of Store View. Click Edit on Default so every view inherits it, or on a single store view row to change just that one. A multi-store install showing the widget on one storefront and not another is nearly always this row.

Add to Miscellaneous HTML

Expand Footer and paste into Miscellaneous HTML, the field Magento renders just before the closing </body> tag:

HTML

<script src="https://app.inclusifyapp.com/w/YOUR-DOMAIN.com.js" async></script>

Save & Clear Cache

Click Save Configuration, then clear the cache at System Cache Management.

Method 2: Layout XML

For a change that ships with your code, add the script through your theme’s default.xml layout. The whole file is shown below: xsi:type is only valid if the <page> root declares the xsi namespace, so a fragment pasted on its own fails layout validation.

app/design/frontend/[Vendor]/[theme]/Magento_Theme/layout/default.xml

<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceContainer name="before.body.end">
            <block class="Magento\Framework\View\Element\Text" name="inclusify.widget">
                <arguments>
                    <argument name="text" xsi:type="string"><![CDATA[<script src="https://app.inclusifyapp.com/w/YOUR-DOMAIN.com.js" async></script>]]></argument>
                </arguments>
            </block>
        </referenceContainer>
    </body>
</page>

Whitelist the host for CSP

This step is not optional if you want the widget on checkout. Adobe’s note on the Miscellaneous HTML field says that all JavaScript entered there must be whitelisted in the Content Security Policy settings, otherwise it will not be executed on the Checkout pages. Elsewhere it depends on your version: from 2.4.7 Adobe ships CSP in restrict mode for payment pages in the storefront and admin and in report-only mode for every other page, and before 2.4.7 every page was report-only. Report-only logs the violation without blocking the request, which is why a widget can look fine while the console fills up.

Adobe’s documented way to add a host is a csp_whitelist.xml in your own module’s etc folder, which ships with your code instead of living in someone’s admin session:

app/code/[Vendor]/[Module]/etc/csp_whitelist.xml

<?xml version="1.0"?>
<csp_whitelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Csp:etc/csp_whitelist.xsd">
    <policies>
        <policy id="script-src">
            <values>
                <value id="inclusify" type="host">https://app.inclusifyapp.com</value>
            </values>
        </policy>
    </policies>
</csp_whitelist>

Notes

• Works with Magento Open Source 2.x and Adobe Commerce. What changes between versions is the default CSP mode, not the install
• The script tag is theme-agnostic. Luma, Hyvä and custom themes all run it; what differs is where you can get it onto the page, so if Method 1 does not reach the rendered HTML on your theme, use Method 2
• Miscellaneous HTML is store-view scoped. Set it on Default unless you deliberately want one storefront to differ
• Flush the full-page cache after every change, and purge Varnish if it sits in front of Magento
• The HTML Head section has a Scripts and Style Sheets field with the same CSP condition attached. The widget belongs in the footer field, not that one

What needs attention on Magento

Miscellaneous HTML is scoped to a store view

Adobe lists the Footer section's Miscellaneous HTML field with a scope of Store View, and describes it as an input box for scripts that must be placed just before the closing </body> tag. Editing the Default row covers every view that inherits it; editing one view's row covers only that view. A multi-store install that shows the widget on one storefront and not another is nearly always this.

Checkout needs the host in your CSP, whatever mode you are in

Adobe's note on the field is unambiguous: all JavaScript entered in Miscellaneous HTML must be whitelisted in the Content Security Policy settings, otherwise it will not be executed on the Checkout pages. This is not a theme quirk to work around; it is the documented behaviour of the field.

The default policy mode changed in 2.4.7

From 2.4.7, Adobe Commerce and Magento Open Source ship CSP in restrict mode for payment pages in both the storefront and the admin, and in report-only mode everywhere else. Before 2.4.7 every page was report-only. Report-only logs a violation without blocking the request, which is why a widget can appear to work while the console fills with warnings.

Whitelisting is one file in your own module

Adobe documents adding a host to a policy by putting a csp_whitelist.xml in your custom module's etc folder, with a <policy id="script-src"> block listing each host as a <value ... type="host"> entry. Add https://app.inclusifyapp.com there and the entry ships with your code rather than living in someone's admin session.

Verify the installation

Flush the full-page cache from System > Cache Management before testing, and purge Varnish if it sits in front of Magento. Until you do, Magento serves the HTML it rendered before your change.
Load a category page and a product page in a private window and confirm the tag is present in View Source. Miscellaneous HTML is server-rendered, so absence from the source means the change did not reach the page.
Check the store view you actually edited. Miscellaneous HTML is a store-view scoped field, so a tag set on one view is absent from the others.
Test checkout separately, and expect it to need a CSP entry: Adobe states that JavaScript entered in Miscellaneous HTML must be whitelisted in the Content Security Policy settings or it will not execute on the Checkout pages.
In production mode, run bin/magento setup:static-content:deploy if you added the script through a layout XML change rather than the admin field.

Widget bundles are served from a CDN and cached for a few hours. If you changed widget settings in the panel and the site still shows the old configuration, wait for the cache to expire or load the script URL directly with a cache-busting query string (`?v=2`) to confirm the new version is being served.

Troubleshooting Magento installs

The script is saved in the admin but does not appear on the storefront.: Full-page cache is still serving old HTML. Flush the cache in System > Cache Management, and purge Varnish if it sits in front of Magento.
The widget works everywhere except checkout.: This is the documented behaviour of the Miscellaneous HTML field: JavaScript entered there has to be whitelisted in the CSP settings or it does not execute on the Checkout pages. Add app.inclusifyapp.com to script-src through a csp_whitelist.xml in your module's etc folder.
The browser console reports a Content Security Policy violation.: The widget host is not listed in a policy that is being enforced. On 2.4.7 and later that is restrict mode, which Adobe applies by default to payment pages in the storefront and admin; elsewhere the default is report-only, so an enforcing policy there came from your theme, an extension or the server. Either way the fix is a csp_whitelist.xml entry for script-src.
The widget loads on Luma but not on a Hyva theme.: The admin field is not reaching the rendered page on that theme. Add the tag through the theme's layout XML into the before.body.end container instead, and whitelist the host in csp_whitelist.xml.
The tag appears on some store views only.: Miscellaneous HTML is store-view scoped. Set it on the Default row so every view inherits it, or repeat it on each view that needs it.

Magento questions

Which Magento versions are supported?: Magento Open Source 2.x and Adobe Commerce. The script tag is theme-agnostic, so Luma, Hyva and custom themes all work as long as the tag reaches the rendered page; what changes between versions is the default CSP mode, not the install.
Admin configuration or layout XML, which should I use?: Layout XML if the store is deployed from version control, because the change ships with the code and is reproducible across environments and scopes. The admin field is faster for a one-off, needs no deploy, and is scoped to a store view.
Do I need to whitelist the domain for CSP?: For checkout, yes: Adobe states that JavaScript in Miscellaneous HTML must be whitelisted or it will not execute on the Checkout pages. Elsewhere on 2.4.7 and later the default is report-only, which logs a violation without blocking, so the widget still loads; adding app.inclusifyapp.com to script-src in a csp_whitelist.xml keeps it working when a theme, an extension or your server tightens the policy.
Does the widget load on checkout?: Yes, once the host is whitelisted in your CSP settings and the tag is in a container the checkout layout renders. before.body.end is rendered on checkout; some header-only containers are not.

Magento documentation

Every Magento-specific requirement, menu path and limit on this page comes from these pages. Menus move, so check them against your own admin if something does not match.

Inclusify for Magento covers what the widget does on a Magento site, and pricing.
Script installation generates the embed code for your domain.
Customization covers the position, colour and size of the widget button.