Install guide
Adding a chat assistant to Magento or Adobe Commerce
Magento has a field designed for exactly this, scoped per store view, which is more useful than it sounds if you run more than one storefront. The step people forget is the cache: Magento serves cached pages until told otherwise, so a correct install can look like a failed one for an hour.
The tag
<script src="https://cdn.askably.xyz/w.js" data-key="pk_live_YOUR_KEY" defer></script>Your own key replaces the placeholder. You will find it on the install tab of the assistant.
The origin the page is served from has to be on the allowlist for that assistant, or nothing renders and the browser console says which origin was refused. An apex domain and its www are two different origins to a browser, so list both, along with any staging or preview host you want it to work on.
Where it goes on Magento and Adobe Commerce
Content, then Design, then Configuration. Edit the store view, open the Footer section, and use Miscellaneous HTML.
Available in Magento Open Source and Adobe Commerce alike. No extension is needed, and no developer access to the file system is required.
Step by step
- 1In the admin open Content, then Design, then Configuration.
- 2Find the row for the store view you want, and choose Edit. Scope matters here: editing at Default level applies to every store view under it.
- 3Expand HTML Head if you want it site wide, or Footer if you want it at the end of the body. Footer is the right choice.
- 4Paste the tag into Miscellaneous HTML.
- 5Save Configuration.
- 6Flush the Magento cache, then flush any full page cache in front of it. Until you do, the storefront keeps serving the version without the tag.
What goes wrong on Magento and Adobe Commerce
Scope is the whole point, and the whole trap
Design Configuration is scoped by website, store and store view. Pasting the tag at Default level installs it on every storefront you run, including the ones with a different brand on them, which for a multi-store merchant is a real mistake rather than a cosmetic one.
If you run several storefronts, install per store view and give each one its own assistant key, so the answers and the branding match the site the visitor is actually on.
Cache flush is not optional
Magento serves most storefront pages from a full page cache. Saving the configuration invalidates it, but on a busy store with a separate cache layer in front, the old markup can persist. Flush both, then check the page source rather than the rendered page.
Content Security Policy is enforced by default in recent versions
Recent Magento versions ship a policy that restricts which hosts may serve scripts and which the page may connect to. If the tag is in the source and the browser console shows a policy violation rather than a refused origin, add the loader origin to the script and connect directives in your policy configuration.
Origins to allowlist
These are the origins a Magento and Adobe Commerce site is typically served from. List every one you want the assistant to answer on, including the ones only you visit.
- https://yourdomain.com
- https://www.yourdomain.com
- https://second-storefront.com
How the tag behaves, wherever you put it
The rest of this is the same on every platform, so it is worth reading once rather than on each guide.
| One tag, nothing else | There is no second file, no stylesheet and no package to install. The tag is the whole install. |
|---|---|
| Where it goes | Immediately before the closing body tag. It works in the head too, because it defers, but the body keeps it out of the way of anything that measures render order. |
| data-key is required | Without it the loader stops and writes a warning to the browser console rather than rendering anything. |
| It finds itself | The loader reads the tag it was loaded from, and falls back to the first tag on the page carrying a data-key. Platforms that move or re-inject the tag do not break it. |
| It installs once | A second copy of the tag on the same page is ignored, so a template that renders twice does not produce two launchers. |
| Assets follow the tag | Everything else it needs is fetched from the same origin the tag was served from, so a proxy or a private domain needs no extra configuration. |
| The panel loads late | Only the small launcher is on the page at first. The conversation panel is fetched the first time a visitor opens it, in its own frame. |
| Styles cannot collide | The launcher renders inside a closed shadow root and the panel inside a frame, so nothing on the host page can restyle either, and neither can restyle the host page. |
Set up on Magento and Adobe Commerce for a particular trade
The tag is the same everywhere. What is not the same is which of your pages the assistant can read once it is running, and on Magento and Adobe Commerce that depends on what kind of site this is. These go one level further than this guide.
- For a electronics retailerConsumer rights differ by market and Magento already splits your storefronts by store view. Give each one its own assistant and its own pages.
- For a furniture retailerA lead time inside a CMS block has no address of its own, and the page it sits on is cached, so the crawler often reads a figure weeks old.
Taking it off again
Clear the Miscellaneous HTML field for that store view, save, and flush the cache again.
Before you remove it
- Removing the tag stops the widget on that site. It does not delete the assistant, its material, or the enquiries it has already collected.
- If you are moving the widget to a different host rather than retiring it, add the new origin to the allowlist before you remove the old tag, or there is a window where neither works.
Questions
- HTML Head or Footer?
- Footer. The tag defers either way, so it never blocks rendering, but keeping third-party markup out of the head makes the head easier to reason about when something else goes wrong.
- Can each storefront have its own assistant?
- Yes, and it should. Install per store view with a different key in each, so a visitor on your German storefront gets an assistant that read your German content and answers under the name that storefront uses.
- Does it work with a headless front end?
- Yes. The tag is plain HTML with no dependency on Magento, so it goes in whatever layout renders your pages, and you allowlist the origin that front end is served from.
Keep reading
- Install on ShopifyOnline Store, then Themes, then the three dots beside your live theme, Edit code, then layout/theme.liquid.
- Install on WooCommerceA site-specific plugin or a code snippets plugin, hooking wp_footer. Not the theme editor.
- Install on BigCommerceStorefront, then Script Manager, then Create a Script.
- Every install guideThe same one line of HTML, and where it goes on each platform.
Try it on your own material
Upload a document or point it at your site, paste one line of HTML, then ask it something only your business could answer.