Melonhelp Feedback

Integrar Melonhelp Feedback en tu app

Hay dos caminos para instalar el botón de feedback y puedes cambiar de uno a otro cuando quieras. Todo lo que el botón necesita (clave pública, sitios permitidos, secreto de identidad y cómo se abre) está en Ajustes, Botón de feedback dentro de feedback.melonhelp.com. Las encuestas de satisfacción se instalan aparte, desde la pestaña Instalación de cada encuesta (más abajo).

CaminoCuándo convieneTiempo
Con agentes (recomendado)Programas con un agente de código o un asistente de IAUnos minutos
ManualPrefieres pegar el código tú10 a 25 minutos

Con agentes

Tu agente detecta el framework, escribe el código con tu clave real, permite tus sitios y verifica que cargó. Son tres pasos.

1. Instala la skill

Ejecuta esto una vez en la raíz de tu repositorio:

npx skills add https://feedback.melonhelp.com

La skill melonhelp-feedback deja en tu repositorio las instrucciones para integrar Feedback. Usa el estándar abierto Agent Skills, así que sirve para cualquier agente compatible.

2. Conecta el servidor MCP

Agrega este servidor en los ajustes de MCP de tu agente:

https://feedback.melonhelp.com/mcp
  • En asistentes de chat y editores: agrega un conector MCP personalizado y pega la URL.
  • En agentes que leen la configuración desde el repositorio: un archivo como .mcp.json en la raíz.
{
  "mcpServers": {
    "melonhelp-feedback": {
      "type": "http",
      "url": "https://feedback.melonhelp.com/mcp"
    }
  }
}

Se abre el navegador para que autorices con tu cuenta de Melonhelp. No hay claves que guardar. Con el servidor conectado, tu agente lee tu clave pública, tus sitios permitidos y tu configuración directo de tu cuenta, sin copiar y pegar. El detalle de las herramientas está en Conector MCP.

Para que el agente instale (permitir sitios, cambiar el botón o crear encuestas) necesitas rol de owner o administrador en el espacio. Si tu rol es de solo lectura, conecta https://feedback.melonhelp.com/mcp/readonly: tu agente podrá leer tu configuración, pero los cambios los hace un administrador.

3. Pídeselo

Con el proyecto abierto, escribe algo así:

Integra Melonhelp Feedback en este proyecto usando la skill melonhelp-feedback y su servidor MCP.
Antes de escribir código, aclara conmigo lo que no puedas deducir del repositorio.

El agente pregunta lo que no puede saber solo (qué instalar, si identificas usuarios, tu dominio de producción y cómo se abre) y después:

  1. Pone el script en el layout compartido de tu framework.
  2. Agrega la firma del token de identidad en tu backend.
  3. Permite el origen local y el de producción.
  4. Verifica la instalación y te dice qué falta.

Lo que queda para ti:

  • Copiar el secreto de identidad desde Ajustes, Botón de feedback (sección Secreto de identidad) a la variable MELON_FEEDBACK_SECRET de tu servidor. El agente nunca lo pide por chat.
  • Confirmar tu dominio de producción si no está en el repositorio.
  • Registrar cada versión cuando ya esté desplegada, si cierras errores por versión (ver Versiones desplegadas, más abajo).

Manual

PasoQué hacesEstimado
1Pegar el SDK2 min
2Permitir tus sitios1 min
3Identificar a tus usuarios15 min
4Elegir cómo se abre5 min

1. Pega el SDK

Antes de </body>, en el layout compartido de tu app. En Ajustes, Botón de feedback, sección Código del SDK, tienes el script listo con tu clave pública.

<script src="https://feedback.melonhelp.com/sdk.js" data-key="pk_..." async></script>

2. Permite tus sitios

En Ajustes, Botón de feedback, sección Sitios permitidos, agrega los orígenes donde corre tu app, uno por línea: el local (http://localhost:3000) y el de producción. https://*.tuapp.com cubre todos los subdominios. Sin esto el SDK no carga.

3. Identifica a tus usuarios

Así cada pedido queda asociado a una persona real, su correo queda verificado y recibe el aviso cuando lo que pidió se publica. Tu servidor firma un JWT HS256 con el secreto de identidad, que está en Ajustes, Botón de feedback, sección Secreto de identidad (botón Mostrar). Guárdalo solo en tu servidor, en la variable MELON_FEEDBACK_SECRET:

// npm i jose
import { SignJWT } from "jose";

const secret = new TextEncoder().encode(process.env.MELON_FEEDBACK_SECRET);

export async function feedbackToken(user) {
  return new SignJWT({ email: user.email, name: user.name, plan: user.plan })
    .setProtectedHeader({ alg: "HS256" })
    .setSubject(String(user.id))
    .setIssuedAt()
    .setExpirationTime("1h")
    .sign(secret);
}

Después entrega el token en el script con data-user-token="...", o desde JavaScript en una app de una sola página:

window.MelonFeedback("identify", { token });
// Al cerrar sesión
window.MelonFeedback("logout");

Campos del token: sub (el id de tu usuario, obligatorio), email, name, avatar, company, plan y mrr (en centavos).

Mostrar y rotar el secreto requiere rol de owner o administrador. Si lo rotas, los tokens firmados con el secreto anterior dejan de funcionar hasta que actualices la variable en tu servidor.

4. Elige cómo se abre

En Ajustes, Botón de feedback, sección Botón y panel, con vista previa en una página de ejemplo. Ahí mismo eliges las pestañas del panel y cómo se capturan los errores:

EstiloQué ve tu usuario
GlobitoUn botón redondo en una esquina
Botón con textoEl botón flotante con tu texto
Pestaña lateralUna pestaña en el borde que se abre con clic o arrastrándola
Desde tu botónEl panel se despliega bajo un botón tuyo, por ejemplo junto a la campana
Solo por códigoLo abres tú con MelonFeedback("open")

Idioma

El panel usa el idioma del navegador de cada visitante (español, inglés o portugués). En una app con varios idiomas pásalo según el usuario:

<script src="https://feedback.melonhelp.com/sdk.js" data-key="pk_..." data-lang="es" async></script>
// Si el usuario cambia de idioma en tu app
window.MelonFeedback("setLocale", "en");

Reportar errores

Con data-capture-errors="ask" el SDK captura los errores no controlados y le pregunta al usuario si quiere reportarlos (auto los envía en silencio). En los flujos que importan, reporta también los errores que sí controlas:

try {
  await guardarPedido(pedido);
} catch (error) {
  window.MelonFeedback("captureError", error, { mode: "ask", context: { pedidoId: pedido.id } });
  throw error;
}

Agrega data-release="1.4.2" con la versión de tu app para agrupar los errores por versión y detectar regresiones.

Versiones desplegadas

Cuando marcas un error como resuelto en una versión (por ejemplo 1.4.3), el aviso a quienes lo reportaron sale cuando esa versión queda registrada como desplegada. Regístrala cuando ya esté en producción, nunca antes. Hay dos formas:

  • Tu agente, con la herramienta register_release del conector MCP.
  • Tú, en Errores, con el botón "Registrar versión desplegada".

Registrar dos veces la misma versión no repite el aviso. Si el error vuelve a aparecer en esa versión o en una posterior, se reabre como regresión. El cierre por versión está incluido en los planes Indie y Pro, y registrar versiones requiere rol de owner o administrador.

Encuestas de satisfacción

Las encuestas usan otro script y su propia clave, que encuentras en la pestaña Instalación de cada encuesta (ahí también está cómo instalarla con tu agente de código):

<script src="https://feedback.melonhelp.com/widget/loader.js" data-key="fb_..." async></script>
AtributoPara qué sirve
data-userEl id de la persona en tu sistema
data-emailCorreo ya conocido: el formulario no lo vuelve a pedir
data-langIdioma: es, en o pt
data-categoryEtiqueta para filtrar respuestas
data-meta-planCualquier dato tuyo se guarda con la respuesta (hasta 20)
// Abrirla después de un momento clave
window.MelonFeedback.open({ category: "checkout", metadata: { pedidoId: "A-1042" } });

No pases contraseñas ni datos de pago: lo que va en el script es visible en el código de la página.

Política de seguridad de contenido (CSP)

Si tu sitio envía una cabecera CSP, permite https://feedback.melonhelp.com en script-src, connect-src y frame-src, y data: en img-src.

Problemas comunes

  • El botón no aparece. Casi siempre falta el origen en los sitios permitidos (Ajustes, Botón de feedback). Revisa que sea exacto, con http o https y el puerto.
  • El agente no ve las herramientas. Reautoriza el servidor MCP. Si tu sesión de Melonhelp expiró, el permiso necesita renovarse.
  • El agente solo puede leer. Conectaste /mcp/readonly o tu rol es de solo lectura. Las herramientas para instalar y resolver aparecen en /mcp con rol de owner o administrador. Si tu rol es de solo lectura y conectas /mcp, el servidor rechaza la conexión: usa /mcp/readonly.
  • Los usuarios aparecen sin identificar. Revisa que MELON_FEEDBACK_SECRET esté en el servidor que firma el token y que el token no esté vencido. Si rotaste el secreto, actualiza la variable.
  • Nadie recibió el aviso de un error resuelto. Si lo resolviste en una versión, el aviso sale al registrar esa versión como desplegada.
Integrar Melonhelp Feedback en tu app (con tu agente de código o manual) | Docs de Melonhelp