# Instalar o agente Nodale no seu site

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

Uma tag de script coloca o agente Nodale no seu site. Onde a colar, o que o seu site tem de permitir e como verificar que funciona.

O agente Nodale funciona no seu site através de uma única tag de script. Esta página destina-se ao programador que a instala. Para comandar o agente a partir do seu próprio código, leia a [API JavaScript](https://nodale.ai/pt/docs/api).

## Antes de começar

Duas condições têm de estar cumpridas no seu workspace Nodale, caso contrário a tag não faz nada:

1. **O agente está publicado e online.** O separador Install do seu agente só mostra a linha a colar depois de o agente estar publicado e de a sua implementação estar ativa.
2. **O seu site está declarado.** Adicione o endereço em **Allowed websites**, no mesmo separador. As regras estão [abaixo](#sites-autorizados).

## Colar a tag

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

Copie a linha a partir do separador Install: já contém o identificador do seu workspace. Cole-a em todas as páginas onde quer o agente, no `<head>` ou imediatamente antes de `</body>`.

- **Uma linha por workspace, colada uma vez.** A tag lê a configuração atual do seu workspace a cada carregamento de página. Publicar uma nova versão do agente ou alterar a sua apresentação chega a todas as páginas sem que ninguém toque no site.
- **Executa uma vez por página.** Colá-la duas vezes, ou carregá-la a partir de um gestor de tags além da página, é inofensivo: a segunda cópia vê a primeira e para.
- **As single-page apps são acompanhadas.** O agente permanece montado quando a sua aplicação navega com `pushState`, `replaceState` ou `popstate`.
- **Língua.** O widget usa a língua da página, lida em `<html lang>`. Para a definir por si, adicione `data-lang` à tag, por exemplo `data-lang="fr"`.
- **Um workspace por página.** Uma página executa uma única tag.

## Sites autorizados

A tag só responde nos sites que o seu workspace declara. Em qualquer outro site, nada é adicionado à página.

- Uma entrada é uma origem, com esquema e porta incluídos: `https://www.example.com`. Não tem caminho.
- Apenas `https`, exceto `localhost` e `127.0.0.1` para trabalho local.
- `https://*.example.com` cobre todos os subdomínios, a qualquer profundidade, mas não o próprio `example.com`. Declare o domínio raiz (apex) como uma entrada à parte.
- 20 sites no máximo por workspace.
- Uma alteração não exige publicação. Um site removido deixa de mostrar o agente no carregamento de página seguinte do visitante.

## Onde o agente é mostrado

A apresentação é uma definição do separador Install, não da tag:

- **Floating bar**: uma barra flutuante na parte inferior da página.
- **Button**: um botão de abertura no canto inferior direito, que abre o widget ao clique.

Para colocar o agente dentro do seu próprio layout, adicione este elemento onde o quiser. O widget é montado no primeiro que encontrar, no fluxo da página, seja qual for a definição de apresentação:

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

Uma terceira apresentação, `hidden`, mantém o agente fora de vista até o seu código o abrir. Está descrita na [API JavaScript](https://nodale.ai/pt/docs/api#a-apresentação-hidden).

## Content Security Policy

Um site que envia uma Content Security Policy adiciona exatamente três origens às diretivas que já tem:

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

- Sem `'unsafe-inline'`, sem `'unsafe-eval'`, sem wildcard e sem nonce: a tag é um script externo sem código inline.
- Sem entrada `style-src`, `img-src`, `font-src` ou `media-src`: tudo o que o widget apresenta é carregado dentro da sua própria frame.
- `require-trusted-types-for 'script'` é compatível.
- `frame-src` recorre a `child-src` e, depois, a `default-src`.

## Microfone

A voz precisa do microfone, e o browser só o pede quando o visitante carrega no botão do microfone, nunca no carregamento da página.

Se o seu site envia um cabeçalho `Permissions-Policy`, este não pode negar o microfone ao widget. Deixe `microphone` de fora ou autorize a origem da Nodale:

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

## Banners de cookies

Uma ferramenta de consentimento que bloqueia scripts automaticamente tem de isentar a tag da Nodale, ou classificá-la na categoria que o seu workspace escolheu para o rastreio de visitas. Uma tag bloqueada não consegue mostrar o agente.

O rastreio de visitas está desligado por predefinição. Quando o liga, as páginas vistas só são contadas depois de o visitante ter aceitado. A tag lê a resposta no seu banner de cookies; um site sem banner comunica-a com [`nodale('consent')`](https://nodale.ai/pt/docs/api#nodaleconsent). O agente é montado em ambos os casos.

## Verificar a instalação

Abra o separador Install. O cartão **Tag on your sites** lista cada site declarado como **Detected** ou **Not detected**, com a última vez em que a tag foi vista. **Check again** lê a página inicial de cada site.

Se o agente não for mostrado numa página, verifique por esta ordem:

1. O site está em **Allowed websites**, com o esquema e o subdomínio exatos.
2. O agente está publicado e a sua implementação está online.
3. A Content Security Policy da página contém as três origens acima.
4. Nenhuma ferramenta de consentimento bloqueia o script.

A tag nunca escreve um erro na sua página. Deixa uma linha `console.debug` começada por `nodale tag:` quando para.

## Docs

- [API JavaScript: abrir o agente Nodale a partir do seu código](https://nodale.ai/pt/docs/api): Os comandos nodale() que uma página pode chamar: abrir o agente a partir do seu botão ou formulário, passar um e-mail e contexto, comunicar o consentimento. (Markdown: https://nodale.ai/pt/docs/api.md)
- [Servidor MCP: gerir o seu workspace Nodale no Claude Code](https://nodale.ai/pt/docs/mcp): Ligue o Claude Code ao servidor MCP da Nodale e leia ou altere o seu workspace: conhecimento, assets de demo, definições do agente, sites, implementação. (Markdown: https://nodale.ai/pt/docs/mcp.md)
