Paso 1: divide en cuatro grupos (carga / config / framework / visualización)
Cualquiera que sea tu «el chat no salió», acótalo primero a cuatro grupos — solo esto ahorra la mayoría de los rodeos. El diagrama de flujo aclara la decisión: comprueba si el script siquiera cargó (meiqia.js en F12), luego si es config, framework o un problema de capa de visualización. Para lo básico ve la guía de integración web de 美洽.
Cómo funciona la integración: por qué falla / se bloquea esta inyección JS
Basta una frase: el widget web de 美洽 no es un componente estático en tu página: es un meiqia.js cargado de forma asíncrona desde el dominio externo de 美洽 que inyecta dinámicamente un contenedor de chat (DOM / iframe) y abre una conexión persistente de origen cruzado. Para que la inyección funcione necesita «el script cargado (buena ubicación, sin adblock), el contenedor no tapado por CSS / otros plugins, entId y dominio coincidiendo, y remontaje tras un cambio de ruta SPA». El diagrama de abajo dibuja esta cadena y cuatro puntos de bloqueo — por eso el mismo código funciona en un sitio / framework pero no en otro.
Código bien puesto pero sigue sin aparecer: corre el panel de autochequeo de integración
Si ubicación, meiqia.js 200 y entId están todos confirmados pero sigue sin aparecer, básicamente es «adblock» o «framework / apilamiento». El panel de abajo está ordenado por importancia: verde suele estar bien, los rojos (adblock, apilamiento SPA / plugin de terceros) son las trampas frecuentes. Revisarlos ítem por ítem lo localiza rápido.
Tabla completa de síntomas (comportamiento / ubicación oficial · causa raíz L2)
La tabla de abajo lista de una vez los síntomas comunes de no aparecer / error, cada uno con su ubicación oficial y causa raíz L2. La caja de búsqueda de arriba se alimenta de los datos de esta tabla — busca la palabra clave que encontraste.
| Síntoma | Grupo | Comportamiento L1 / ubicación oficial | Causa raíz L2 |
|---|---|---|---|
| La ventana / burbuja de chat no aparece en absoluto | Fallo de carga | El widget web de 美洽 carga una ventana de chat flotante con un solo snippet JS pegado; confirma que el código esté bien incrustado y el sitio de integración configurado en la consola. | El widget es meiqia.js inyectado en el DOM tras una carga asíncrona, así que «nada en absoluto» suele significar «el script nunca cargó»: mala ubicación, bloqueado por adblock / caché, o dominio / entId sin coincidir, así que la inyección nunca corrió. |
| El script cargó pero falta el botón de chat | Problemas de visualización | El código del widget se adapta al sitio y muestra un botón de chat; si la visualización falla, revisa si está oculto por estilos o si la inicialización se interrumpió. | Si el script carga pero falta el botón, suele ser un problema de «capa de visualización»: el CSS global anula la posición / pone display:none, pierde el z-index, u otro elemento fijo lo tapa; otro error JS en la página también puede abortar la inicialización. |
| meiqia.js bloqueado por una extensión de adblock | Fallo de carga | El script de chat de 美洽 viene de un dominio de terceros; si hay una extensión de bloqueo instalada puede tratarlo como anuncio / rastreador e impedir la carga — desactiva el bloqueo o añade a lista blanca. | ERR_BLOCKED_BY_CLIENT significa que una extensión del navegador (AdBlock / uBlock / AdGuard) bloqueó la petición por sus listas de filtros. El script de 美洽 es «terceros fuera de dominio + comunicación en tiempo real», que esas reglas suelen confundir con anuncio / rastreador, causando un fallo falso «consola bien, lado del usuario ausente». |
| meiqia.js 404 / estado erróneo / contenido mixto | Fallo de carga | Tras desplegar, busca meiqia.js en el panel Network; un estado 200 significa que el script está bien ubicado y cargado. | Causas comunes de no-200: código retenido por caché de página / CDN (sin refrescar tras publicar), carga en página HTTP / cadena de certificado incompleta que dispara bloqueo de contenido mixto, o código roto / copiado parcialmente. Con este paso fallido, la inyección y la conexión nunca ocurren. |
| Código mal ubicado (bloqueo en head / sin efecto) | Fallo de carga | 美洽 recomienda pegar el código al final de la página, antes de </body>; el widget corre tras cargar el contenido principal. | El widget debe inyectar su contenedor tras estar listo el DOM. En <head> bloquea el render (pantalla en blanco primero en red lenta) o corre antes de listo el DOM y falla la inyección; dentro de algún ámbito asíncrono / de módulo el orden de carga también puede salir mal. |
| Estilo roto de la ventana / botón de chat | Problemas de visualización | El widget inyecta sus propios estilos y se adapta al sitio; los conflictos con estilos globales pueden causar fallos visuales. | El script de 美洽 inyecta CSS en tiempo de ejecución; si los estilos globales (selectores universales / reglas de alta prioridad / resets) anulan sus clases primero, se rompen posición, apilamiento y fuentes — un efecto secundario de «inyección dinámica + compartir un mismo espacio de estilos del documento». |
| Botón fuera de pantalla / tapado | Problemas de visualización | El botón del widget aparece como flotante de posición fija; si lo tapan otros elementos fijos, ajusta el apilamiento o la posición. | Otros elementos position:fixed del sitio (volver arriba, anuncios flotantes, una barra de soporte propia) con mayor z-index tapan el botón de 美洽, o el tema calcula mal sus coordenadas, dejándolo «fuera de pantalla / tapado». |
| Conflicto de DOM con plugin / analítica de terceros | Problemas de visualización | Otros scripts de la página que modifican el DOM o interceptan peticiones pueden afectar la carga y visualización normales del widget. | Los scripts de mapa de calor / analítica / conversión reescriben el DOM, inyectan overlays o interceptan peticiones; como ellos y 美洽 inyectan en el mismo documento, el apilamiento / eventos interfieren y el contenedor de 美洽 queda tapado o su init interrumpido. |
| El widget desaparece tras un cambio de ruta SPA | Integración de framework | Para apps de una sola página (SPA), usa los hooks de ruta del framework para cargar / iniciar el widget de 美洽 y que encaje con el enrutado del frontend. | Una SPA cambia vistas vía enrutado del frontend, destruyendo / recreando el DOM, pero meiqia.js inyecta una vez en la primera carga por defecto y no se recrea solo al cambiar de ruta, así que «cambias de página y el chat desaparece». |
| Init manual necesario (manualInit / init) | Integración de framework | Añade _MEIQIA('manualInit') tras el código de incrustación de 美洽 para detener el auto-init tras la descarga; llama _MEIQIA('init') para iniciar manualmente cuando haga falta. | Por defecto 美洽 se autoinicia justo tras descargar; cuando necesitas el contenedor listo / datos del cliente pasados / la ruta estable primero, ese momento es «demasiado pronto» — cambia a init manual para controlar la secuencia. |
| entId no coincide / los agentes no reciben chats | Configuración / autorización | El número tras entId en el código es el id único de tu empresa; si no coincide con el panel los agentes no pueden atender el chat — encuentra el ID de empresa en Ajustes - Equipo - búsqueda de ID. | entId vincula el snippet a una cuenta de empresa concreta. Con el código de otro / de otro entorno, o cuentas mezcladas, el frontend carga la ventana pero los mensajes van a «otra empresa», así que este panel no recibe ninguno — el clásico «se ve bien pero no recibe nada». |
| Dominio del sitio no autorizado en la consola | Configuración / autorización | La consola de 美洽 permite «Añadir sitio de integración», cada uno con su config; un sitio nuevo debe configurarse en la consola antes de integrarse bien. | 美洽 gestiona varios sitios como «sitios de integración»; el dominio debe registrarse / autorizarse en la consola para ser reconocido. Un dominio de producción nuevo sin añadir puede no aceptarse o mapearse a la config equivocada. |
| Multi-sitio / subcanal (sonda) cruzado | Configuración / autorización | 美洽 permite desplegar distintos widgets y enlaces de chat por sitio (subcanales / sonda); además del sitio por defecto puedes añadir más, cada uno con su config. | Distintas líneas de negocio necesitan distintos grupos de agentes / mensajes automáticos, pero si cada sitio comparte el único snippet por defecto, no se distinguen orígenes y las configs se cruzan. Los subcanales (sonda) están diseñados para «una empresa, varias entradas, enrutadas». |
| Chat web móvil no aparece / necesita despliegue aparte | Móvil / SDK | El código del widget se adapta al sitio; móvil / PC usan el mismo snippet pero debe desplegarse por separado. | Muchos equipos tienen páginas / plantillas PC y móvil separadas y solo pegaron el código en la plantilla PC. El snippet es el mismo y se autoadapta, pero el paso de «pegar» debe hacerse también en la plantilla móvil; si se omite, móvil no tiene chat. |
| Integración del SDK nativo de app / AppKey | Móvil / SDK | La integración in-app necesita un AppKey del panel de 美洽 (Ajustes - Integración - SDK, «Añadir config APP»), y los desarrolladores integran el SDK iOS / Android según la doc y el demo oficiales. | Una app usa el SDK nativo, no JS web: primero «Añadir config APP» para un AppKey, luego integra el SDK por plataforma para la UI de chat, no leídos, push, etc. — una ruta totalmente distinta del widget web. |
| El push de mensajes del SDK no llega | Móvil / SDK | El push del SDK de 美洽 tiene dos modos: con «sin push», los mensajes del agente llegan solo dentro de la app (ábrela para recibir); con un «servidor de push propio», los usuarios reciben push al teléfono incluso tras salir de la app. | La falta de «push offline» suele significar que el modo de push es «sin push», o no hay servidor de push propio / certificados de push por plataforma. La ruta es «美洽 → servidor de la app → teléfono del usuario»; un eslabón faltante deja solo recepción in-app. |
| Ocultar el botón por defecto / entrada propia | Llamadas a la API | Llama _MEIQIA('withoutBtn') para no mostrar el botón nativo de 美洽; tras un init exitoso, llama _MEIQIA('showPanel') para abrir el chat. | Por defecto se renderiza el botón flotante nativo; para usar tu entrada debes declarar «sin botón nativo» antes / durante el init y enlazar «abrir chat» a tu elemento — un asunto de tiempo de API, no un «botón roto». |
| Pasar / sincronizar datos del cliente no surte efecto | Llamadas a la API | El widget web de 美洽 ofrece APIs «pasar datos del cliente», «sincronizar identidad» y «añadir info de evento personalizada» para llevar datos del visitante al chat. | Estas APIs deben llamarse dentro del tiempo de init correcto: tras un init exitoso (o con el tiempo de manualInit + init). Demasiado pronto / tarde, o formatos de campo erróneos, y queda «puesto pero sin efecto». |
美洽 causas de no aparecer & comparativa de métodos de integración (estimación 2026)
Las siguientes son estimaciones 2026 sintetizadas de la ayuda oficial de 美洽 (Canales de acceso / API del widget web JavaScript) y del troubleshooting público de integración (no son compromisos del proveedor ni medición de primera mano; de referencia, cambian por versión y política del navegador):
| Dimensión | Estimación / comparación |
|---|---|
| Reparto de causas de no aparecer (comunidad / tickets · est.) | ubicación / no cargado ~35% > adblock / extensión del navegador ~25% > config / autorización (entId / dominio) ~20% > framework (SPA) ~12% > conflicto de estilo / plugin de terceros ~8% |
| Qué es realmente la integración | el widget web = JS asíncrono de terceros fuera de dominio que inyecta el DOM + una conexión persistente de origen cruzado (no un componente estático incrustado); de ahí el efecto de ubicación, reglas de adblock, apilamiento CSS, ciclo de vida SPA |
| Integración por plataforma (est.) | web PC / móvil = widget JS (mismo código, desplegado aparte); app = SDK nativo (AppKey); WeChat / Douyin / RED = integración autorizada por canal |
| Impacto del adblock (est.) | cerca del 30-40% de usuarios PC usan una extensión de adblock → el script de chat de terceros se bloquea por reglas de anuncios (ERR_BLOCKED_BY_CLIENT), causa principal de «consola bien, lado del usuario ausente» |
| Tiempo a producción del widget JS (oficial) | pega el JS dedicado al final de la página y entra en producción en unos 3-5 minutos; entId es el id único de la empresa, y un desajuste con el panel deja a los agentes sin chats |
Base de la estimación: línea base de fuentes + extrapolación temporal (meiqia.com/help Canales de acceso / widget web JavaScript, guía de integración meiqia.im, troubleshooting público, 2026); cambia con la versión y la política de bloqueo del navegador. Sigue la info oficial más reciente de 美洽. No oficial · localización LLM.
Cinco métodos de integración de 美洽 comparados (código / dificultad / funciones / escenario / tiempo a producción)
¿Qué método de integración? La comparativa de abajo sintetiza la doc oficial de 美洽 para una referencia transversal rápida (volumen de código, funciones, mejor encaje, tiempo a producción). La mayoría de sitios eligen el «widget JS web».
| Método de integración | Código / dificultad | Funciones completas | Mejor para | Tiempo a producción |
|---|---|---|---|---|
| Widget JS web | un snippet JS · bajo | lo más completo (flotante / popup / saludo automático / rastro de visitante) | sitios PC + móvil (recomendado oficial) | ~3-5 min |
| Enlace de chat | sin código · mínimo | chat básico | sin técnica / soltar un enlace de chat rápido | instantáneo |
| API / SDK WebIM | requiere dev · alto | personalización profunda (UI propia / sistema / integración de pedidos) | equipos con capacidad dev para fusión profunda | según dev |
| SDK nativo de app | integrar SDK · alto | chat in-app + push de mensajes | apps iOS / Android | según dev |
| Config rápida CMS | plugin / un clic · bajo | igual que el widget JS | sitios WordPress / Fkw / Shopify | minutos |
Canal / escenario → mapa de resultado de integración
El mismo 美洽 se integra distinto por canal / escenario. El mapa de abajo muestra canales comunes: verde = pegar y listo, ámbar = necesita config (despliegue aparte / init / lista blanca), rojo = cambiar de método por defecto (adblock / entId / la app usa SDK).
Preguntas frecuentes
美洽 La ventana / burbuja de chat no aparece en absoluto — ¿cómo se soluciona?
El widget web de 美洽 carga una ventana de chat flotante con un solo snippet JS pegado; confirma que el código esté bien incrustado y el sitio de integración configurado en la consola. El widget es meiqia.js inyectado en el DOM tras una carga asíncrona, así que «nada en absoluto» suele significar «el script nunca cargó»: mala ubicación, bloqueado por adblock / caché, o dominio / entId sin coincidir, así que la inyección nunca corrió. F12 → Network, busca meiqia.js: sin petición → código sin efecto (revisa ubicación / limpia caché); con petición pero no-200 → bloqueado o problema de ruta; todo bien pero sigue oculto → revisa entId / autorización de dominio y los grupos de abajo.
美洽 El script cargó pero falta el botón de chat — ¿cómo se soluciona?
El código del widget se adapta al sitio y muestra un botón de chat; si la visualización falla, revisa si está oculto por estilos o si la inicialización se interrumpió. Si el script carga pero falta el botón, suele ser un problema de «capa de visualización»: el CSS global anula la posición / pone display:none, pierde el z-index, u otro elemento fijo lo tapa; otro error JS en la página también puede abortar la inicialización. F12 → Elements, busca el contenedor de 美洽 — ¿está presente, oculto o fuera de pantalla?; desactiva temporalmente CSS / scripts propios para reprobar; revisa la consola por un error que abortó la ejecución.
美洽 meiqia.js bloqueado por una extensión de adblock — ¿cómo se soluciona?
El script de chat de 美洽 viene de un dominio de terceros; si hay una extensión de bloqueo instalada puede tratarlo como anuncio / rastreador e impedir la carga — desactiva el bloqueo o añade a lista blanca. ERR_BLOCKED_BY_CLIENT significa que una extensión del navegador (AdBlock / uBlock / AdGuard) bloqueó la petición por sus listas de filtros. El script de 美洽 es «terceros fuera de dominio + comunicación en tiempo real», que esas reglas suelen confundir con anuncio / rastreador, causando un fallo falso «consola bien, lado del usuario ausente». Reprueba en incógnito o con el adblock apagado — si aparece, el bloqueo era la causa; pide a los usuarios que añadan el sitio a lista blanca; el frontend puede cargar el script de forma diferida / condicional para esquivar algunas reglas automáticas.
美洽 meiqia.js 404 / estado erróneo / contenido mixto — ¿cómo se soluciona?
Tras desplegar, busca meiqia.js en el panel Network; un estado 200 significa que el script está bien ubicado y cargado. Causas comunes de no-200: código retenido por caché de página / CDN (sin refrescar tras publicar), carga en página HTTP / cadena de certificado incompleta que dispara bloqueo de contenido mixto, o código roto / copiado parcialmente. Con este paso fallido, la inyección y la conexión nunca ocurren. Limpia la caché CDN / navegador (o usa incógnito) tras publicar; asegura HTTPS completo con cadena de certificado íntegra y sin contenido mixto; verifica que el código copiado esté completo y sin escapar.
美洽 Código mal ubicado (bloqueo en head / sin efecto) — ¿cómo se soluciona?
美洽 recomienda pegar el código al final de la página, antes de </body>; el widget corre tras cargar el contenido principal. El widget debe inyectar su contenedor tras estar listo el DOM. En <head> bloquea el render (pantalla en blanco primero en red lenta) o corre antes de listo el DOM y falla la inyección; dentro de algún ámbito asíncrono / de módulo el orden de carga también puede salir mal. Pon el JS de 美洽 en el pie común de cada página, antes de </body>; para SPAs ve la entrada «ruta SPA» y usa manualInit; asegúrate de que un bundler no lo elimine por tree-shaking.
美洽 Estilo roto de la ventana / botón de chat — ¿cómo se soluciona?
El widget inyecta sus propios estilos y se adapta al sitio; los conflictos con estilos globales pueden causar fallos visuales. El script de 美洽 inyecta CSS en tiempo de ejecución; si los estilos globales (selectores universales / reglas de alta prioridad / resets) anulan sus clases primero, se rompen posición, apilamiento y fuentes — un efecto secundario de «inyección dinámica + compartir un mismo espacio de estilos del documento». F12 para ver qué regla del sitio anula el contenedor de 美洽; acota los estilos globales / reduce su impacto en clases genéricas; si hace falta, pide a 美洽 ajustar el apilamiento del contenedor.
美洽 Botón fuera de pantalla / tapado — ¿cómo se soluciona?
El botón del widget aparece como flotante de posición fija; si lo tapan otros elementos fijos, ajusta el apilamiento o la posición. Otros elementos position:fixed del sitio (volver arriba, anuncios flotantes, una barra de soporte propia) con mayor z-index tapan el botón de 美洽, o el tema calcula mal sus coordenadas, dejándolo «fuera de pantalla / tapado». Selecciona el contenedor de 美洽 en F12 para ver coordenadas / z-index reales; súbelo o baja el z-index del elemento que tapa; evita apilar varios flotantes fijos en una esquina.
美洽 Conflicto de DOM con plugin / analítica de terceros — ¿cómo se soluciona?
Otros scripts de la página que modifican el DOM o interceptan peticiones pueden afectar la carga y visualización normales del widget. Los scripts de mapa de calor / analítica / conversión reescriben el DOM, inyectan overlays o interceptan peticiones; como ellos y 美洽 inyectan en el mismo documento, el apilamiento / eventos interfieren y el contenedor de 美洽 queda tapado o su init interrumpido. Desactiva plugins sospechosos uno a uno para localizar el conflicto; ajusta orden de carga / apilamiento del contenedor; haz que los mapas de calor eviten la zona del contenedor de 美洽.
美洽 El widget desaparece tras un cambio de ruta SPA — ¿cómo se soluciona?
Para apps de una sola página (SPA), usa los hooks de ruta del framework para cargar / iniciar el widget de 美洽 y que encaje con el enrutado del frontend. Una SPA cambia vistas vía enrutado del frontend, destruyendo / recreando el DOM, pero meiqia.js inyecta una vez en la primera carga por defecto y no se recrea solo al cambiar de ruta, así que «cambias de página y el chat desaparece». Usa _MEIQIA('manualInit') para detener el auto-init y llama _MEIQIA('init') en un hook de ruta (React useEffect / Vue mounted / router afterEach) para remontar bajo demanda; evita iniciar varias instancias.
美洽 Init manual necesario (manualInit / init) — ¿cómo se soluciona?
Añade _MEIQIA('manualInit') tras el código de incrustación de 美洽 para detener el auto-init tras la descarga; llama _MEIQIA('init') para iniciar manualmente cuando haga falta. Por defecto 美洽 se autoinicia justo tras descargar; cuando necesitas el contenedor listo / datos del cliente pasados / la ruta estable primero, ese momento es «demasiado pronto» — cambia a init manual para controlar la secuencia. Añade _MEIQIA('manualInit') tras el código; llama _MEIQIA('init') cuando estén listas las condiciones (DOM / sesión / ruta); llama las APIs de datos en orden dentro del tiempo de init según la doc.
Más config de integración: integración web de 美洽, integración SDK de APP; para empezar: guía de 美洽. Una versión completa con búsqueda (incl. esta herramienta) también en troubleshooting de integración de 美洽 (GitHub Pages).