DocsAPI de JavaScript

API de JavaScript: abre el agente de Nodale desde tu código

Los comandos nodale() que una página puede llamar: abrir el agente desde tu botón o formulario, pasar un correo y contexto, comunicar el consentimiento.

Una vez instalada la etiqueta, tu página puede enviarle comandos con una sola función, nodale(). Hay dos comandos: open y consent. La etiqueta no expone ningún otro método y no envía ningún evento a tu página.

La cola de comandos

La etiqueta define window.nodale cuando se ejecuta. Para llamar a un comando antes de que la etiqueta se haya cargado, pega este stub encima de ella. Los comandos esperan en una cola hasta que la etiqueta está lista:

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

Conserva el ||. Un script que más tarde asigna window.nodale sin él elimina el comando de la etiqueta, y las llamadas posteriores no llegan a ninguna parte.

nodale('open')

Abre el agente desde tu propio código, por ejemplo desde tu propio botón o cuando se ha enviado tu propio formulario.

nodale('open')

nodale('open', {
  email: 'sam@acme.io',
  context: { 'Contactos al mes': '1500' }
})

La llamada inicia una conversación escrita en el diálogo del agente. No se pide el micrófono: espera al visitante.

Opciones

Opción Tipo Qué hace
email string El correo del visitante, cuando tu página ya lo conoce. Queda identificado antes del saludo del agente.
context object Lo que el visitante ya te ha dicho, en pares de nombre y respuesta. El agente lo recibe cuando empieza la conversación. Se registra en la conversación y nunca se muestra al visitante.

Las dos son opcionales. La etiqueta comprueba el argumento antes de que nada salga de la página:

  • El argumento es nada, o un objeto simple sin más claves que email y context. Con cualquier otra cosa, no se abre nada.
  • email es una cadena de 1 a 254 caracteres una vez recortada. Si no, se descarta, y el agente se abre igualmente. La etiqueta no juzga la dirección: el servidor decide si la acepta.
  • context contiene 20 respuestas como máximo. Un nombre tiene de 1 a 60 caracteres, una respuesta es una cadena de 300 caracteres como máximo, y un nombre se usa una sola vez. Los nombres y las respuestas se recortan, y una respuesta vacía se omite. Si se incumple una regla, se descarta el contexto entero, nunca se corta, y el agente se abre igualmente sin él.

nodale('open') nunca lanza una excepción y devuelve undefined.

Dónde funciona

  • Solo en la barra y en la visualización hidden. Con la visualización de botón, con un <div data-nodale-agent> insertado en la página, y en una página donde el agente no se muestra (una regla de página, o una parte de los visitantes), la llamada no hace nada. Si usas open, deja desactivada la parte de los visitantes, o la llamada no hará nada para algunos visitantes.
  • Antes de que la etiqueta se haya cargado, con el stub de arriba. Solo se reproduce el último open en cola, una vez.
  • Una sola conversación. El widget inicia una conversación como máximo y conserva el primer correo y el primer contexto que recibió. Un open durante una conversación, o después de que haya terminado, solo muestra el diálogo.
  • Cuando el agente pide primero el correo, la llamada muestra ese paso, y tu correo y tu contexto se envían cuando el visitante lo envía.

Desde un botón

<button type="button" onclick="nodale('open')">Haz una pregunta</button>

Después de tu propio formulario

form.addEventListener('submit', function () {
  nodale('open', {
    email: form.elements.email.value,
    context: {
      'Tamaño de la empresa': form.elements.size.value,
      'Qué quiere hacer': form.elements.message.value
    }
  })
})

La visualización hidden

hidden es una visualización del espacio de trabajo, junto a la barra y el botón. Con ella, no se muestra nada hasta que tu página llama a nodale('open').

  • La página sigue siendo totalmente utilizable. El marco del agente está montado pero es invisible, y no recibe ningún clic.
  • Una vez abierto, es la barra. Cerrar el diálogo vuelve a la barra y conserva la conversación. La barra se queda después durante el resto de la pestaña.
  • La pestaña lo recuerda. Una página posterior de tu sitio en la misma pestaña muestra la barra de inmediato, para que el visitante encuentre de nuevo la conversación. La etiqueta lo guarda en sessionStorage, en una clave que no contiene ningún identificador. Una pestaña nueva empieza oculta.
  • Probado solo en navegadores Chromium. Safari y Firefox todavía no están cubiertos por nuestras pruebas de navegador: un navegador que ralentiza los marcos invisibles puede responder a open más tarde.

nodale('consent')

Indica a la etiqueta si el visitante ha aceptado la medición de visitas. Úsalo cuando tu sitio no tiene un banner de cookies que la etiqueta pueda leer, o cuando gestionas tú el consentimiento.

nodale('consent', 'granted')
nodale('consent', 'revoked')
  • Solo cuenta cuando la medición de visitas está activada en tu espacio de trabajo. La medición está desactivada por defecto, y el agente se monta en ambos casos.
  • La medición empieza denegada. No se pide nada y no se escribe ninguna cookie antes de una aceptación. Con revoked, la etiqueta se detiene y elimina su cookie.
  • Está por encima de cualquier banner. Una vez que tu página lo ha llamado, la etiqueta sigue tu llamada e ignora lo que diga un banner.
  • Global Privacy Control gana a todo. Un navegador que lo envía sigue denegado durante toda la visita, llame a lo que llame tu página.

Sin la llamada, la etiqueta lee la respuesta de la herramienta de consentimiento de la página: Axeptio, Didomi, Cookiebot, OneTrust, Usercentrics, CookieYes, tarteaucitron.js, WP Consent API, Complianz, el banner de HubSpot, iubenda, Osano, Cookie-Script, CookieFirst, Klaro, Shopify, Wix, IAB TCF v2.2, IAB GPP y Google Consent Mode v2. Algunas necesitan que Nodale esté declarado como proveedor o como servicio: la guía de medición de visitas de la aplicación da la configuración de cada una.

Depuración

La etiqueta nunca lanza una excepción en tu página. Se explica en console.debug, en líneas que empiezan por nodale tag:. Activa el nivel detallado de la consola de tu navegador para verlas.

Línea Qué ha pasado
open refused El argumento no es un objeto simple, o contiene otra clave que email y context.
open email dropped email no es una cadena de 1 a 254 caracteres.
open context dropped context incumple una de sus reglas.
open needs the floating or hidden display El espacio de trabajo usa la visualización de botón, o la página monta el agente insertado en ella.
open: agent not on this page Una regla de página o la parte de los visitantes deja el agente fuera de esta página.
open not acknowledged El widget no respondió en 30 segundos.

Para agentes de IA: esta página en Markdown

Que cada visita cuente.