Add Tidio to your Jekyll site with a Liquid include in your shared layout. You do not need a package for Tidio. Checked with Jekyll 4.4.1.
In this article, you'll learn:
- How to find your Public key
- How to add the widget to Jekyll
- How to check the installation
- How to identify logged-in visitors
- How to hide the widget on some pages
- How to troubleshoot the installation
Find your Public key
Log in to your Tidio panel and go to Settings > Developer > Project data. Click the Public key field to select its value, then copy it.
The Public key is part of the script address that every visitor's browser loads, so you can keep it in front-end code. The private key on the same page is different: never put it in your website.
You'll find the same key inside the installation code in Settings > Live Chat > Installation, under Manual install:
<script src="//code.tidio.co/YOUR_PUBLIC_KEY.js" async></script>
Add the widget to Jekyll
Add your Public key to _config.yml at the site root:
tidio_public_key: YOUR_PUBLIC_KEY
Create _includes/tidio.html with this code. Liquid reads the key from your site configuration:
<script src="https://code.tidio.co/{{ site.tidio_public_key | escape }}.js" async></script>
Include it once, just before </body> in _layouts/default.html. Keep the existing layout content:
{% include tidio.html %}
</body>
If you use a gem-based theme such as Minima, the layout may live in the theme gem rather than your site. Run bundle info --path minima to find it. Copy its _layouts/default.html into your site's _layouts folder, then add the include to that copy. Your local file overrides the theme file, so review future theme changes yourself.
Use layout: default in page front matter, or a theme layout that inherits from it. Pages without that layout do not receive the include. Do not add another Tidio script to posts or individual pages.
Run JEKYLL_ENV=production bundle exec jekyll build and deploy the generated _site directory. Rebuild and redeploy after changing the key. If you configured another destination, deploy that directory instead.
Jekyll produces static pages. With ordinary links, each page opens a new document and loads the widget once. This example does not use a client-side router or a theme extension that replaces the page body.
If an AI coding assistant edits this project for you, give it the prompt from Install Tidio with an AI coding agent.
Check the installation
Open your site in a regular browser window. The chat widget appears in the corner of the page and stays there when you move between pages. Headless and automated browsers may not show the widget, so do not rely on them for this check.
Loading a page with the widget is what activates it. After that, Settings > Live Chat > Installation in your Tidio panel says Chat Widget is installed properly.
On this static site, the next page loads its own widget rather than retaining the previous document's widget.
Identify logged-in visitors
Do not store visitor identity in _config.yml, front matter or generated HTML. Jekyll builds shared files, not a separate page for each signed-in visitor. Get the current visitor from your existing browser authentication code instead.
Replace the original script in _includes/tidio.html with this loader. Call startTidio(user) after authentication resolves on each page. Pass the signed-in visitor's data, or null when signed out. Never pass session tokens.
<script>
function startTidio(user) {
if (document.getElementById('tidio-script')) return;
if (user) {
document.tidioIdentify = {
distinct_id: user.distinct_id,
email: user.email,
name: user.name
};
}
const script = document.createElement('script');
script.id = 'tidio-script';
script.src = 'https://code.tidio.co/{{ site.tidio_public_key | uri_escape }}.js';
script.async = true;
document.body.appendChild(script);
}
</script>
This sets document.tidioIdentify before loading Tidio and can merge conversations for the same visitor. Use the loader instead of the original script, not alongside it.
For a later login on the same page, call setVisitorData after the widget is ready. Replace these example values with data from your authentication code. This updates visitor data but does not merge conversations:
window.tidioChatApi.setVisitorData({
email: 'visitor@example.com',
name: 'Example visitor'
});
After logout, remove identification data before resetting the widget. Run this in your logout handler after the widget is ready:
delete document.tidioIdentify;
window.tidioChatApi?.resetVisitor();
Hide the widget on some pages
Add this code at the start of _includes/tidio.html, before the original script or identification loader. It hides the widget on /checkout and /checkout/, and shows it elsewhere. Each full-page navigation registers a new ready callback.
<script>
function updateTidioVisibility() {
const path = window.location.pathname.replace(/\/+$/, '') || '/';
window.tidioChatApi.display(path !== '/checkout');
}
if (window.tidioChatApi) {
window.tidioChatApi.on('ready', updateTidioVisibility);
} else {
document.addEventListener('tidioChat-ready', updateTidioVisibility);
}
</script>
If you publish beneath a path such as /store, compare against /store/checkout instead. The browser pathname includes that prefix.
Hiding the widget does not stop Flows from triggering. To load the widget only on a list of addresses instead, see Show the widget only on specific pages.
Troubleshooting
- If a page has no widget, check its front matter and layout inheritance. The final layout must include
tidio.html. - If your theme has no local layout file, copy the layout from the theme gem before editing it. Do not edit the installed gem.
- If the published site still uses an old key, rebuild and deploy the output again.
- If the widget loads twice, remove duplicate includes and any older Tidio installation from the theme.
- If your theme replaces the body during navigation, disable that navigation extension for these pages and use ordinary links with full page loads.
- If a browser blocks the script, check its console and your content security policy. See Tidio's content security policy requirements.
