gatsby-ssr.js or gatsby-browser.js?

gatsby-ssr.js in almost every case, because it puts the tag in the generated HTML before any of your own code runs. gatsby-browser.js is the right choice only when you want to add the widget conditionally at runtime, for example after a consent decision, and then you create the element yourself and can call the destroy method later.

Why is nothing showing after I edited gatsby-ssr.js?

Two causes, in this order. The development server was not restarted, so the file was never read again, or you checked the development server rather than a built site. Rebuild, serve the output, and view source.

No. This is one script element and a file that exists for exactly this purpose. A plugin would only wrap the same call.

Does the tag end up in every generated page?

Yes. onRenderBody runs for each page Gatsby generates, so the tag lands at the end of the body on all of them, including pages created later from data.

Install guide

Installing a chat assistant in a Gatsby project

Gatsby builds its HTML rather than serving a file you wrote, so the tag is added through the server rendering API instead of pasted into a template. It is a few lines of code, and nearly every way this goes wrong is about the build rather than the code.

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 Gatsby

gatsby-ssr.js at the project root, inside onRenderBody, using setPostBodyComponents.

Any Gatsby site. gatsby-ssr.js and gatsby-browser.js either already exist at the root or can be created empty there, and neither needs a plugin or a configuration change.

Step by step

1Create or open gatsby-ssr.js at the project root, beside gatsby-config.js.
2Export onRenderBody, taking setPostBodyComponents from its argument.
3Call setPostBodyComponents with an array holding one script element: src pointing at the loader, defer, the data-key prop carrying your publishable key, and a key prop, because React asks for one on array children.
4Stop and restart the development server. Changes to gatsby-ssr.js are read when the process starts and are not picked up by hot reloading.
5Run a build and serve the output locally, since gatsby-ssr.js runs during HTML generation and that is the step you are actually testing.
6View source on the served page and confirm the tag sits at the end of the body with the key intact.
7Allowlist the origins you develop and deploy on before you expect a launcher anywhere.

What goes wrong on Gatsby

gatsby-ssr.js is not hot reloaded

Edit it while the development server is running and nothing at all happens: no tag, no error, no rebuild notice. The file is read once when the process starts.

Stop the process and start it again. This one reliably costs people twenty minutes of re-reading code that was correct the whole time.

React needs a key, and data-key is not it

setPostBodyComponents takes an array of React elements, so React wants a key prop on each one and warns in your build output if you leave it off. That key is bookkeeping and is discarded before the HTML is written.

The data-key attribute is an entirely different thing, is emitted verbatim into the document, and is the one the loader reads. Set both, and do not mistake the warning about the first for a problem with the second.

Three origins, not two

The development server and the local preview of a built site listen on different local ports, and your deployed site answers on your domain. All three are separate origins to a browser and to the allowlist.

The usual sequence is build, serve the output locally to confirm the tag, then check the deployed site. Add whichever local origins you actually use, or expect a refused origin in the console on each of them.

Origins to allowlist

These are the origins a Gatsby site is typically served from. List every one you want the assistant to answer on, including the ones only you visit.

http://localhost:8000
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.

Loader behaviour
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 Gatsby 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 Gatsby that depends on what kind of site this is. These go one level further than this guide.

For a universityThe page comes from the last build and the material came from a crawl at another moment. A moved deadline is what exposes the gap.

Taking it off again

Delete the onRenderBody export from gatsby-ssr.js, or the whole file if that is all it held, and run a build. A previously deployed build keeps serving the tag until the new one replaces it.

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

gatsby-ssr.js or gatsby-browser.js?: gatsby-ssr.js in almost every case, because it puts the tag in the generated HTML before any of your own code runs. gatsby-browser.js is the right choice only when you want to add the widget conditionally at runtime, for example after a consent decision, and then you create the element yourself and can call the destroy method later.
Why is nothing showing after I edited gatsby-ssr.js?: Two causes, in this order. The development server was not restarted, so the file was never read again, or you checked the development server rather than a built site. Rebuild, serve the output, and view source.
Do I need a plugin?: No. This is one script element and a file that exists for exactly this purpose. A plugin would only wrap the same call.
Does the tag end up in every generated page?: Yes. onRenderBody runs for each page Gatsby generates, so the tag lands at the end of the body on all of them, including pages created later from data.

Keep reading

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.

Start free See what it does