Integrar Melonhelp Feedback en tu app

Hay dos caminos para instalar Feedback y puedes cambiar de uno a otro cuando quieras. Los dos están en Ajustes, Instalación dentro de feedback.melonhelp.com.

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 Claude (web o escritorio): Settings, Connectors, Add custom connector.
• En Claude Code o Cursor: un archivo .mcp.json en la raíz del repositorio.

{
  "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.

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, Instalación a la variable MELON_FEEDBACK_SECRET. El agente nunca lo pide por chat.
• Confirmar tu dominio de producción si no está en el repositorio.

Manual

1. Pega el SDK

Antes de </body>, en el layout compartido de tu app. Tu clave pública está arriba a la derecha en Ajustes, Instalación.

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

2. Permite tus sitios

En Ajustes, Instalación 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:

// 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).

4. Elige cómo se abre

En Ajustes, Instalación, sección Widget, con vista previa en una página de ejemplo:

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.

Encuestas de satisfacción

Las encuestas usan otro script y su propia clave, que encuentras en la pestaña Instalación de cada encuesta:

<script src="https://feedback.melonhelp.com/widget/loader.js" data-key="fb_..." async></script>

// 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. 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.
• 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.