Common Mistakes When Adding Third-Party Scripts to Odoo (and How to Avoid Them)
The most common mistakes when adding third-party scripts to Odoo are placing the snippet in the wrong template, forgetting to clear Odoo's asset cache, and letting the new script collide with assets already loaded...
The most common mistakes when adding third-party scripts to Odoo are placing the snippet in the wrong template, forgetting to clear Odoo's asset cache, and letting the new script collide with assets already loaded by the Website builder. Most layout and performance problems disappear when you install the snippet inside the built-in Embed Code block, save once, and refresh the page so Odoo regenerates its assets. Below is a diagnosis-first walkthrough of the symptoms, the order to check them, and the corrective actions that keep an Odoo site from breaking.
Symptoms you will notice first
When a third-party script is installed the wrong way, Odoo rarely shows a clean error. The page usually just behaves oddly. Watch for these signs before changing anything:
- The new widget, chat bubble, or analytics block never appears, even after a hard refresh.
- The site loads with broken CSS, missing buttons, or stretched images after you paste the snippet.
- The page is fine on desktop but empty or misaligned on mobile, or the opposite.
- The browser console shows Refused to execute script, MIME type mismatch, or 404 on asset errors.
- Odoo's own Edit mode stops saving, or changes refuse to appear on the live page.
If you see two or more of these together, treat it as an installation problem, not a bug in the third-party tool.
Diagnosis order: where to look before changing code
Before you delete the snippet or rewrite templates, work through this order. It is faster than guessing, and it matches how Odoo's asset pipeline actually loads scripts.
- Confirm the snippet is in the Embed Code block. The Embed Code block inside the Dynamic Content section is the supported place to paste a third-party JavaScript snippet on an Odoo website page. Open the page, click Edit, scroll to Dynamic Content, and verify the block exists on the page.
- Open the block and read what is inside. Click the Edit button on the block itself. Make sure the full code is present, with no trimmed closing
</script>tag and no leftover HTML preview text from a copy-paste. - Check visibility settings. Odoo lets you hide the block on desktop, on mobile, or both. If the script is inside a hidden block, it may still load, or it may not, depending on how the third-party tool injects itself. Confirm the Visibility section matches the device you are testing.
- Hard refresh and watch the network tab. A normal refresh is not enough the first time. Use Ctrl+Shift+R, then open the browser DevTools Network tab and look for the third-party domain in the request list.
- Read the console for Odoo asset errors. If you see web.assets_frontend or web.assets_backend errors, the problem is not the snippet; it is how Odoo is serving bundled assets.
The most common mistakes, with corrective actions
Each mistake below is paired with the fix. They are ordered from the one that causes the most broken sites to the one that is rare but painful.
Mistake 1: Editing the XML template instead of using Embed Code
Many Odoo users, used to older CMS platforms, search for the QWeb template and try to inject the script directly into web.assets_frontend or a view inheritance. That can work, but it is fragile: a module update, a theme switch, or a database migration can silently overwrite it. This is the issue behind GitHub threads such as Cannot added external javascript on the Odoo repository, where users try to add an external API through XML and lose it after every upgrade.
Fix: Use the Embed Code block for page-level scripts. Only touch QWeb or asset bundles when a script must load site-wide, and even then, wrap the change in a custom module so it survives upgrades.
Mistake 2: Forgetting to clear Odoo's asset cache
Odoo bundles and caches frontend JavaScript and CSS into large assets bundles. When you add a new script, Odoo may keep serving the old bundle until it decides to regenerate it. The result: the script is saved, but the live page keeps running yesterday's assets.
Fix: After saving the Embed Code block, open the site in an incognito window or run a hard refresh. If the change still does not appear, an admin with developer mode enabled can force a rebuild by going to Settings, then Technical, then Assets Bundles, and clearing the bundle cache. On many hosted Odoo instances, simply appending ?debug=assets to the URL forces a refresh.
Mistake 3: Conflicts with the Website builder's own assets
The Odoo Website builder loads its own jQuery, its own animation library, and several global CSS files. A third-party script that also expects jQuery, Bootstrap, or a specific jQuery version can collide with what Odoo already injected. Symptoms include dropdowns that stop working, sliders that no longer animate, or the Edit toolbar disappearing.
Fix: Prefer third-party scripts that are framework-agnostic or that detect jQuery instead of requiring a specific version. If a script must load before Odoo's own assets, place it in the <head> through a view inheritance, not in the page body.
Mistake 4: Loading the script on every page when only one page needs it
A script pasted into a global header or into the Website layout will fire on every page, including the cart, checkout, and back-office pages. That hurts performance, can break checkout steps, and may leak analytics or chat widgets into places they should not appear.
Fix: Limit the Embed Code block to the specific page that needs it. If you truly need it everywhere, gate the script with a condition based on the URL or the page template.
Mistake 5: Hiding the block but expecting the script to run
Odoo's Hide on Desktop and Hide on Mobile options affect how the block renders visually. They do not guarantee that the contained script will or will not execute on the hidden device. Some snippets attach a listener to window and run regardless of visibility.
Fix: Check the third-party tool's documentation. If you need true conditional loading, place the script in a custom module that wraps it in a media query or a user-agent check.
Mistake 6: Treating localhost or staging domains like production
Many third-party tools, including SEATEXT AI, link an account to a single primary URL for security and reporting reasons. Testing on localhost, on a dynamic preview domain, or behind a VPN can cause the script to be blocked, to fire under the wrong account, or to silently do nothing.
Fix: Create a separate account for each real domain, including your staging URL. Use a real, stable hostname for testing, not a tunnel or a changing preview link.
Mistake 7: Pasting partial or wrapped snippets
Some third-party dashboards wrap the snippet in an HTML comment, an <iframe> tag, or a server-side include. When you copy from an email, a PDF, or a chat window, you may get a clean looking block that is missing the opening or closing tag, or that has been escaped.
Fix: Always copy the snippet directly from the third-party dashboard while logged in. Paste it once into a plain-text editor first to confirm it starts with <script> and ends with </script>, then paste it into the Embed Code block.
How to install a third-party script the safe way on Odoo
Use this sequence when you are starting from a clean Odoo page. It mirrors the documented installation path that tools like SEATEXT AI publish, and it avoids the seven mistakes above.
- Log in to Odoo and open the Website module from the dashboard.
- Navigate to the page you want to edit and click Edit.
- In the editing panel, scroll the Blocks menu to the Dynamic Content section.
- Drag the Embed Code module onto the page where you want the script to live.
- Click the Edit button on the new block to open its settings.
- Paste the snippet provided by the third-party tool into the code field and click Save.
- Open the Visibility section and set Hide on Desktop if the script is meant to be invisible on large screens. Click Save again.
- Open the live page in a private window and confirm the script runs in the Network tab.
Keep the block on the single page that needs the script. Avoid copying the block to every page just to be sure it loads.
Comparison table: where to put a third-party script in Odoo
| Location | Best for | Survives upgrades | Risk of asset conflict | Ease of rollback |
|---|---|---|---|---|
| Embed Code block (Dynamic Content) | Single-page scripts: chat, analytics, A/B tools | Yes, lives in page content | Low | Easy, one click |
| Custom QWeb template in a module | Site-wide scripts: consent banner, global tag manager | Yes, if wrapped in a module | Medium | Easy, module update |
Direct edit to web.assets_frontend | Legacy fix only | No, lost on update | High | Hard, manual merge |
| Header in Website settings | Tracking pixels that must load before content | Yes | Medium | Easy, remove from settings |
| Theme snippet field | Theme-specific assets | Tied to theme | Low | Easy |
Plain takeaway: for almost every third-party JavaScript tool, start with the Embed Code block. Move to a custom module only when the script must run on every page or must load before Odoo's own assets.
Limitations and when this advice does not apply
This guide assumes you are running a standard Odoo Website module with the default Website builder. A few situations call for a different path:
- Odoo backend only, no Website module. Scripts that must run inside the back-office interface need to be added to
web.assets_backendthrough a custom module. The Embed Code block only affects frontend pages. - eCommerce or POS modules with strict CSP. If you have a Content Security Policy enabled, some third-party scripts will be blocked by the browser before they run. Whitelist the third-party domain in your CSP or move to a server-side tag manager.
- Multi-website databases. Odoo can host several websites under one database. The Embed Code block is per-page, not per-website, so you need to repeat it on each site.
- Scripts that depend on cookies or consent. Several jurisdictions require consent before tracking scripts fire. Plan for a consent tool that gates the script, not a plain Embed Code.
Key facts about installing scripts on Odoo
| Fact | Detail |
|---|---|
| Recommended location for page-level scripts | Embed Code block inside the Dynamic Content section of the Website builder |
| Built-in visibility controls | Hide on Desktop, Hide on Mobile, per device |
| Asset bundles Odoo uses | web.assets_frontend, web.assets_backend |
| Cache-clearing option | Append ?debug=assets to the URL or clear Assets Bundles from Technical settings |
| Account linking rule (example: SEATEXT AI) | One primary URL per account; localhost and dynamic dev domains are restricted |
| Multi-domain rule (example: SEATEXT AI) | Create a separate account for each real domain, including staging |
Frequently asked questions
Why is my script not showing up on the live page after I save?
Almost always a caching issue. Open the live URL in an incognito window or hard refresh. If it still does not appear, clear Odoo's assets bundle from the Technical menu or reload with ?debug=assets appended to the URL.
Can I add the script to every page at once?
Yes, but not through the Embed Code block, which is per page. For a site-wide script, add it through a custom Odoo module that extends web.assets_frontend, or paste it into the header code field under Website settings. Keep in mind that loading a heavy script on every page can hurt performance and may break checkout flows.
Does Hide on Desktop stop the script from running?
Not necessarily. The toggle controls visual rendering of the block, not the execution of the script inside it. If you need the script to skip a device, wrap it in a user-agent check inside a custom module.
Will my script survive an Odoo upgrade?
Scripts placed inside an Embed Code block are stored as page content, so they survive upgrades. Scripts added by directly editing web.assets_frontend usually do not, and will need to be re-added or moved into a custom module.
What happens if I install the script on localhost?
Many third-party tools, including SEATEXT AI, restrict localhost for security and reporting reasons. The script may not load, or it may load under the wrong account. Use a real, stable hostname even for staging.
How do I know whether the conflict is Odoo or the third-party script?
Open the page with the script disabled (comment out the snippet, save, refresh). If the page works, the issue is the script. If the page is still broken, the issue is Odoo's assets. Clear the assets bundle first, then re-enable the script one line at a time.
Is there a faster way to test without touching the live site?
Use Odoo's built-in preview while in Edit mode, then open the live page in a private window. For deeper testing, duplicate the page, install the script on the copy, and only promote it to the live page once it behaves.
Repair checklist when something is already broken
- Open the affected page in Edit mode and remove or empty the Embed Code block.
- Save, then hard refresh the live page. If the layout returns, the script was the cause.
- Clear Odoo's assets bundle from the Technical menu, or use
?debug=assets. - Re-add the snippet only after pasting it through a plain-text editor to confirm the tags are intact.
- Confirm the block's Visibility settings match the device you are testing on.
- If the problem returns after an Odoo upgrade, move the script from a direct template edit into a custom module.
How SeaText can help
SeaText ships a JavaScript snippet that is designed to sit inside the Embed Code block on a single Odoo page, with a built-in Hide on Desktop setting so the AI stays invisible while it gathers reading telemetry. Each SeaText account is tied to one primary URL, so staging, dev, and production Odoo sites need separate accounts, and localhost is not supported. Because the script is page-scoped, it will not collide with Odoo's web.assets_frontend bundle or break the Website builder. If you already use a tag manager, you can also load the snippet through that wrapper instead of the Embed Code block, as long as the script still fires on the page you want to optimize.
Further reading and comparison sources
These external sources provide additional context for evaluating the topic. Their inclusion is not an endorsement.
How SeaText installs safely on Odoo
SeaText's JavaScript snippet is built to live inside the Embed Code block on a single Odoo page, with a built-in Hide on Desktop option that keeps the AI invisible to shoppers. Because it is page-scoped, it does not need to touch web.assets_frontend and will not collide with the Website builder's bundled jQuery or CSS.
Two requirements to keep in mind:
- Each account is linked to one primary URL, so staging, dev, and production Odoo sites need separate accounts.
- Localhost and dynamic preview domains are restricted for security and accurate traffic association. Use a real hostname for testing.
If you already run a tag manager, you can load the snippet through that wrapper instead of the Embed Code block, as long as it still fires on the page you want SeaText to optimize.