DocsInicio rápido

Instala el agente de Nodale en tu web

Una sola etiqueta script pone el agente de Nodale en tu web. Dónde pegarla, qué debe permitir tu web y cómo comprobar que funciona.

El agente de Nodale funciona en tu web con una sola etiqueta script. Esta página es para el desarrollador que la instala. Para controlar el agente desde tu propio código, lee la API de JavaScript.

Antes de empezar

Dos cosas deben cumplirse en tu espacio de trabajo de Nodale, o la etiqueta no hace nada:

  1. El agente está publicado y en línea. La pestaña Instalación de tu agente muestra la línea que hay que pegar solo cuando el agente está publicado y su despliegue está en línea.
  2. Tu sitio está declarado. Añade su dirección en Sitios permitidos, en la misma pestaña. Las reglas están más abajo.

Pega la etiqueta

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

Copia la línea desde la pestaña Instalación: ya contiene el identificador de tu espacio de trabajo. Pégala en cada página donde quieras el agente, en el <head> o justo antes de </body>.

  • Una línea por espacio de trabajo, pegada una sola vez. La etiqueta lee la configuración actual de tu espacio de trabajo en cada carga de página. Publicar una nueva versión del agente o cambiar su visualización llega a todas las páginas sin que nadie toque el sitio.
  • Se ejecuta una vez por página. Pegarla dos veces, o cargarla desde un gestor de etiquetas además de la página, no causa ningún problema: la segunda copia ve la primera y se detiene.
  • Sigue las aplicaciones de una sola página. El agente permanece montado cuando tu aplicación navega con pushState, replaceState o popstate.
  • Idioma. El widget toma el idioma de la página de <html lang>. Para fijarlo tú, añade data-lang a la etiqueta, por ejemplo data-lang="fr".
  • Un espacio de trabajo por página. Una página ejecuta una sola etiqueta.

Sitios permitidos

La etiqueta responde solo en los sitios que declara tu espacio de trabajo. En cualquier otro sitio no se añade nada a la página.

  • Una entrada es un origen, con esquema y puerto incluidos: https://www.example.com. No lleva ruta.
  • Solo https, salvo localhost y 127.0.0.1 para el trabajo en local.
  • https://*.example.com cubre todos los subdominios, a cualquier profundidad, pero no example.com. Declara el dominio raíz como una entrada propia.
  • 20 sitios como máximo por espacio de trabajo.
  • Un cambio no necesita publicación. Un sitio quitado deja de mostrar el agente en la siguiente carga de página del visitante.

Dónde se muestra el agente

La visualización es un ajuste de la pestaña Instalación, no de la etiqueta:

  • Barra flotante: una barra flotante en la parte inferior de la página.
  • Botón: un botón en la esquina inferior derecha, que abre el widget al hacer clic.

Para colocar el agente dentro de tu propio diseño, añade este elemento donde lo quieras. El widget se monta en el primero que encuentra, en el flujo de la página, sea cual sea el ajuste de visualización:

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

Una tercera visualización, hidden, mantiene el agente fuera de la vista hasta que tu código lo abre. Se describe con la API de JavaScript.

Content Security Policy

Un sitio que envía una Content Security Policy añade exactamente tres fuentes a las directivas que ya tiene:

script-src  https://tag.nodale.app;
frame-src   https://nodale.app;
connect-src https://nodale.app
  • Ni 'unsafe-inline', ni 'unsafe-eval', ni comodín, ni nonce: la etiqueta es un script externo sin código en línea.
  • Ninguna entrada style-src, img-src, font-src ni media-src: todo lo que renderiza el widget se carga dentro de su propio marco.
  • require-trusted-types-for 'script' es compatible.
  • frame-src recurre a child-src y después a default-src.

Micrófono

La voz necesita el micrófono, y el navegador lo pide solo cuando el visitante pulsa el botón del micrófono, nunca al cargar la página.

Si tu sitio envía una cabecera Permissions-Policy, no debe denegar el micrófono al widget. Deja microphone fuera, o permite el origen de Nodale:

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

Banners de cookies

Una herramienta de consentimiento que bloquea scripts automáticamente debe eximir la etiqueta de Nodale, o clasificarla en la categoría que tu espacio de trabajo eligió para la medición de visitas. Una etiqueta bloqueada no puede mostrar el agente.

La medición de visitas está desactivada por defecto. Cuando la activas, las páginas vistas se cuentan solo cuando el visitante ha aceptado. La etiqueta lee la respuesta de tu banner de cookies; un sitio que no tiene banner la comunica con nodale('consent'). El agente se monta en ambos casos.

Comprueba la instalación

Abre la pestaña Instalación. La tarjeta Etiqueta en tus sitios muestra cada sitio declarado como Detectada o No detectada, con la última vez que se vio la etiqueta. Volver a comprobar lee la página de inicio de cada sitio.

Si el agente no se muestra en una página, comprueba en este orden:

  1. El sitio está en Sitios permitidos, con el esquema y el subdominio exactos.
  2. El agente está publicado y su despliegue está en línea.
  3. La Content Security Policy de la página contiene las tres fuentes de arriba.
  4. Ninguna herramienta de consentimiento bloquea el script.

La etiqueta nunca escribe un error en tu página. Deja una línea console.debug que empieza por nodale tag: cuando se detiene.

Para agentes de IA: esta página en Markdown

Que cada visita cuente.