Install guide
Installing a chat assistant on a Craft CMS build
Craft is the rare content system where the templates are simply yours. There is no theme to update and no marketplace copy sitting underneath your edits, so the usual worry on this kind of page does not apply. The two things that do bite are template caching and the fact that one Craft install can be several sites.
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 Craft CMS
The templates folder at the root of your project, in the layout that your other templates extend, immediately before the closing body tag.
Any Craft site where you can commit a template change. Craft Solo and Craft Pro are identical here, because templates are project files rather than a product feature.
Step by step
- 1Open the templates folder at the root of your project. Everything Craft displays comes from here.
- 2Find the layout your templates extend. Look at the top of an entry template for its extends tag: the file it names is the one you want, whatever your team called it.
- 3Scroll to the closing body tag in that layout and paste the tag immediately above it.
- 4Check that the paste is not inside a cache tag. If the surrounding markup is wrapped in one, put your tag outside the block so it is never served from a stored copy.
- 5Commit the change and deploy the way you normally deploy. Craft templates are project files, so this goes through your usual review and release, not through the control panel.
- 6After deploying, open Utilities, then Caches, and clear the caches. Then load the site and confirm the launcher appears.
What goes wrong on Craft CMS
Nothing is going to overwrite this, which changes what you watch for
On most content systems the standing risk is an update replacing the file you edited. Craft has no theme layer at all, so that risk does not exist: your layout is your code, in your repository, and the only thing that changes it is a commit.
The failure mode moves rather than disappearing. It becomes a deploy that shipped the wrong branch, or a template change that landed in one environment and not another. When the widget is missing on a Craft site, look at what was actually deployed rather than at anything in the control panel.
A cache tag around the layout freezes the markup you just changed
Craft's cache tag stores the output of the section it wraps and serves that stored copy on later requests, keyed by URL. If your layout wraps its footer region in one, the tag you just pasted is inside stored output and the change is invisible until the stored copy expires or is cleared.
The tell is a page source that still shows the old markup after a successful deploy. Clear the caches from Utilities, then Caches, and confirm. Then move the tag outside the cached block so that a key change later does not need the same dance.
One install can be several sites sharing one layout
Craft's multi site feature runs distinct sites, each with its own base address and its own content, from a single install and frequently from a single set of templates. A tag pasted into a shared layout therefore installs the same assistant on all of them at once.
That is fine for a set of language variants of one brand and wrong for two unrelated brands. Where the sites genuinely differ, branch on the current site inside the layout and use a different key for each, so a visitor gets an assistant that read the content of the site they are actually on.
Origins to allowlist
These are the origins a Craft CMS site is typically served from. List every one you want the assistant to answer on, including the ones only you visit.
- https://yoursite.ddev.site
- 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 Craft CMS 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 Craft CMS that depends on what kind of site this is. These go one level further than this guide.
Taking it off again
Delete the line from the layout, commit, deploy, and clear the caches from Utilities, then Caches. There is nothing in the database and nothing in the control panel to undo.
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
- Does it need a plugin?
- No. This is one line of markup in a template file you already own. A plugin would add an update to track and a settings screen to learn for something that is a single paste.
- Should the tag go in the head instead?
- The end of the body is the better habit, though the tag defers so both behave the same. Keeping the head to what your site genuinely needs early makes the head easier to audit when something else goes wrong later.
- Can I keep it off the control panel?
- It is already off it. The control panel is served by Craft itself and does not use your templates, so a tag in your layout never appears there. Only the front end of your site is affected.
- What material suits a Craft site?
- Whatever the site publishes, crawled from its own address. Craft builds are usually bespoke, so the useful sources are your own entry types: the service pages, the help section, the policy pages. Let the crawl read them as published rather than trying to feed it entry data.
Keep reading
- Install on WordPressA code snippets plugin, or a small plugin of your own, hooking wp_footer. Not Appearance, then the theme file editor.
- Install on GhostSettings, then Code injection, then the Site Footer box. The alternative is default.hbs in a custom theme.
- Install on DrupalA small custom module attaching a library, an asset injection contributed module, or html.html.twig in a custom theme. Not a custom block.
- 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.