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
emailecontext. 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.contextconté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 usaropen, 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
openem 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
opendurante 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
openmais 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. |