Cómo integrar los widgets de comentarios de UserVoice en Webflow

El widget de comentarios de UserVoice es un SDK de JavaScript que solo funciona en el navegador. Se carga de forma asíncrona desde el subdominio de tu cuenta y se comunica directamente con UserVoice desde el navegador del visitante; por eso, añadirlo a un sitio de Webflow es básicamente copiar y pegar.

La parte de copiar y pegar es fácil. El verdadero trabajo empieza cuando el widget necesita saber quién es el visitante. Pasar los rasgos del usuario es una llamada sencilla, pero acceder a un foro privado o a un portal restringido, y mostrar que los comentarios provienen de un autor verificado, requiere un token firmado en un servidor con una clave secreta. Un sitio estático de Webflow no tiene dónde firmarlo.

Este es el camino que sigue una solicitud, desde la integración hasta los servidores de UserVoice:

Esa conexión directa entre el navegador y UserVoice es la base anónima. Para firmar el token, esta guía añade una aplicación de Webflow Cloud, que se ejecuta en el borde como un Cloudflare Worker y puede almacenar la clave secreta y firmar con Web Crypto.

Lo construiremos en seis pasos: primero, un widget anónimo en un sitio de Webflow publicado; luego, usuarios identificados; y finalmente, un token firmado que abre foros privados y verifica la identidad. Una nota antes de empezar: el widget en la aplicación es una función de pago de UserVoice Discovery, y la empresa ahora se posiciona como una plataforma de inteligencia de clientes, aunque el widget sigue activo y documentado.

¿Qué necesitas para integrar widgets de comentarios de UserVoice en Webflow?

Necesitas una cuenta de UserVoice con un plan que incluya el widget en la aplicación, un sitio de Webflow donde integrarlo y, para la identidad verificada, una aplicación de Webflow Cloud que pueda firmar un token en el servidor en lugar de en el navegador.

Aquí tienes todo lo que debes tener listo antes de pegar una sola línea de código:

• Una cuenta de UserVoice con el widget en la aplicación habilitado, disponible en Discovery Pro y Premium
• Tu subdominio del widget y la clave del SDK de JavaScript, desde la Consola de administración > Configuración > Widgets
• Un sitio de Webflow donde puedas editar código personalizado y publicar
• Para la identidad verificada, un proyecto de Webflow Cloud que ejecute Next.js y tu clave secreta SSO de UserVoice
• Node.js 22 o superior localmente, si vas a crear la aplicación de Webflow Cloud

Con la cuenta, las claves y el acceso al sitio listos, la construcción comienza con el widget anónimo y luego añade la capa de identidad.

6 pasos para integrar widgets de comentarios de UserVoice en Webflow

La integración de UserVoice en Webflow se divide en dos partes. Los tres primeros pasos colocan un widget anónimo en tu sitio publicado mediante código personalizado. Los tres últimos identifican al visitante y prueban esa identidad con un token firmado por el servidor.

Cada paso a continuación incluye el código y la ubicación exacta de la consola de donde proviene.

1. Activa el widget y copia tu código de inserción

El widget es un SDK de navegador que UserVoice genera por cuenta, por lo que no puedes escribir la URL del cargador a mano. Contiene tanto tu subdominio como una clave de SDK de JavaScript que vincula el widget a tu espacio de trabajo.

En la consola de administración de UserVoice, abre Ajustes > Widgets. Configura la experiencia inicial en Publicar idea, o en NPS si tienes ese complemento, y luego elige una posición de activación y un color de acento. UserVoice ensambla el fragmento en el paso 2 de esa pantalla.

El código generado se ve así, con tu propio subdominio y clave ya incluidos:

UserVoice = window.UserVoice || [];
(() => {
  const uv = document.createElement('script');
  uv.type = 'text/javascript';
  uv.async = true;
  // Replace {subdomain} and {JS key} with the values from Settings > Widgets.
  uv.src = 'https://{subdomain}.uservoice.com/widget_environment/{JS key}.js';
  const s = document.getElementsByTagName('script')[0];
  s.parentNode.insertBefore(uv, s);
})();

UserVoice.push(['set', {
  accent_color: '#458dd6',
  trigger_color: 'white',
  forum_id: '209871', // Optional: defaults to your account's default forum
}]);
UserVoice.push(['addTrigger', { mode: 'post_idea', trigger_position: 'bottom-right' }]);

La clave del SDK de JavaScript se encuentra en la sección de configuración avanzada de la misma pantalla de Widgets. Copia todo el bloque. Con el cargador en mano, ya tienes exactamente lo que UserVoice espera, y el siguiente paso es llevarlo a Webflow.

2. Añade el widget al código personalizado de tu sitio en Webflow

Un sitio de Webflow no tiene un paso de compilación para scripts de terceros, así que el widget se añade a través del Código personalizado, donde Webflow lo inyecta por ti en cada página publicada.

La ubicación en el pie de página es importante aquí. El fragmento se inserta antes del primer elemento de script de la página, por lo que necesita que el documento esté mayormente analizado antes de ejecutarse; el código del encabezado puede dispararse demasiado pronto y no encontrar ese ancla.

Pega el cargador en el campo de Código del pie de página envuelto en una etiqueta script, de esta manera:

<!-- Webflow: Site Settings > Custom Code > Footer Code -->
<script>
  UserVoice = window.UserVoice || [];
  (function () {
    var uv = document.createElement('script');
    uv.type = 'text/javascript';
    uv.async = true;
    uv.src = 'https://{subdomain}.uservoice.com/widget_environment/{JS key}.js';
    var s = document.getElementsByTagName('script')[0];
    s.parentNode.insertBefore(uv, s);
  })();
</script>

Guarda y publica el sitio. El código personalizado solo se envía en las páginas publicadas, por lo que el widget no aparecerá en el lienzo del Diseñador ni en una vista previa de prueba hasta que lo publiques. Una vez hecho, el activador de comentarios aparecerá en la esquina de cada página activa.

3. Coloca el widget en línea o mediante un activador personalizado

El activador predeterminado es una pestaña flotante, pero la mayoría de los diseños de Webflow prefieren que los comentarios estén vinculados a un botón específico o integrados dentro de una sección. UserVoice lee dos atributos HTML para ello, documentados en su guía de personalización de widgets.

Añade un elemento de inserción (Embed) en el Diseñador y pega uno de estos:

<!-- Inline embed: drops the Post Idea widget into a section -->
<div data-uv-embed="post_idea" data-uv-height="325px" data-uv-width="100%"></div>

<!-- Custom trigger: any element opens the widget on click -->
<a href="/contact" data-uv-trigger>Send feedback</a>

El div renderiza el widget en línea, mientras que convierte cualquier elemento en un lanzador. Si prefieres configurar los activadores en JavaScript, utiliza un selector y un modo en su lugar.data-uv-embeddata-uv-triggeraddTrigger

Esto vincula el widget a un botón que ya existe en tu diseño:

UserVoice.push(['addTrigger', '#feedback-button', {
  mode: 'post_idea',
}]);

Publica de nuevo y haz clic para probar. En este punto, el widget recopila ideas de cualquier visitante sin saber quiénes son, algo que cambiaremos en el siguiente paso.

4. Pasa los rasgos del usuario y de la cuenta con identify()

Es difícil actuar sobre una idea anónima. Cuando un visitante ha iniciado sesión, adjunta su correo electrónico, nombre y cuenta para que los comentarios lleguen con contexto en lugar de con un perfil vacío.identify()

Llamalo después del cargador, usando los datos que tu aplicación ya posee. El correo electrónico y el ID de usuario son siempre obligatorios, mientras que el objeto de cuenta es opcional; su ID y nombre solo se vuelven obligatorios cuando lo incluyes.

Envía los rasgos justo después de que el widget se cargue:

UserVoice.push(['identify', {
  email: 'john.doe@example.com', // Required: the user's email address
  id: 123,                       // Required: unique id from your app
  name: 'John Doe',
  type: 'Owner',                 // Segment users by type
  account: {
    id: 456,                     // Required: unique account id
    name: 'Acme, Co.',           // Required: account name
    plan: 'Enhanced',
  },
}]);

Una advertencia de la propia documentación de UserVoice: los rasgos enviados de esta manera permanecen ocultos hasta que el usuario interactúa realmente con UserVoice, ya sea votando, comentando, publicando una idea o dando una puntuación NPS. El método Identify tampoco demuestra nada sobre quién es el usuario, que es donde surge la elección entre las dos rutas de identidad.

Las dos formas de adjuntar una identidad difieren en lo que pueden hacer y dónde se ejecutan:

Para un foro público, identify() es suficiente. Para un foro privado, un portal restringido para todo el sitio o cualquier momento en que la identidad deba ser confiable, el token firmado en el siguiente paso es lo que necesitas.

5. Firma un token JWT SSO de UserVoice en Webflow Cloud

Un token firmado convierte una reclamación sin verificar en una identidad de confianza, ya que UserVoice lo comprueba con un secreto que solo comparten tu servidor y UserVoice. Esa firma no puede realizarse en un sitio estático de Webflow, por lo que este paso introduce una aplicación de Webflow Cloud que se ejecuta como un Cloudflare Worker.

Primero, obtén la clave. En UserVoice, la clave SSO se encuentra en el área de Autenticación de usuario de la configuración del Portal web, y también aparece en la Configuración del widget bajo Configuración avanzada. Guárdala en Webflow Cloud como una variable de entorno secreta llamada USERVOICE_SSO_KEY. UserVoice requiere el algoritmo HS256, por lo que el gestor de rutas firma con HMAC-SHA256 a través de la API Web Crypto en lugar de usar una biblioteca JWT de Node.

Crea un gestor de rutas que genere y firme el token:

// app/api/uservoice/sso/route.ts
import { NextResponse, type NextRequest } from "next/server";

function base64url(input: string | ArrayBuffer): string {
  const bytes =
    typeof input === "string"
      ? new TextEncoder().encode(input)
      : new Uint8Array(input);
  let binary = "";
  for (const b of bytes) binary += String.fromCharCode(b);
  return btoa(binary)
    .replace(/\+/g, "-")
    .replace(/\//g, "_")
    .replace(/=+$/, "");
}

export async function POST(request: NextRequest) {
  const { guid, email, name } = (await request.json()) as {
    guid: string;
    email: string;
    name: string;
  };

  // Read the SSO secret at runtime from Webflow Cloud's environment.
  const secret = process.env.USERVOICE_SSO_KEY as string;

  const header = { alg: "HS256", typ: "JWT" };
  const payload = {
    guid,                 // Required: a unique id, never the email
    email,                // Required: used for notification emails
    display_name: name,
    exp: Math.floor(Date.now() / 1000) + 60 * 60, // UNIX timestamp
  };

  const signingInput =
    `${base64url(JSON.stringify(header))}.${base64url(JSON.stringify(payload))}`;

  // UserVoice requires the HS256 signing algorithm.
  const key = await crypto.subtle.importKey(
    "raw",
    new TextEncoder().encode(secret),
    { name: "HMAC", hash: "SHA-256" },
    false,
    ["sign"]
  );

  const signature = await crypto.subtle.sign(
    "HMAC",
    key,
    new TextEncoder().encode(signingInput)
  );

  const token = `${signingInput}.${base64url(signature)}`;
  return NextResponse.json({ token });
}

El gestor lee el secreto dentro del cuerpo de la función para que se resuelva en el contexto de la solicitud, el patrón que Webflow documenta para la configuración en tiempo de ejecución. Establece en un ID único en lugar del correo electrónico, que es lo que requiere UserVoice, y marca una reclamación guidexp como una marca de tiempo UNIX para que el token caduque. El resultado es un punto de conexión que devuelve un token recién firmado para el usuario actual.

6. Configura el token firmado en el widget para verificar la identidad

El último paso entrega el token al widget. Configurar la opción sso antes de que se inicie el widget es lo que le permite acceder a foros privados y a un sitio restringido, y lo que marca al usuario como un autor verificado.

Obtén el token de tu gestor y configúralo antes de añadir el activador:

// In a Client Component, after the user signs in.
// Webflow Cloud exposes the mount path at runtime; do not read next.config.
const baseUrl = process.env.NEXT_PUBLIC_BASE_PATH ?? "";

const res = await fetch(`${baseUrl}/api/uservoice/sso`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ guid: user.id, email: user.email, name: user.name }),
});
const { token } = await res.json();

// Hand the signed token to the widget before it launches.
UserVoice.push(['set', { sso: token }]);
UserVoice.push(['addTrigger', {}]);

El prefijo baseUrl es importante en Webflow Cloud porque la aplicación se monta en una ruta base como /app, por lo que una ruta simple se resolvería contra la raíz incorrecta. Léela en tiempo de ejecución desde process.env.NEXT_PUBLIC_BASE_PATH, la ruta de montaje que expone Webflow Cloud, en lugar de importar next.config, lo cual no funciona en la plataforma. Configura la opción sso antes de addTrigger, el orden que muestra la documentación de JWT SSO de UserVoice, para que el widget lea el token al iniciarse. Los usuarios que han iniciado sesión ahora pueden acceder a foros privados y aparecer como autores verificados en cada idea y voto.

¿Qué hace que los widgets de UserVoice fallen en Webflow? Consejos para solucionar problemas

La mayoría de los problemas de UserVoice en Webflow se deben a dónde reside el código, si el visitante está identificado y si un foro privado espera un token que el widget nunca recibió.

Cada síntoma a continuación empareja su causa con la solución.

El widget nunca aparece en el sitio publicado

Causa: El cargador se pegó en el código del encabezado (Header Code) en lugar del código del pie de página (Footer Code), el marcador de posición {subdomain} o {JS key} nunca se reemplazó con valores reales, o el sitio se guardó pero no se publicó.

Solución: Mueve el cargador a Configuración del sitio > Código personalizado > Código del pie de página, luego abre el panel de Red de tu navegador y confirma que el script widget_environment realmente realiza la solicitud desde tu subdominio real usando la clave del SDK de JavaScript en Configuración > Widgets. Un error 404 ahí significa que todavía hay un marcador de posición en el código. El código personalizado solo se envía en páginas publicadas y solo en un plan de sitio de pago, por lo que un sitio Starter gratuito o una vista previa de ensayo no publicada se verá vacío incluso cuando el fragmento sea correcto. Vuelve a publicar después de cada cambio, porque Webflow no envía el código personalizado al dominio activo hasta que lo haces.

Los usuarios que han iniciado sesión siguen apareciendo como anónimos

Causa: La llamada identify() se ejecutó antes de que el usuario hiciera algo que el widget registra, o falta un campo obligatorio en la carga útil, por lo que UserVoice no tiene nada a lo que adjuntar los rasgos.

Solución: Confirma que el correo electrónico y el ID de usuario están presentes en la llamada, y que cualquier objeto de cuenta que pases lleva su ID y nombre requeridos. Debido a que el SDK se carga de forma asíncrona, comprueba en la consola del navegador que identify() se ejecuta después de que el cargador haya terminado y no antes, ya que una llamada realizada demasiado pronto se descarta. Luego, recuerda que los rasgos solo aparecen después de que la persona vota, comenta, publica una idea o responde a una encuesta NPS, así que activa una de esas acciones y vuelve a abrir el widget para confirmar que los datos llegaron en lugar de asumir que la llamada falló silenciosamente.

El token SSO es rechazado y los usuarios permanecen desconectados

Causa: El token se firmó con el algoritmo incorrecto o una clave obsoleta, guid se configuró con la dirección de correo electrónico en lugar de un ID único, o exp se envió como algo distinto a una marca de tiempo UNIX.

Solución: Firma con HS256 usando la clave SSO del área de Autenticación de Usuario en la configuración de tu Portal Web, establece guid en un ID único y estable en lugar del correo electrónico, incluye el correo por separado y pasa exp como una marca de tiempo UNIX. Dado que la clave de firma es secreta, realiza la firma en tu controlador de rutas de Webflow Cloud con la API Web Crypto; nunca lo hagas en el código del navegador, donde la clave quedaría expuesta. Por último, configura la opción sso antes de addTrigger para que el widget lea el token en el orden correcto, ya que cualquier configuración posterior será ignorada.

El widget del foro privado no muestra nada

Causa: El foro es privado o el sitio completo está restringido, por lo que el widget anónimo no tiene una identidad que autorizar y se muestra vacío en lugar de recurrir a una vista pública.

Solución: Proporciona un token SSO firmado como se muestra en los pasos cinco y seis, y confirma que el guid firmado corresponde a un usuario que realmente tiene acceso a ese foro privado, ya que un token válido para un usuario sin permisos seguirá sin mostrar nada. Los foros privados y los sitios restringidos no pueden recurrir al acceso anónimo, por lo que el token es la única forma de abrirlos. Revisa el panel de Red para ver la solicitud de identidad del widget y confirma que lleva tu token; si la solicitud sale como anónima, la opción sso se configuró después de addTrigger o el punto de conexión de firma devolvió un error que el widget omitió.

Qué puedes construir con UserVoice y Webflow

Con el widget integrado y la identidad firmada en el borde (edge), los siguientes pasos llevan los comentarios más profundamente a tu stack y traen los datos de UserVoice de vuelta a tu aplicación de Webflow Cloud.

El siguiente paso habitual es el trabajo de servidor a servidor. En lugar de solo recopilar ideas en el navegador, tu aplicación de Webflow Cloud puede crear sugerencias, sincronizar usuarios y leer comentarios a través de las API de backend de UserVoice cuando ocurre algo en el servidor, como un nuevo registro o un trato cerrado.

La plataforma para desarrolladores de UserVoice documenta la API de administración para el acceso a datos y la API de recopilación de ideas para formularios de captura personalizados, ambas combinan perfectamente con el patrón de controlador de rutas del paso cinco.

Explora Webflow + UserVoice para obtener el desglose completo de las opciones de integración, desde un simple código incrustado en una página estática hasta flujos de trabajo basados en API que sincronizan los comentarios en todo tu stack.

Para las piezas del lado del servidor que se encuentran detrás de un token firmado, desde secretos de entorno hasta controladores de rutas, la documentación para desarrolladores de Webflow explica cómo se ejecuta una aplicación de Webflow Cloud en el borde.