Magento (Adobe Commerce)

Overview

Magento Open Source and Adobe Commerce have a footer setting, Miscellaneous HTML, for scripts that go just before the closing </body> tag of every page. Pasting the Yaplet code there puts the chat widget on the store. No extension is needed.

Adobe's guide for this setting covers stores on your own servers and Adobe Commerce on cloud infrastructure. On Magento 2.4.7 and later, the chat won't run on the checkout pages unless a developer allow-lists it (see the checkout section below).

Installation Steps

Copy your Yaplet code

In your Yaplet dashboard, go to Brand → Chat widget and open the Install tab. If the tab asks where your website runs, choose Other website. Copy the code with the copy button on the code block.

Miscellaneous HTML takes HTML, so the code must sit between a <script> line and a </script> line. With Other website chosen, the code already has these lines. If the tab didn't ask, the code is plain JavaScript that starts with !function (Yaplet, and you add the lines when you paste it.

Open the footer settings

In the Admin sidebar, go to Content → Design → Configuration. Find the store view where you want the chat and click Edit in the Action column. Under Other Settings, expand the Footer section.

Add the Yaplet code

In Miscellaneous HTML, keep any existing code and start a new line at the end. Paste the Yaplet code there. It must start with a <script> line and end with a </script> line; if what you copied starts with !function (Yaplet instead, type <script> on a new line before it and </script> on a new line after it. Click Save Configuration.

The field is saved per store view. Repeat this for each store view where you want the chat.

Refresh the cache

If Magento shows a message that a cache needs a refresh, click the Cache Management link in it (or go to System → Tools → Cache Management). Select the caches marked as invalid, set Actions to Refresh, and click Submit, or click Flush Magento Cache.

Check your store

Open your store in a new browser tab and reload it. The Yaplet chat button appears in the bottom-right corner. Click it to check that the chat opens.

Checkout on 2.4.7 and later

From version 2.4.7, Magento's Content Security Policy (CSP) runs in restrict mode on payment pages (storefront checkout and the admin's payment pages) and in report-only mode on all other pages. In restrict mode only allow-listed inline scripts run, and Adobe's page-setup guide states that JavaScript in Miscellaneous HTML must be allow-listed or it won't run on checkout. Before 2.4.7, every page was report-only.

So without changes, the chat runs everywhere except checkout. To show it on checkout too, a developer adds Yaplet to a csp_whitelist.xml in a custom module's etc folder:

The inline Yaplet code: a sha256 hash, Base64-encoded, of the exact text between the <script> and </script> tags, line breaks included. The code contains your widget ID, so compute the hash from your own code and again whenever you change it.
Yaplet's addresses: the scripts load from https://yaplet.com and https://sdk.yaplet.com, the widget calls https://yaplet.com and keeps a live connection to wss://phx.yaplet.com, the chat window is a frame from https://embed.yaplet.com, images come from https://api.yaplet.com and https://cdn.yaplet.com, and the new-message sound from https://yaplet.com.

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="yaplet-snippet" type="hash" algorithm="sha256">YOUR_BASE64_HASH</value>
                <value id="yaplet" type="host">https://yaplet.com</value>
                <value id="yaplet-sdk" type="host">https://sdk.yaplet.com</value>
            </values>
        </policy>
        <policy id="connect-src">
            <values>
                <value id="yaplet-api" type="host">https://yaplet.com</value>
                <value id="yaplet-live" type="host">wss://phx.yaplet.com</value>
            </values>
        </policy>
        <policy id="frame-src">
            <values>
                <value id="yaplet-embed" type="host">https://embed.yaplet.com</value>
            </values>
        </policy>
        <policy id="img-src">
            <values>
                <value id="yaplet-api-img" type="host">https://api.yaplet.com</value>
                <value id="yaplet-cdn" type="host">https://cdn.yaplet.com</value>
            </values>
        </policy>
        <policy id="media-src">
            <values>
                <value id="yaplet-sound" type="host">https://yaplet.com</value>
            </values>
        </policy>
    </policies>
</csp_whitelist>

Adobe's Content Security Policies guide covers the file format, the nonce provider (an alternative to the hash) and how to change the CSP mode per area.

Troubleshooting

The code shows up as text at the bottom of the pages — the <script> tags are missing. Put <script> on a new line before the code and </script> on a new line after it, save, and refresh the cache.
Nothing changed after saving — the page cache still serves the old pages. Refresh the invalid caches in System → Tools → Cache Management, and clear any other page cache in front of the store.
The chat shows on one store view but not another — Miscellaneous HTML is saved per store view. Add the code to the other store view too.
The chat is missing only on checkout — that is the 2.4.7+ CSP restrict mode on payment pages. See the checkout section above.
The browser console says "Refused to execute inline script because it violates the following Content Security Policy directive" on other pages too — the storefront has been switched to restrict mode everywhere. Allow-list Yaplet as shown above.
The browser shows an old copy of the page — clearing the Magento cache doesn't clear the browser cache. Reload, or open the store in a private browser window.

The Installation page explains what the code does and lists every other platform guide.