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).
| Camino | Cuándo conviene | Tiempo |
|---|---|---|
| Con agentes (recomendado) | Programas con un agente de código o un asistente de IA | Unos minutos |
| Manual | Prefieres 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.jsonen 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:
- Pone el script en el layout compartido de tu framework.
- Agrega la firma del token de identidad en tu backend.
- Permite el origen local y el de producción.
- 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_SECRETde 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
| Paso | Qué haces | Estimado |
|---|---|---|
| 1 | Pegar el SDK | 2 min |
| 2 | Permitir tus sitios | 1 min |
| 3 | Identificar a tus usuarios | 15 min |
| 4 | Elegir cómo se abre | 5 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:
| Estilo | Qué ve tu usuario |
|---|---|
| Globito | Un botón redondo en una esquina |
| Botón con texto | El botón flotante con tu texto |
| Pestaña lateral | Una pestaña en el borde que se abre con clic o arrastrándola |
| Desde tu botón | El panel se despliega bajo un botón tuyo, por ejemplo junto a la campana |
| Solo por código | Lo 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_releasedel 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>
| Atributo | Para qué sirve |
|---|---|
data-user | El id de la persona en tu sistema |
data-email | Correo ya conocido: el formulario no lo vuelve a pedir |
data-lang | Idioma: es, en o pt |
data-category | Etiqueta para filtrar respuestas |
data-meta-plan | Cualquier 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
httpohttpsy 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/readonlyo tu rol es de solo lectura. Las herramientas para instalar y resolver aparecen en/mcpcon 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_SECRETesté 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.