Install guide
Adding a chat assistant to a Shopify store
Shopify gives every plan access to theme code, so the install is a single paste into one file. The part worth reading twice is the checkout, which is not part of your theme on any plan below Plus, and the fact that a theme update quietly removes anything you added by hand.
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 Shopify
Online Store, then Themes, then the three dots beside your live theme, Edit code, then layout/theme.liquid.
Every Shopify plan can edit theme code, so there is no upgrade to buy. The exception is the checkout, which renders from Shopify's own templates rather than your theme.
Step by step
- 1In the Shopify admin open Online Store, then Themes. Duplicate the live theme before touching anything, so you have a copy to roll back to.
- 2On the live theme open the three dot menu and choose Edit code.
- 3In the Layout folder open theme.liquid.
- 4Scroll to the bottom and paste the tag on its own line immediately before the closing body tag.
- 5Save. Shopify publishes theme edits straight to the live storefront, so there is no separate deploy.
- 6Open the storefront and hard refresh. The launcher appears in the corner within a second or two of the page settling.
What goes wrong on Shopify
The checkout is not your theme
Shopify renders checkout from its own templates, and theme.liquid is not one of them. On plans below Plus you cannot add a script there at all, so the widget is absent from the moment a shopper hits the cart page onward.
This is worth planning around rather than fighting. Put the answers a shopper needs before checkout, on the product and shipping pages, and index your shipping and returns policies so the assistant can answer them there instead.
A theme update deletes your edit
Editing the live theme edits that copy of the theme, not Shopify's record of your customisations. Updating the theme, or switching to a new one, gives you a fresh theme.liquid with no tag in it, and nothing warns you.
The symptom is a widget that was working for months and then silently stops, usually the day after a theme change. Keep a note of the tag with your theme documentation and re-paste it after any theme swap.
Two origins, not one
A Shopify store answers on its myshopify.com address as well as on the domain you connected, and the two are different origins to a browser. If you only allowlist the custom domain, every preview you open through the admin will show nothing and look broken.
Origins to allowlist
These are the origins a Shopify site is typically served from. List every one you want the assistant to answer on, including the ones only you visit.
- https://your-store.myshopify.com
- https://yourdomain.com
- https://www.yourdomain.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 Shopify 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 Shopify that depends on what kind of site this is. These go one level further than this guide.
- For a furniture retailerDelivery surcharges are resolved at checkout, where the theme tag cannot reach, and your dimension files are linked from an address that is not your shop.
- For a pharmacyEvery product is a public page a crawl can reach, so a pharmacy store puts its whole medicines range into the corpus by default. Undo that before you index.
- For a fashion retailerSizes are a dropdown and the size chart is a modal, so the answer to the only question that matters never reaches the crawler as words.
- For a bike shopThe bikes sell on Shopify and the workshop books somewhere else. Two origins, a geometry chart that is an image, and frame sizes as options.
- For a electronics retailerShopify generates a refund policy and nothing about statutory rights, which decides which document wins when a customer reports a fault.
- For a garden centreHours, dogs, the cafe and the compost delivery area are the real questions, and none of them live in the shop. Where to put them instead.
Taking it off again
Open layout/theme.liquid again, delete the line, and save. There is nothing else to uninstall: the tag is the whole install.
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
- Will this slow the store down?
- The tag is deferred, so it never blocks the page from rendering, and only the small launcher loads up front. The conversation panel is fetched the first time somebody opens it. On a Shopify theme already loading several apps, this is not the one that shows up in your speed report.
- Can it tell a shopper where their order is?
- Only if the material it reads contains that. It answers from what you index, so it can explain your dispatch times, your carrier and your tracking process from your policy pages. It does not look up an individual order unless you connect a source that holds order records.
- Does it work on a headless Shopify storefront?
- Yes, but not through theme.liquid, because a headless storefront does not use it. Put the tag in the layout of whatever renders your pages, and allowlist the origin that storefront is served from.
- What should I feed it for a store?
- Shipping and returns policies, the sizing or specification pages, the FAQ, and the collection pages that explain what a range is for. Product descriptions matter less than you expect, because most pre-purchase questions are about delivery and returns.
Keep reading
- 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.
- Install on Magento and Adobe CommerceContent, then Design, then Configuration. Edit the store view, open the Footer section, and use Miscellaneous HTML.
- 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.