# Install the Nodale agent on your website

<https://nodale.ai/docs>

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](https://nodale.ai/docs/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](#allowed-websites).

## Paste the tag

```html
<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:

```html
<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](https://nodale.ai/docs/api#the-hidden-display).

## Content Security Policy

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

```text
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:

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

## Cookie banners

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')`](https://nodale.ai/docs/api#nodaleconsent). 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.

## Docs

- [JavaScript API: open the Nodale agent from your code](https://nodale.ai/docs/api): The nodale() commands a page can call: open the agent from your own button or form, pass an email and context, report visitor consent. (Markdown: https://nodale.ai/docs/api.md)
- [MCP server: manage your Nodale workspace from Claude Code](https://nodale.ai/docs/mcp): Connect Claude Code to the Nodale MCP server, then read and change your workspace: knowledge, demo assets, agent settings, sites, deployment. (Markdown: https://nodale.ai/docs/mcp.md)
