Install guide
Installing a chat assistant in a Spring Boot project
The install is one line in the template your pages share. What separates this from editing a file on a content system is that the template is packaged into the artifact when you build, so nothing you change on a running server has any effect until the next release goes out.
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 Spring Boot
src/main/resources/templates, in the shared template your pages decorate or include, immediately before the closing body tag.
Any Spring Boot application that builds pages on the server from templates. An application that serves only JSON to a separate front end needs the tag in that front end instead.
Step by step
- 1Open src/main/resources/templates and identify the template that actually holds the html and body elements for your pages.
- 2Work out which sharing mechanism your project uses. Some projects have each page include a common fragment, others have each page decorate a single template that owns the whole document. The file you want is the one with the body element in it, not the fragment that happens to be named for the footer.
- 3Paste the tag in that file, immediately before the closing body tag.
- 4Rebuild the application. Templates under src/main/resources are packaged into the artifact during the build, so the change does not exist until then.
- 5Redeploy and restart. A running instance keeps serving the pages it was built with.
- 6Load a page and confirm the launcher appears. If it does not, look at the page source first: either the tag is absent, which is a build or deploy problem, or it is present, which makes it an allowlist problem.
What goes wrong on Spring Boot
Editing the file on the server changes nothing
Templates live under src/main/resources and are copied into the packaged artifact when the project is built. Once it is running, the templates it uses are the ones inside that package, not the ones on any disk you can reach. So the instinct carried over from content systems, edit the file and reload, fails silently here: the page comes back exactly as it was.
The full cycle is edit, rebuild, redeploy, restart. It is slower than a paste into an admin screen and it is the reason this install goes through code review like any other change, which on balance is a feature.
The shared template is not always the file you first open
Two arrangements are common and they point in opposite directions. In one, each page pulls in a shared fragment near its own closing body tag. In the other, each page declares that it decorates a single template, and that template owns the document while the page supplies only a content region.
Guessing wrong gives you a tag inside a region that is discarded, or a tag on a fragment only half your pages include. Open two unrelated pages and see how each one connects to the shared file before you paste anything.
Template caching hides the change during local work
The template engine caches compiled templates and the cache is on by default, which is correct for production and confusing locally: you rebuild, the process is still up, and the page keeps coming back without your tag.
Turn the cache off in your development configuration, or use the development tooling that restarts the application for you, then confirm the tag in the page source rather than judging by whether the launcher appeared.
Origins to allowlist
These are the origins a Spring Boot site is typically served from. List every one you want the assistant to answer on, including the ones only you visit.
- http://localhost:8080
- 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 Spring Boot 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 Spring Boot 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 shared template, rebuild, and redeploy. There is nothing in the database and no configuration property to unset.
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
- Which templates directory if my project has more than one?
- The one your template resolver is pointed at, which is src/main/resources/templates unless somebody changed it in your configuration. If the application finds your pages today, it will find your edit.
- Should the tag go in the head instead of the body?
- Either works, because the tag defers and never blocks the page. The end of the body is the better default: it keeps third party markup out of a head that your own metadata and stylesheets already share.
- Does the key belong in application properties?
- It does not have to. The key is a publishable one that ships to every visitor's browser regardless, so putting it in the template is honest about that. Reading it from configuration is still reasonable if you want a different assistant per environment.
- How do I keep it off the actuator endpoints?
- Nothing to do. Those endpoints return JSON and never pass through your templates, so the tag is not on them and cannot be.
Keep reading
- Install on Next.jsapp/layout.tsx in the App Router, or pages/_document.tsx in the Pages Router. Not a client component that can unmount.
- Install on Reactindex.html at the project root for a Vite app, or public/index.html for Create React App. Immediately before the closing body tag.
- Install on Vueindex.html at the project root, after the div the app mounts into and immediately before the closing body tag.
- 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.