Prueba Omnifox gratis 7 días gratis. Sin tarjeta de crédito.
Guías

Chat en una web HTML, React o Next.js: instalar el widget en una SPA

Cómo instalar un chat web en HTML, React, Next.js, Vue o Angular sin duplicar el script, con rutas del cliente, usuarios identificados y modo oscuro.

September 06, 2026
Chat en una web HTML, React o Next.js: instalar el widget en una SPA
En este artículo

    Instalar un chat en una web HTML, React o Next.js es una sola línea de script, pero en una SPA esa línea puede cargarse dos veces, perder los cambios de ruta o chocar con la política de seguridad del sitio. Si eres quien mantiene el frontend, ya sabes que "pégalo antes de </body>" no describe bien un layout de Next.js con App Router ni un componente de Vue que se monta y desmonta.

    Este artículo va dirigido a desarrolladores: cómo cargar el widget una sola vez en cada framework, qué pasa cuando la ruta cambia sin recarga, qué permitir en tu CSP, cómo identificar al usuario logueado con una firma HMAC desde tu backend y cómo respetar el tema oscuro del sistema.

    La línea base: HTML estático

    En un sitio estático (HTML plano, Astro, Hugo, Jekyll, Eleventy) el script va al final del documento, antes de la etiqueta de cierre del body. La clave data-widget-key se copia desde el panel de Omnifox en Canales → tu canal de chat web → Instalar.

    <script src="https://omnifox.io/widget/loader.js" data-widget-key="TU_CLAVE" async></script>
    

    El atributo async evita que el loader bloquee el render. Si tu generador estático usa una plantilla base o layout, ponlo ahí una vez y no en cada página.

    React y Next.js: cargar el widget una sola vez

    El error clásico en React es meter el script en un componente que se renderiza en cada página: el loader se inyecta varias veces, aparecen dos botones flotantes o el widget se reinicia con cada navegación. La regla: el script vive en el layout raíz y en ningún otro lugar.

    En Next.js con App Router, usa next/script en app/layout.tsx con la estrategia afterInteractive, que carga el script después de la hidratación:

    // app/layout.tsx
    import Script from "next/script";
    
    export default function RootLayout({ children }) {
      return (
        <html lang="es">
          <body>
            {children}
            <Script
              src="https://omnifox.io/widget/loader.js"
              data-widget-key={process.env.NEXT_PUBLIC_OMNIFOX_WIDGET_KEY}
              strategy="afterInteractive"
            />
          </body>
        </html>
      );
    }
    

    Con Pages Router, el mismo componente Script va en pages/_app.tsx. En una app de React con Vite o Create React App sin framework, lo más sencillo es dejar la etiqueta en index.html, que se sirve una sola vez y no depende del árbol de componentes.

    Vue, Nuxt y Angular

    Framework Dónde va el script Nota
    HTML estático Antes de </body> en el layout base Una sola vez por plantilla
    React (Vite/CRA) index.html Fuera del árbol de React
    Next.js App Router app/layout.tsx con next/script, afterInteractive Nunca en page.tsx
    Next.js Pages Router pages/_app.tsx con next/script Igual que arriba
    Vue (Vite) index.html Evita onMounted en componentes de página
    Nuxt nuxt.config → app.head.script con async: true Se inyecta en todas las rutas
    Angular src/index.html antes de </body> No lo cargues desde un servicio por ruta

    Si necesitas inyectarlo desde código (por ejemplo, tras aceptar cookies), comprueba antes que window.Omnifox no exista y que no haya ya una etiqueta con ese src; así evitas el widget duplicado cuando el gestor de consentimiento repite su callback.

    Cambios de ruta sin recarga: qué ve el widget

    En una SPA la URL cambia con pushState y nunca hay una carga de página completa. Eso importa por dos motivos:

    • Los disparadores por URL que configuras en el panel (contiene, empieza con, exacta) siguen aplicando cuando el usuario navega de /precios a /demo sin recargar: el widget escucha la navegación del cliente y evalúa las condiciones con la nueva ruta.
    • Las condiciones de tiempo en página y porcentaje de scroll se reinician con cada ruta, así que un disparador de "30 segundos en /precios" no se dispara porque el usuario llevaba 30 segundos en la home.

    Como el widget no se desmonta entre rutas, la conversación abierta se mantiene mientras el usuario recorre la app; si cierra la pestaña y vuelve en el mismo navegador, la retoma dentro de la gracia de reapertura configurada.

    Content Security Policy y dominios permitidos

    Si tu sitio publica una cabecera Content-Security-Policy estricta, el loader será bloqueado hasta que lo permitas. Como mínimo, agrega el origen del widget a script-src. Si además restringes connect-src o frame-src, la consola del navegador te dirá qué directiva está bloqueando qué recurso: ajusta solo esa, sin abrir 'unsafe-inline' para todo.

    Content-Security-Policy: script-src 'self' https://omnifox.io; ...
    

    El panel de Omnifox muestra en qué dominios está instalado cada canal de chat web: si trabajas con localhost, un dominio de preview y producción, verás los tres y sabrás si el despliegue llegó a producción sin abrir el sitio a mano.

    Identificar al usuario logueado con firma HMAC

    Cuando el visitante ya inició sesión en tu app, no tiene sentido pedirle nombre y correo en el pre-chat. Omnifox permite identificarlo con window.Omnifox.identify, pasando un identificador externo y un hash que tu backend calcula con el secreto del canal. Así nadie puede hacerse pasar por otro usuario cambiando el id en el navegador.

    Backend (Node.js, cualquier framework):

    import { createHmac } from "node:crypto";
    
    export function omnifoxUserHash(userId) {
      return createHmac("sha256", process.env.OMNIFOX_CHANNEL_SECRET)
        .update(String(userId))
        .digest("hex");
    }
    

    Frontend, después de que el loader esté disponible:

    window.Omnifox.identify({
      user_id: "usr_48213",
      user_hash: "<hash calculado en el servidor>",
    });
    

    El contacto se crea o se actualiza en Omnifox por ese identificador externo, y la conversación queda en la ficha correcta del CRM aunque el usuario escriba desde otro dispositivo con la misma cuenta. Tres reglas para no romperlo:

    1. El secreto del canal nunca sale del servidor; el frontend solo recibe el hash.
    2. Llama a identify una vez por sesión de usuario, por ejemplo al montar el layout autenticado, no en cada render.
    3. Si el usuario cierra sesión, no vuelvas a llamar a identify con datos vacíos; simplemente deja que el widget siga como visitante anónimo.

    Para un SaaS de facturación en Colombia esto significa que el asesor abre la conversación y ya ve la ficha del cliente con su historial, sin preguntar "¿con qué correo te registraste?". Si ese usuario luego escribe por WhatsApp con el celular de su perfil, todo cae en la misma ficha. La guía sobre chat en vivo para SaaS profundiza en qué hacer con esa información.

    Tema oscuro, apariencia y analítica sin código extra

    El widget tiene modo claro, oscuro o automático, que sigue prefers-color-scheme del sistema del visitante. Si tu app ya implementa tema oscuro, deja el widget en automático y ajusta el color principal y de acento desde el panel; cuando necesitas más control (alinear el radio de los bordes con tu sistema de diseño), el panel acepta CSS personalizado y permite elegir tipografía, forma del botón y posición. La interfaz del widget se muestra en español, inglés o portugués según el idioma del navegador, sin que tengas que pasarle el locale de tu app.

    Eventos para GA4

    El widget emite widget_loaded, widget_opened, conversation_started y message_sent al dataLayer y a gtag si existen en la página. En una SPA con GA4 ya configurado no necesitas escuchar eventos ni escribir un wrapper: llegan solos y puedes marcar conversation_started como conversión. El artículo sobre GA4 y el chat de tu web con dataLayer muestra cómo montar el embudo.

    Preguntas frecuentes

    ¿Dónde pongo el script del chat en Next.js?

    En el layout raíz (app/layout.tsx con App Router o pages/_app.tsx con Pages Router) usando next/script con strategy="afterInteractive". Nunca en una página individual, para que se cargue una sola vez.

    ¿Los disparadores por URL funcionan en una SPA sin recargar?

    Sí, el widget escucha la navegación del cliente y evalúa las condiciones de URL con cada cambio de ruta; el tiempo en página y el scroll se reinician con la nueva ruta.

    ¿Cómo evito que el widget se cargue dos veces?

    Cárgalo solo desde el layout raíz o index.html, y si lo inyectas por código, verifica antes que window.Omnifox no exista y que no haya otra etiqueta con el mismo src.

    ¿Qué necesita identify para ser seguro?

    Un user_id y un user_hash calculado en tu backend con HMAC y el secreto del canal. El secreto nunca debe estar en el frontend.

    Instálalo en el layout y pruébalo en preview

    Un script en el layout raíz, la CSP ajustada y identify firmado desde el servidor: con eso el chat web funciona igual en HTML, React, Next.js, Vue o Angular. Crea tu cuenta con la prueba gratis de 7 días, copia la clave del canal y revisa la configuración de apariencia, disparadores y analítica en la página del chat web de Omnifox.

    ¿Listo para probarlo en tu negocio?

    Reúne WhatsApp, Instagram, Messenger, email y llamadas en una sola bandeja, y deja que la IA dé la primera respuesta. Configúralo hoy mismo.

    7 días gratis. Sin tarjeta de crédito.

    Comentarios (0)

    Todavía no hay comentarios. Sé el primero en compartir tu opinión.

    Deja un comentario

    Tu email nunca se publica. Los comentarios se moderan antes de aparecer.

    Soporta markdown. El HTML se elimina.

    Leer más

    Escríbenos por WhatsApp