Help · Spree Commerce integration
SuperBot for Spree Commerce
Install the agent on Spree Commerce, ground its answers in your own content, confirm the widget is live, and fix the issues that most often block a launch.
On this page
What SuperBot does on Spree Commerce
Spree Commerce is a Rails codebase you own, so SuperBot goes in the way any script does: in the storefront layout, or through the custom code setting that Spree 5 added to the admin. No gem, no engine, and nothing tied to your Spree or Rails version.
- No gem in your Gemfile, so Spree and Rails upgrades never wait on us.
- Runs in the browser from SuperBot's servers, adding no load to your Rails app or database.
- Works the same on the Rails storefront and on a headless front end.
- Leads and escalations can go to a webhook, so they fit whatever your team has already built.
Before you install
The quality of the first answers depends on what a visitor can already read on your site, so publish your current shipping, returns, and contact information before training the agent. Have your site URL and one test page ready.
- Use the site that should be connected to this SuperBot workspace, not a staging copy.
- Check that your policy and product pages are written for customers rather than internal staff.
- Decide where escalations should land: the SuperBot inbox, Slack, or your existing support process.
- Copy the exact snippet from your SuperBot dashboard so the site ID routes conversations to the right workspace.
Install SuperBot on Spree Commerce
Before </body> in the layout your storefront renders, or in the custom code setting Spree 5 adds to the admin. Deploy as usual and precompile assets if your pipeline requires it.
- Create a free SuperBot workspace and copy the embed snippet.
- Add the URLs of your shipping, returns, and FAQ pages, plus the product pages people ask about.
- On Spree 5, paste the snippet into the admin's custom code setting for the storefront body; on older or heavily customised storefronts, add it before </body> in your storefront layout.
- Deploy through your usual pipeline, precompiling assets if your setup needs it.
- Click from a product page to the cart and back to confirm the launcher stays through Turbo navigation, then review the first answers.
Check that it is live
Open your site in a private window rather than the editor or preview, because most platforms only serve custom code on the published site. The launcher should appear in the lower corner within a second or two.
- Load a real published URL, not an editor preview or a password-protected page.
- Open the launcher and send a question you know the answer to, then confirm the reply cites your own content.
- Check one product or interior page as well as the home page, since templates can differ.
- If you run several languages or store views, check one page in each.
If the widget does not appear
Almost every failed install is one of four things: the change was never published, a cache is still serving the old page, the snippet carries the wrong site ID, or another script is stripping it.
- Spree 5's Rails storefront uses Turbo, which swaps the page body on navigation. Test by clicking between pages, not only by reloading, and email [email protected] if the launcher drops out.
- Headless storefronts, such as a Next.js front end on the Spree API, need the snippet in that front end's root layout rather than in the Rails app.
- A Content-Security-Policy configured in Rails must allow superbotapp.ai for scripts and connections.
- On older Spree versions, a Deface override can inject the snippet without forking the layout view.
- Open your browser console and look for a blocked request to superbotapp.ai, which points at a Content-Security-Policy or an ad blocker.
- Confirm the site ID in the snippet matches the workspace you are looking at in the dashboard.
Train and test before you send traffic
Approve a small, representative set of answers before the widget meets real customers. Test the questions that normally create tickets or stop a purchase, and correct the wording once so every later answer inherits it.
- Start with the ten questions your team answers most often.
- Check that policy answers link to the live page that supports them.
- Add a trained answer for anything the agent gets wrong rather than editing the source page twice.
- Decide what should escalate immediately — refunds, complaints, anything account-specific.
Common questions
Is there a Spree extension to install?
No, and that is deliberate. SuperBot is a client-side snippet, so there is no gem to keep compatible with your Spree or Rails version.
Where does the snippet go on Spree 5?
Either in the admin's custom code setting, which Spree 5 provides for head, body, and checkout snippets, or before </body> in your storefront layout if your team prefers it in code.
Does it work with a headless Spree storefront?
Yes. Add the snippet to the root layout of whatever front end renders your storefront; the widget does not care what serves the HTML.
Will it affect my Rails app's performance?
No. Nothing runs server-side - the widget is loaded by the browser from SuperBot's servers.
Still stuck?
Open the chat on this page and ask — a person reads it. You can also read the Spree Commerce overview for what the agent handles once it is live. Other install guides: Salesforce Commerce Cloud, Shopify, Wix, Squarespace, or every guide.