DocsQuick start

Install the Nodale agent on your website

One script tag puts the Nodale agent on your site. Where to paste it, what your site must allow, and how to check that it runs.

The Nodale agent runs on your website through one script tag. This page is for the developer who installs it. To drive the agent from your own code, read the JavaScript API.

Before you start

Two things must be true in your Nodale workspace, or the tag does nothing:

  1. The agent is published and online. The Install tab of your agent shows the line to paste only once the agent is published and its deployment is live.
  2. Your site is declared. Add its address under Allowed websites, in the same tab. The rules are below.

Paste the tag

<script src="https://tag.nodale.app/v1/tag.js" data-workspace="YOUR_WORKSPACE_ID" async></script>

Copy the line from the Install tab: it already holds your workspace id. Paste it on every page you want the agent on, in the <head> or just before </body>.

  • One line per workspace, pasted once. The tag reads your workspace’s current configuration on every page load. Publishing a new version of the agent or changing its display reaches every page without anybody touching the site.
  • It runs once per page. Pasting it twice, or loading it from a tag manager as well as the page, is harmless: the second copy sees the first and stops.
  • Single-page apps are followed. The agent stays mounted when your app navigates with pushState, replaceState or popstate.
  • Language. The widget takes the language of the page from <html lang>. To set it yourself, add data-lang to the tag, for instance data-lang="fr".
  • One workspace per page. A page runs a single tag.

Allowed websites

The tag answers only on the sites your workspace declares. On any other site nothing is added to the page.

  • An entry is an origin, scheme and port included: https://www.example.com. It has no path.
  • https only, except localhost and 127.0.0.1 for local work.
  • https://*.example.com covers every subdomain, at any depth, but not example.com itself. Declare the apex as its own entry.
  • 20 sites at most per workspace.
  • A change needs no publish. A removed site stops showing the agent on the visitor’s next page load.

Where the agent shows

The display is a setting of the Install tab, not of the tag:

  • Floating bar: a bar at the bottom of the page.
  • Button: a launcher in the bottom-right corner, which opens the widget on click.

To place the agent inside your own layout instead, add this element where you want it. The widget mounts in the first one it finds, in the flow of the page, whatever the display setting:

<div data-nodale-agent></div>

A third display, hidden, keeps the agent out of sight until your code opens it. It is described with the JavaScript API.

Content Security Policy

A site that sends a Content Security Policy adds exactly three sources to the directives it already has:

script-src  https://tag.nodale.app;
frame-src   https://nodale.app;
connect-src https://nodale.app
  • No 'unsafe-inline', no 'unsafe-eval', no wildcard and no nonce: the tag is an external script with no inline code.
  • No style-src, img-src, font-src or media-src entry: everything the widget renders loads inside its own frame.
  • require-trusted-types-for 'script' is compatible.
  • frame-src falls back to child-src, then to default-src.

Microphone

Voice needs the microphone, and the browser asks for it only when the visitor presses the microphone button, never on page load.

If your site sends a Permissions-Policy header, it must not deny the microphone to the widget. Either leave microphone out, or allow the Nodale origin:

Permissions-Policy: microphone=(self "https://nodale.app")

A consent tool that blocks scripts automatically must exempt the Nodale tag, or classify it in the category your workspace chose for visit tracking. A blocked tag cannot show the agent.

Visit tracking is off by default. When you turn it on, page views are counted only once the visitor agreed. The tag reads the answer from your cookie banner; a site without one reports it with nodale('consent'). The agent itself is mounted either way.

Check the install

Open the Install tab. The Tag on your sites card lists each declared site as Detected or Not detected, with the last time the tag was seen. Check again reads the home page of each site.

If the agent does not show on a page, check in this order:

  1. The site is in Allowed websites, with the exact scheme and subdomain.
  2. The agent is published and its deployment is online.
  3. The page’s Content Security Policy holds the three sources above.
  4. No consent tool blocks the script.

The tag never writes an error on your page. It leaves one console.debug line starting with nodale tag: when it stops.

For AI agents: this page in Markdown

Make every visit count.