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:

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 Project data page with the Public key field, masked private key and Visit widget SDK documentation button visible

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>
Settings > Live Chat > Installation with Manual install selected, the code snippet visible, and the Copy to clipboard button.

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.

Silent walkthrough. A demo Jekyll site with the Tidio chat widget in the corner. Each page loads the widget, and the Checkout page hides it.

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.

Further reading