Magento

Add Inclusify to your Magento 2 store using a custom module or direct template editing.

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

1

Open Design Configuration

Go to Content Design Configuration in your Magento admin.

2

Edit the scope you want

The grid has one row per scope. Click Edit on Default to cover every store view, or on a single store view row to change just that one.

3

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>
4

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>

Notes

  • • Works with Magento Open Source 2.x and Adobe Commerce
  • • 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.
  • • Remember to clear cache after changes

Verify the installation

  1. Flush the full-page cache from System → Cache Management before testing — Magento serves the previously rendered HTML until you do.
  2. Load a category and a product page in a private window and confirm the script tag is present in View Source.
  3. In production mode, run bin/magento setup:static-content:deploy if you added the script through a layout XML change.

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 browser console reports a Content Security Policy violation.
Something on the site is enforcing a policy the widget host is not listed in. On 2.4.7 and later that is restrict mode, which Adobe turns on by default for payment pages in the storefront and admin; elsewhere the default is report-only, so an enforcing policy there was configured by your theme, an extension or the server. Either way, add app.inclusifyapp.com to script-src in your module's or theme's csp_whitelist.xml.
The widget loads on Luma but not on the Hyvä theme.
Hyvä ships a stricter CSP and does not render Miscellaneous Scripts in every layout. Add the tag through the theme's layout XML and whitelist the host in csp_whitelist.xml.
The tag appears on some store views only.
Content → Design → Configuration is scoped per store view. Either set the script at the Default scope or repeat it for each store 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, Hyvä and custom themes all work as long as the tag reaches the rendered page.
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. The admin field is faster for a one-off and needs no deploy.
Do I need to whitelist the domain for CSP?
Usually not, but it is cheap insurance. Adobe defaults to restrict mode only on payment pages in the storefront and admin on 2.4.7 and later, and to report-only everywhere else; before 2.4.7 every page was report-only. Report-only logs a violation without blocking the request, so the widget still loads. Listing app.inclusifyapp.com in csp_whitelist.xml keeps it working if your theme, an extension or your server tightens the policy.
Does the widget load on checkout?
Yes, provided the script is placed in a container present in the checkout layout. before.body.end is rendered on checkout; some header-only containers are not.

Related