美洽 widget de chat não aparece / corrigir erro de integração
Fig: 美洽 chat não aparece / correção de erros (comportamento L1 + causa raiz L2 + cinco métodos de integração)
Colou o código do 美洽(Meiqia) e o widget de chat web não aparece, o botão de chat nunca surge, o console informa meiqia.js bloqueado, ou os atendentes não recebem chats? Esclareça três coisas primeiro: o script não carregou de jeito nenhum (posição / adblock / cache), carregou mas ficou oculto por estilo / empilhamento, ou carregou bem mas a config não bate (entId / domínio / ciclo de vida SPA)? Busque o sintoma ou palavra-chave (ex. not showing, adblock, entId, SPA, mobile, sdk push): primeiro o comportamento L1 e o posicionamento oficial, depois a causa raiz L2 e a solução. Instalação / guia? Veja download do 美洽 / guia de integração de atendimento.
Passo 1: verifique se o script carregou e divida em quatro grupos
Quando o chat do 美洽 não aparece, 9 em 10 vezes é um de quatro grupos; veja primeiro se o script sequer carregou: F12 → Network, busque meiqia.js; sem requisição ou status diferente de 200 significa que não carregou. ① Falha de carga: código no lugar errado (vai antes de </body>, não no <head>), bloqueado por regra de adblock (ERR_BLOCKED_BY_CLIENT), retido por cache CDN / navegador, ou certificado HTTPS / conteúdo misto. ② Config / autorização: entId não bate com o painel (carrega mas atendentes não recebem chats), ou domínio não autorizado no console. ③ Integração de framework: uma SPA Vue/React/Next destrói o contêiner na troca de rota e o widget não é recriado. ④ Exibição / mobile / SDK: o CSS do site empurra o balão para fora da tela, um plugin de terceiros sobrepõe o DOM, mobile precisa de deploy próprio, in-app precisa do SDK. Mais completo: guia de integração web do 美洽.
Falha de cargaposição · adblock · cache · HTTPS
Cole o JS do 美洽 antes de
(não no ); F12 → Network, busque meiqia.js e veja o status (deve ser 200); ERR_BLOCKED_BY_CLIENT costuma ser uma extensão de adblock — teste em anônima ou whitelist; limpe o cache CDN após publicar; garanta HTTPS completo sem conteúdo misto.
Config / autorizaçãoentId · lista branca de domínio · subcanais
entId é o id único da sua empresa; se não bate com o painel «o script carrega mas atendentes não recebem chats» (Config - Equipe - busca de ID); o domínio do site deve ser autorizado via «Adicionar site de integração»; use um subcanal (sonda) por linha de negócio.
Integração de frameworkSPA · troca de rota · manualInit
Uma SPA Vue/React/Next destrói o DOM na troca de rota e o widget não é recriado; use _MEIQIA('manualInit') para parar o auto-init e chame _MEIQIA('init') num hook de rota (useEffect / mounted) para remontá-lo.
Problemas de exibiçãoconflito de estilo · empilhamento · plugins de terceiros
Carregado mas invisível: normalmente o CSS global do site sobrescreve a posição do balão, ou um plugin de heatmap / analytics / SEO edita o DOM e cobre o contêiner; F12 → Elements, busque o contêiner meiqia e veja display:none, z-index perdido ou coordenadas fora da tela.
Mobile / SDKweb mobile · AppKey · push
Web mobile / PC é o mesmo snippet mas precisa de deploy próprio; in-app usa o SDK nativo (primeiro «Adicionar config APP» no console para um AppKey); push se divide em «sem push» (só in-app) e «servidor de push próprio» (entregue mesmo após sair do app).
Chamadas de APIwithoutBtn · showPanel · dados do cliente
Botão próprio? _MEIQIA('withoutBtn') oculta o botão nativo, e chame _MEIQIA('showPanel') ao clicar para abrir o chat; passe / sincronize dados do cliente dentro do tempo de init, ou não tem efeito.
Fig 1: triagem do 美洽 não aparece — verifique a carga do script (meiqia.js no F12), depois carga / config / framework / exibição
Passo 2: a causa raiz mais ignorada → L2 (o widget = injeção JS assíncrona de terceiros fora do domínio)
Uma ideia basta: o widget web do 美洽 não é um componente estático embutido na sua página — é um meiqia.js carregado de forma assíncrona do domínio externo do 美洽 que então injeta dinamicamente um contêiner de chat (DOM / iframe) e abre uma conexão persistente de origem cruzada com os servidores do 美洽. Isso explica a maioria dos «sumiços misteriosos»: ① é um script de terceiros fora do domínio, então AdBlock / uBlock o bloqueiam por suas listas de «rastreamento / anúncios» (ERR_BLOCKED_BY_CLIENT) e o botão nunca surge (embora o console pareça ok); ② injeta o DOM de forma assíncrona: no <head> bloqueia, uma troca de rota SPA destrói o contêiner e ele não é recriado sozinho (use manualInit + _MEIQIA('init')), e plugins de heatmap / analytics que editam o DOM podem cobri-lo; ③ vincula-se à sua empresa via entId e é controlado por lista branca de domínios: com entId errado ou domínio não autorizado o script carrega mas «não conecta um chat»; ④ mobile e PC são duas integrações distintas, in-app é o SDK (AppKey), e o push se divide em «sem push» vs «servidor de push próprio». Uma vez vista essa cadeia de injeção, cada sintoma abaixo tem uma única lógica. Abaixo o painel de autoverificação; mais abaixo os cinco métodos e as estimativas 2026.
Fig 2: painel de autoverificação de integração do 美洽 (verde = confirmado / vermelho = facilmente ignorado)Fig: verifique «posição do código + meiqia.js 200 + inicializado» primeiro, depois «adblock + framework/empilhamento» — os dois últimos são os mais ignorados
Tabela completa de sintomas (comportamento / posicionamento oficial · causa raiz L2)
Cinco métodos de integração do 美洽 comparados (código / dificuldade / recursos / cenário / tempo no ar · doc oficial)
Método de integração
Código / dificuldade
Recursos completos
Melhor para
Tempo no ar
Widget JS web
um snippet JS · baixo
o mais completo (flutuante / popup / saudação automática / trilha do visitante)
sites PC + mobile (recomendado oficial)
~3-5 min
Link de chat
sem código · mínimo
chat básico
sem técnica / soltar um link de chat rápido
instantâneo
API / SDK WebIM
precisa de dev · alto
personalização profunda (UI própria / sistema / integração de pedidos)
times com capacidade de dev para fusão profunda
conforme dev
SDK nativo de app
integrar SDK · alto
chat in-app + push de mensagens
apps iOS / Android
conforme dev
Config rápida CMS
plugin / um clique · baixo
igual ao widget JS
sites WordPress / Fkw / Shopify
minutos
美洽 causas de não aparecer & comparativo de métodos de integração (estimativa 2026)
A seguir estão estimativas 2026 sintetizadas da ajuda oficial do 美洽 (Canais de acesso / API do widget web JavaScript) e do troubleshooting público de integração (não são compromissos do fornecedor nem medição de primeira mão; para referência, mudam por versão e política do navegador):
Dimensão
Estimativa / comparação
Distribuição das causas de não aparecer (comunidade / tickets · est.)
posição / não carregado ~35% > adblock / extensão do navegador ~25% > config / autorização (entId / domínio) ~20% > framework (SPA) ~12% > conflito de estilo / plugin de terceiros ~8%
O que é realmente a integração
o widget web = JS assíncrono de terceiros fora do domínio injetando o DOM + uma conexão persistente de origem cruzada (não um componente estático embutido); daí o efeito de posição, regras de adblock, empilhamento CSS, ciclo de vida SPA
Integração por plataforma (est.)
web PC / mobile = widget JS (mesmo código, deployado à parte); app = SDK nativo (AppKey); WeChat / Douyin / RED = integração autorizada por canal
Impacto do adblock (est.)
cerca de 30-40% dos usuários PC usam uma extensão de adblock → o script de chat de terceiros é bloqueado por regras de anúncio (ERR_BLOCKED_BY_CLIENT), causa principal de «console ok, lado do usuário ausente»
Tempo no ar do widget JS (oficial)
cole o JS dedicado no fim da página e ele entra no ar em cerca de 3-5 minutos; entId é o id único da empresa, e uma divergência com o painel deixa os atendentes sem chats
Base da estimativa: linha de base de fontes + extrapolação temporal (meiqia.com/help Canais de acesso / widget web JavaScript, guia de integração meiqia.im, troubleshooting público, 2026); muda com a versão e a política de bloqueio do navegador. Siga as informações oficiais mais recentes do 美洽. Não oficial · localização LLM.
Casos reais — leitura rápida
Código colado mas sem balão de chat: primeiro F12 → Network, busque meiqia.js — sem requisição ou não-200 significa mal posicionado / retido por cache; limpe o cache CDN ou reabra em anônima.
O console diz meiqia.js net::ERR_BLOCKED_BY_CLIENT: um adblock (AdBlock / uBlock / AdGuard) bloqueou o script de chat de terceiros por suas regras de anúncio — desative a extensão ou whitelist o site; por isso «falta para alguns usuários enquanto seu console parece ok».
Script carregado (console typeof _MEIQIA é function) mas sem botão: normalmente um CSS de tema empurrou o balão para fora da tela ou um plugin de heatmap / analytics mudou o empilhamento do DOM — F12 → Elements, busque o contêiner do 美洽 e verifique item a item.
A home tem chat numa SPA Vue / React, mas uma segunda rota não: a troca de rota SPA destruiu o contêiner e o widget não foi recriado — use manualInit para parar o auto-init e chame _MEIQIA('init') no hook de rota para remontar.
O chat abre mas os atendentes não recebem mensagens de visitantes: muito provavelmente o entId não bate com o painel (copiou snippet de outro / misturou contas) — compare o ID da empresa em Config - Equipe - busca de ID com o entId do código.
Funciona no staging, não carrega no domínio de produção: o domínio de produção não foi autorizado via «Adicionar site de integração» — adicione o domínio ao vivo à lista e republique.
Quer remover o botão redondo nativo do 美洽 e usar seu próprio botão «Falar com suporte»: chame _MEIQIA('withoutBtn') para ocultar o nativo, depois vincule _MEIQIA('showPanel') ao seu botão para abrir o chat.
