DocsInício rápido

Instalar o agente Nodale no seu site

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.

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.

Colar a tag

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

<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.

Content Security Policy

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

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:

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'). 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.

Para agentes de IA: esta página em Markdown