DocsAPI JavaScript

API JavaScript: abrir o agente Nodale a partir do seu código

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.

Depois de a tag estar instalada, a sua página pode enviar-lhe comandos através de uma única função, nodale(). Há dois comandos: open e consent. A tag não expõe nenhum outro método e não envia nenhum evento à sua página.

A fila de comandos

A tag define window.nodale quando é executada. Para chamar um comando antes de a tag ter carregado, cole este stub por cima dela. Os comandos esperam numa fila até a tag estar pronta:

<script>
  window.nodale = window.nodale || function(){(window.nodale.q = window.nodale.q || []).push(arguments)}
</script>
<script src="https://tag.nodale.app/v1/tag.js" data-workspace="YOUR_WORKSPACE_ID" async></script>

Mantenha o ||. Um script que mais tarde atribua window.nodale sem ele remove o comando da tag, e as chamadas seguintes não chegam a lado nenhum.

nodale('open')

Abre o agente a partir do seu próprio código, por exemplo a partir do seu próprio botão ou depois de o seu próprio formulário ser enviado.

nodale('open')

nodale('open', {
  email: 'sam@acme.io',
  context: { 'Contactos por mês': '1500' }
})

A chamada inicia uma conversa escrita na janela de diálogo do agente. O microfone não é pedido: espera pelo visitante.

Opções

Opção Tipo O que faz
email string O e-mail do visitante, quando a sua página já o conhece. O visitante é identificado antes da saudação do agente.
context object O que o visitante já lhe disse, em pares de etiqueta e resposta. O agente recebe-o quando a conversa começa. Fica registado na conversa e nunca é mostrado ao visitante.

Ambas são opcionais. A tag verifica o argumento antes de qualquer coisa sair da página:

  • O argumento é nada, ou um objeto simples sem outra chave além de email e context. Qualquer outra coisa e nada abre.
  • email é uma string de 1 a 254 caracteres, depois de retirados os espaços nas extremidades. Caso contrário é descartado, e o agente abre na mesma. A tag não avalia o endereço: é o servidor que decide se o aceita.
  • context contém 20 respostas no máximo. Uma etiqueta tem de 1 a 60 caracteres, uma resposta é uma string de 300 caracteres no máximo, e uma etiqueta é usada uma só vez. Os espaços nas extremidades das etiquetas e das respostas são retirados, e uma resposta vazia é ignorada. Se uma regra for quebrada, o contexto inteiro é descartado, nunca cortado, e o agente abre na mesma sem ele.

nodale('open') nunca lança exceções e devolve undefined.

Onde funciona

  • Apenas na barra e na apresentação hidden. Com a apresentação em botão, com um <div data-nodale-agent> inline, e numa página onde o agente não é mostrado (uma regra de página, ou uma parte dos visitantes), a chamada não faz nada. Se usar open, mantenha a parte dos visitantes desligada, ou a chamada não fará nada para alguns visitantes.
  • Antes de a tag ter carregado, através do stub acima. Só o último open em fila é reproduzido, uma vez.
  • Uma conversa. O widget inicia uma conversa no máximo e guarda o primeiro e-mail e o primeiro contexto que recebeu. Um open durante uma conversa, ou depois de uma ter terminado, apenas mostra a janela de diálogo.
  • Quando o agente pede primeiro o e-mail, a chamada mostra esse passo, e o seu e-mail e o seu contexto são enviados quando o visitante o submete.

A partir de um botão

<button type="button" onclick="nodale('open')">Fazer uma pergunta</button>

Depois do seu próprio formulário

form.addEventListener('submit', function () {
  nodale('open', {
    email: form.elements.email.value,
    context: {
      'Dimensão da empresa': form.elements.size.value,
      'O que pretende fazer': form.elements.message.value
    }
  })
})

A apresentação hidden

hidden é uma apresentação do workspace, ao lado da barra e do botão. Com ela, nada é mostrado até a sua página chamar nodale('open').

  • A página continua totalmente utilizável. A frame do agente está montada mas invisível, e não recebe nenhum clique.
  • Depois de aberta, é a barra. Fechar a janela de diálogo volta à barra e mantém a conversa. A barra fica então presente durante o resto do separador.
  • O separador lembra-se. Uma página seguinte do seu site, no mesmo separador, mostra a barra de imediato, para que o visitante reencontre a conversa. A tag guarda isto em sessionStorage, numa chave que não contém nenhum identificador. Um novo separador começa oculto.
  • Testada apenas em browsers Chromium. O Safari e o Firefox ainda não estão cobertos pelos nossos testes de browser: um browser que abranda as frames invisíveis pode responder a open mais tarde.

nodale('consent')

Indica à tag se o visitante aceitou o rastreio de visitas. Use-o quando o seu site não tem um banner de cookies que a tag consiga ler, ou quando gere o consentimento por si.

nodale('consent', 'granted')
nodale('consent', 'revoked')
  • Só conta quando o rastreio de visitas está ligado no seu workspace. O rastreio está desligado por predefinição, e o agente é montado em ambos os casos.
  • O rastreio começa recusado. Nada é pedido e nenhum cookie é escrito antes de uma autorização. Com revoked, a tag para e elimina o seu cookie.
  • Prevalece sobre qualquer banner. Depois de a sua página o ter chamado, a tag segue a sua chamada e ignora o que um banner diz.
  • O Global Privacy Control prevalece sobre tudo. Um browser que o envia fica recusado durante toda a visita, seja o que for que a sua página chame.

Sem a chamada, a tag lê a resposta na ferramenta de consentimento da página: Axeptio, Didomi, Cookiebot, OneTrust, Usercentrics, CookieYes, tarteaucitron.js, WP Consent API, Complianz, o banner da HubSpot, iubenda, Osano, Cookie-Script, CookieFirst, Klaro, Shopify, Wix, IAB TCF v2.2, IAB GPP e Google Consent Mode v2. Algumas precisam de que a Nodale seja declarada como fornecedor ou como serviço: o guia do rastreio de visitas na aplicação indica a configuração de cada uma.

Depuração

A tag nunca lança exceções na sua página. Explica-se em console.debug, em linhas começadas por nodale tag:. Ative o nível verbose da consola do seu browser para as ver.

Linha O que aconteceu
open refused O argumento não é um objeto simples, ou contém outra chave além de email e context.
open email dropped email não é uma string de 1 a 254 caracteres.
open context dropped context quebra uma das suas regras.
open needs the floating or hidden display O workspace usa a apresentação em botão, ou a página monta o agente inline.
open: agent not on this page Uma regra de página ou a parte dos visitantes mantém o agente fora desta página.
open not acknowledged O widget não respondeu em 30 segundos.

Para agentes de IA: esta página em Markdown