# Installa l'agente Nodale sul tuo sito web

<https://nodale.ai/it/docs>

Un solo tag script porta l'agente Nodale sul tuo sito. Dove incollarlo, cosa deve consentire il sito e come verificare che funzioni.

L'agente Nodale gira sul tuo sito web tramite un solo tag script. Questa pagina è per lo sviluppatore che lo installa. Per pilotare l'agente dal tuo codice, leggi l'[API JavaScript](https://nodale.ai/it/docs/api).

## Prima di iniziare

Nel tuo workspace Nodale devono essere vere due cose, altrimenti il tag non fa nulla:

1. **L'agente è pubblicato e online.** La scheda Install del tuo agente mostra la riga da incollare solo quando l'agente è pubblicato e il suo deployment è attivo.
2. **Il tuo sito è dichiarato.** Aggiungi il suo indirizzo in **Allowed websites**, nella stessa scheda. Le regole sono [qui sotto](#siti-autorizzati).

## Incolla il tag

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

Copia la riga dalla scheda Install: contiene già l'id del tuo workspace. Incollala in ogni pagina in cui vuoi l'agente, nell'`<head>` o subito prima di `</body>`.

- **Una riga per workspace, incollata una volta.** Il tag legge la configurazione corrente del tuo workspace a ogni caricamento di pagina. Pubblicare una nuova versione dell'agente o cambiarne la visualizzazione arriva su ogni pagina senza che nessuno tocchi il sito.
- **Gira una volta per pagina.** Incollarlo due volte, o caricarlo da un tag manager oltre che dalla pagina, non crea problemi: la seconda copia vede la prima e si ferma.
- **Le single-page app sono seguite.** L'agente resta montato quando la tua app naviga con `pushState`, `replaceState` o `popstate`.
- **Lingua.** Il widget prende la lingua della pagina da `<html lang>`. Per impostarla tu, aggiungi `data-lang` al tag, per esempio `data-lang="fr"`.
- **Un workspace per pagina.** Una pagina esegue un solo tag.

## Siti autorizzati

Il tag risponde solo sui siti che il tuo workspace dichiara. Su qualsiasi altro sito non viene aggiunto nulla alla pagina.

- Una voce è un'origine, schema e porta inclusi: `https://www.example.com`. Non ha percorso.
- Solo `https`, tranne `localhost` e `127.0.0.1` per il lavoro in locale.
- `https://*.example.com` copre ogni sottodominio, a qualsiasi profondità, ma non `example.com` stesso. Dichiara l'apex come voce a sé.
- 20 siti al massimo per workspace.
- Una modifica non richiede pubblicazione. Un sito rimosso smette di mostrare l'agente al successivo caricamento di pagina del visitatore.

## Dove si vede l'agente

La visualizzazione è un'impostazione della scheda Install, non del tag:

- **Floating bar**: una barra flottante in fondo alla pagina.
- **Button**: un pulsante di avvio nell'angolo in basso a destra, che apre il widget al clic.

Per collocare invece l'agente dentro il tuo layout, aggiungi questo elemento dove lo vuoi. Il widget si monta nel primo che trova, nel flusso della pagina, qualunque sia l'impostazione di visualizzazione:

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

Una terza visualizzazione, `hidden`, tiene l'agente nascosto finché il tuo codice non lo apre. È descritta con l'[API JavaScript](https://nodale.ai/it/docs/api#la-visualizzazione-hidden).

## Content Security Policy

Un sito che invia una Content Security Policy aggiunge esattamente tre sorgenti alle direttive che ha già:

```text
script-src  https://tag.nodale.app;
frame-src   https://nodale.app;
connect-src https://nodale.app
```

- Nessun `'unsafe-inline'`, nessun `'unsafe-eval'`, nessun carattere jolly e nessun nonce: il tag è uno script esterno senza codice inline.
- Nessuna voce `style-src`, `img-src`, `font-src` o `media-src`: tutto ciò che il widget disegna si carica dentro il suo frame.
- `require-trusted-types-for 'script'` è compatibile.
- `frame-src` ripiega su `child-src`, poi su `default-src`.

## Microfono

La voce ha bisogno del microfono, e il browser lo chiede solo quando il visitatore preme il pulsante del microfono, mai al caricamento della pagina.

Se il tuo sito invia un header `Permissions-Policy`, non deve negare il microfono al widget. Lascia fuori `microphone`, oppure consenti l'origine Nodale:

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

## Banner dei cookie

Uno strumento di consenso che blocca gli script in automatico deve esentare il tag Nodale, oppure classificarlo nella categoria che il tuo workspace ha scelto per il tracciamento delle visite. Un tag bloccato non può mostrare l'agente.

Il tracciamento delle visite è disattivato per impostazione predefinita. Quando lo attivi, le pagine viste sono contate solo dopo che il visitatore ha accettato. Il tag legge la risposta dal tuo banner dei cookie; un sito che non ne ha uno la segnala con [`nodale('consent')`](https://nodale.ai/it/docs/api#nodaleconsent). L'agente viene montato in entrambi i casi.

## Verifica l'installazione

Apri la scheda Install. La card **Tag on your sites** elenca ogni sito dichiarato come **Detected** o **Not detected**, con l'ultima volta in cui il tag è stato visto. **Check again** legge la home page di ogni sito.

Se l'agente non si vede in una pagina, controlla in quest'ordine:

1. Il sito è in **Allowed websites**, con lo schema e il sottodominio esatti.
2. L'agente è pubblicato e il suo deployment è online.
3. La Content Security Policy della pagina contiene le tre sorgenti indicate sopra.
4. Nessuno strumento di consenso blocca lo script.

Il tag non scrive mai un errore sulla tua pagina. Quando si ferma lascia una riga `console.debug` che inizia con `nodale tag:`.

## Docs

- [API JavaScript: apri l'agente Nodale dal tuo codice](https://nodale.ai/it/docs/api): I comandi nodale() che una pagina può chiamare: apri l'agente da un tuo pulsante o form, passa email e contesto, segnala il consenso del visitatore. (Markdown: https://nodale.ai/it/docs/api.md)
- [Server MCP: gestisci il tuo workspace Nodale da Claude Code](https://nodale.ai/it/docs/mcp): Collega Claude Code al server MCP di Nodale, poi leggi e modifica il workspace: knowledge, asset demo, impostazioni dell'agente, siti, deployment. (Markdown: https://nodale.ai/it/docs/mcp.md)
