Passo 1: divida em quatro grupos (carga / config / framework / exibição)
Qualquer que seja o seu «o chat não veio», restrinja primeiro a quatro grupos — só isso poupa a maioria dos desvios. O fluxograma esclarece a decisão: verifique se o script sequer carregou (meiqia.js no F12), depois se é config, framework ou um problema de camada de exibição. Para o básico veja o guia de integração web do 美洽.
Como funciona a integração: por que esta injeção JS falha / é bloqueada
Uma frase basta: o widget web do 美洽 não é um componente estático na sua página — é um meiqia.js carregado de forma assíncrona do domínio externo do 美洽 que injeta dinamicamente um contêiner de chat (DOM / iframe) e abre uma conexão persistente de origem cruzada. Para a injeção funcionar precisa de «o script carregado (boa posição, sem adblock), o contêiner não coberto por CSS / outros plugins, entId e domínio batendo, e remontagem após uma troca de rota SPA». O diagrama abaixo desenha essa cadeia e quatro pontos de bloqueio — por isso o mesmo código funciona num site / framework mas não em outro.
Código bem posicionado mas ainda não aparece: rode o painel de autoverificação de integração
Se posição, meiqia.js 200 e entId estão todos confirmados mas ainda não aparece, basicamente é «adblock» ou «framework / empilhamento». O painel abaixo está ordenado por importância: verde costuma estar ok, os vermelhos (adblock, empilhamento SPA / plugin de terceiros) são as armadilhas frequentes. Verificar item a item localiza rápido.
Tabela completa de sintomas (comportamento / posicionamento oficial · causa raiz L2)
A tabela abaixo lista de uma vez os sintomas comuns de não aparecer / erro, cada um com seu posicionamento oficial e causa raiz L2. A caixa de busca acima é alimentada pelos dados desta tabela — busque a palavra-chave que encontrou.
| Sintoma | Grupo | Comportamento L1 / posicionamento oficial | Causa raiz L2 |
|---|---|---|---|
| Janela / balão de chat não aparece de jeito nenhum | Falha de carga | O widget web do 美洽 carrega uma janela de chat flutuante com um único snippet JS colado; confirme que o código está bem embutido e o site de integração configurado no console. | O widget é meiqia.js injetado no DOM após carga assíncrona, então «nada de nada» costuma significar «o script nunca carregou»: posição errada, bloqueado por adblock / cache, ou domínio / entId divergentes, então a injeção nunca rodou. |
| Script carregou mas falta o botão de chat | Problemas de exibição | O código do widget se adapta ao site e mostra um botão de chat; se a exibição falhar, verifique se está oculto por estilos ou se a inicialização foi interrompida. | Se o script carrega mas falta o botão, costuma ser problema de «camada de exibição»: o CSS global sobrescreve a posição / coloca display:none, o z-index perde, ou outro elemento fixo o cobre; outro erro JS também pode abortar a inicialização. |
| meiqia.js bloqueado por uma extensão de adblock | Falha de carga | O script de chat do 美洽 vem de um domínio de terceiros; se há uma extensão de bloqueio instalada, ela pode tratá-lo como anúncio / rastreador e impedir a carga — desative o bloqueio ou whitelist. | ERR_BLOCKED_BY_CLIENT significa que uma extensão do navegador (AdBlock / uBlock / AdGuard) bloqueou a requisição por suas listas de filtros. O script do 美洽 é «terceiros fora do domínio + comunicação em tempo real», que essas regras costumam confundir com anúncio / rastreador, causando falha falsa «console ok, lado do usuário ausente». |
| meiqia.js 404 / status ruim / conteúdo misto | Falha de carga | Após o deploy, busque meiqia.js no painel Network; um status 200 significa que o script está bem posicionado e carregado. | Causas comuns de não-200: código retido por cache de página / CDN (sem atualizar após publicar), carga em página HTTP / cadeia de certificado incompleta disparando bloqueio de conteúdo misto, ou código quebrado / copiado parcialmente. Com este passo falho, injeção e conexão nunca ocorrem. |
| Código mal posicionado (bloqueio no head / sem efeito) | Falha de carga | O 美洽 recomenda colar o código no fim da página, antes de </body>; o widget roda após o conteúdo principal carregar. | O widget precisa injetar seu contêiner após o DOM estar pronto. No <head> bloqueia o render (tela branca primeiro em rede lenta) ou roda antes do DOM pronto e falha; dentro de algum escopo async / de módulo a ordem de carga também pode dar errado. |
| Estilo da janela / botão de chat quebrado | Problemas de exibição | O widget injeta seus próprios estilos e se adapta ao site; conflitos com estilos globais podem causar falhas visuais. | O script do 美洽 injeta CSS em tempo de execução; se estilos globais (seletores universais / regras de alta prioridade / resets) sobrescrevem suas classes primeiro, posição, empilhamento e fontes quebram — efeito colateral de «injeção dinâmica + compartilhar um mesmo espaço de estilo do documento». |
| Botão fora da tela / coberto | Problemas de exibição | O botão do widget aparece como flutuante de posição fixa; se coberto por outros elementos fixos, ajuste o empilhamento ou a posição. | Outros elementos position:fixed do site (voltar ao topo, anúncios flutuantes, uma barra de suporte própria) com z-index maior cobrem o botão do 美洽, ou o tema calcula mal suas coordenadas, deixando-o «fora da tela / coberto». |
| Conflito de DOM com plugin / analytics de terceiros | Problemas de exibição | Outros scripts da página que modificam o DOM ou interceptam requisições podem afetar a carga e exibição normais do widget. | Scripts de heatmap / analytics / conversão reescrevem o DOM, injetam overlays ou interceptam requisições; como eles e o 美洽 injetam no mesmo documento, empilhamento / eventos interferem e o contêiner do 美洽 é coberto ou seu init interrompido. |
| O widget some após troca de rota SPA | Integração de framework | Para apps de página única (SPA), use os hooks de rota do framework para carregar / iniciar o widget do 美洽 para encaixar no roteamento do front. | Uma SPA troca de vistas via roteamento do front, destruindo / recriando o DOM, mas meiqia.js injeta uma vez na primeira carga por padrão e não é recriado sozinho na troca de rota, então «troca de página, chat some». |
| Init manual necessário (manualInit / init) | Integração de framework | Adicione _MEIQIA('manualInit') após o código de embed do 美洽 para parar o auto-init após o download; chame _MEIQIA('init') para iniciar manualmente quando preciso. | Por padrão o 美洽 auto-inicia logo após o download; quando você precisa do contêiner pronto / dados do cliente passados / a rota estável primeiro, esse momento é «cedo demais» — mude para init manual para controlar a sequência. |
| entId divergente / atendentes não recebem chats | Config / autorização | O número após entId no código é o id único da sua empresa; se não bate com o painel, os atendentes não conseguem atender o chat — ache o ID da empresa em Config - Equipe - busca de ID. | entId vincula o snippet a uma conta de empresa específica. Com código de outro / de outro ambiente, ou contas misturadas, o front carrega a janela mas as mensagens vão para «outra empresa», então este painel não recebe nenhuma — o clássico «parece ok mas não recebe nada». |
| Domínio do site não autorizado no console | Config / autorização | O console do 美洽 permite «Adicionar site de integração», cada um com sua config; um site novo deve ser configurado no console antes de integrar bem. | O 美洽 gerencia vários sites como «sites de integração»; o domínio deve ser registrado / autorizado no console para ser reconhecido. Um domínio de produção novo não adicionado pode não ser aceito ou mapeado para a config errada. |
| Multi-site / subcanal (sonda) cruzado | Config / autorização | O 美洽 suporta deploy de widgets e links de chat diferentes por site (subcanais / sonda); além do site padrão você pode adicionar mais, cada um com sua config. | Linhas de negócio diferentes precisam de grupos de atendentes / mensagens automáticas diferentes, mas se cada site compartilha o único snippet padrão, as origens não se distinguem e as configs se cruzam. Subcanais (sonda) são feitos para «uma empresa, várias entradas, roteadas». |
| Chat web mobile não aparece / precisa de deploy à parte | Mobile / SDK | O código do widget se adapta ao site; mobile / PC usam o mesmo snippet mas devem ser deployados separadamente. | Muitas equipes têm páginas / templates PC e mobile separados e só colaram o código no template PC. O snippet é o mesmo e se autoadapta, mas o passo de «colar» deve acontecer também no template mobile; omitido, o mobile não tem chat. |
| Integração do SDK nativo de app / AppKey | Mobile / SDK | A integração in-app precisa de um AppKey do painel do 美洽 (Config - Integração - SDK, «Adicionar config APP»), e os devs integram o SDK iOS / Android conforme a doc e o demo oficiais. | Um app usa o SDK nativo, não JS web: primeiro «Adicionar config APP» para um AppKey, depois integre o SDK por plataforma para a UI de chat, não lidas, push, etc. — um caminho totalmente diferente do widget web. |
| Push de mensagens do SDK não chega | Mobile / SDK | O push do SDK do 美洽 tem dois modos: com «sem push», as mensagens do atendente chegam só dentro do app (abra-o para receber); com um «servidor de push próprio», os usuários recebem push no celular mesmo após sair do app. | A falta de «push offline» costuma significar que o modo de push é «sem push», ou não há servidor de push próprio / certificados de push por plataforma. O caminho é «美洽 → servidor do app → celular do usuário»; um elo faltando deixa só recepção in-app. |
| Ocultar o botão padrão / entrada própria | Chamadas de API | Chame _MEIQIA('withoutBtn') para não mostrar o botão nativo do 美洽; após um init bem-sucedido, chame _MEIQIA('showPanel') para abrir o chat. | Por padrão o botão flutuante nativo é renderizado; para usar sua entrada você deve declarar «sem botão nativo» antes / durante o init e vincular «abrir chat» ao seu elemento — uma questão de tempo de API, não um «botão quebrado». |
| Passar / sincronizar dados do cliente sem efeito | Chamadas de API | O widget web do 美洽 oferece APIs «passar dados do cliente», «sincronizar identidade do cliente» e «adicionar info de evento personalizada» para levar dados do visitante ao chat. | Essas APIs devem ser chamadas dentro do tempo de init correto: após um init bem-sucedido (ou no tempo de manualInit + init). Cedo / tarde demais, ou formatos de campo errados, e fica «setado mas sem efeito». |
美洽 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.
Cinco métodos de integração do 美洽 comparados (código / dificuldade / recursos / cenário / tempo no ar)
Qual método de integração? O comparativo abaixo sintetiza a doc oficial do 美洽 para uma referência cruzada rápida (volume de código, recursos, melhor encaixe, tempo no ar). A maioria dos sites escolhe o «widget JS web».
| 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 |
Canal / cenário → mapa de resultado de integração
O mesmo 美洽 integra-se diferente por canal / cenário. O mapa abaixo mostra canais comuns: verde = colar e pronto, âmbar = precisa de setup (deploy à parte / init / whitelist), vermelho = trocar de método por padrão (adblock / entId / app usa SDK).
Perguntas frequentes
美洽 Janela / balão de chat não aparece de jeito nenhum — como resolver?
O widget web do 美洽 carrega uma janela de chat flutuante com um único snippet JS colado; confirme que o código está bem embutido e o site de integração configurado no console. O widget é meiqia.js injetado no DOM após carga assíncrona, então «nada de nada» costuma significar «o script nunca carregou»: posição errada, bloqueado por adblock / cache, ou domínio / entId divergentes, então a injeção nunca rodou. F12 → Network, busque meiqia.js: sem requisição → código sem efeito (verifique a posição / limpe o cache); requisição mas não-200 → bloqueado ou problema de caminho; tudo ok mas ainda oculto → verifique entId / autorização de domínio e os grupos abaixo.
美洽 Script carregou mas falta o botão de chat — como resolver?
O código do widget se adapta ao site e mostra um botão de chat; se a exibição falhar, verifique se está oculto por estilos ou se a inicialização foi interrompida. Se o script carrega mas falta o botão, costuma ser problema de «camada de exibição»: o CSS global sobrescreve a posição / coloca display:none, o z-index perde, ou outro elemento fixo o cobre; outro erro JS também pode abortar a inicialização. F12 → Elements, ache o contêiner do 美洽 — presente, oculto ou fora da tela?; desative temporariamente CSS / scripts próprios para retestar; veja no console um erro que abortou a execução.
美洽 meiqia.js bloqueado por uma extensão de adblock — como resolver?
O script de chat do 美洽 vem de um domínio de terceiros; se há uma extensão de bloqueio instalada, ela pode tratá-lo como anúncio / rastreador e impedir a carga — desative o bloqueio ou whitelist. ERR_BLOCKED_BY_CLIENT significa que uma extensão do navegador (AdBlock / uBlock / AdGuard) bloqueou a requisição por suas listas de filtros. O script do 美洽 é «terceiros fora do domínio + comunicação em tempo real», que essas regras costumam confundir com anúncio / rastreador, causando falha falsa «console ok, lado do usuário ausente». Reteste em anônima ou com o adblock off — se aparece, o bloqueio era a causa; peça aos usuários para whitelist o site; o front pode carregar o script de chat de forma adiada / condicional para driblar algumas regras automáticas.
美洽 meiqia.js 404 / status ruim / conteúdo misto — como resolver?
Após o deploy, busque meiqia.js no painel Network; um status 200 significa que o script está bem posicionado e carregado. Causas comuns de não-200: código retido por cache de página / CDN (sem atualizar após publicar), carga em página HTTP / cadeia de certificado incompleta disparando bloqueio de conteúdo misto, ou código quebrado / copiado parcialmente. Com este passo falho, injeção e conexão nunca ocorrem. Limpe o cache CDN / navegador (ou anônima) após publicar; garanta HTTPS completo com cadeia de certificado íntegra e sem conteúdo misto; verifique se o código copiado está completo e não escapado.
美洽 Código mal posicionado (bloqueio no head / sem efeito) — como resolver?
O 美洽 recomenda colar o código no fim da página, antes de </body>; o widget roda após o conteúdo principal carregar. O widget precisa injetar seu contêiner após o DOM estar pronto. No <head> bloqueia o render (tela branca primeiro em rede lenta) ou roda antes do DOM pronto e falha; dentro de algum escopo async / de módulo a ordem de carga também pode dar errado. Ponha o JS do 美洽 no rodapé comum de cada página, antes de </body>; para SPAs veja a entrada «rota SPA» e use manualInit; garanta que um bundler não o elimine por tree-shaking.
美洽 Estilo da janela / botão de chat quebrado — como resolver?
O widget injeta seus próprios estilos e se adapta ao site; conflitos com estilos globais podem causar falhas visuais. O script do 美洽 injeta CSS em tempo de execução; se estilos globais (seletores universais / regras de alta prioridade / resets) sobrescrevem suas classes primeiro, posição, empilhamento e fontes quebram — efeito colateral de «injeção dinâmica + compartilhar um mesmo espaço de estilo do documento». F12 para ver qual regra do site sobrescreve o contêiner do 美洽; restrinja os estilos globais / reduza o impacto em classes genéricas; se preciso, peça ao 美洽 ajustar o empilhamento do contêiner.
美洽 Botão fora da tela / coberto — como resolver?
O botão do widget aparece como flutuante de posição fixa; se coberto por outros elementos fixos, ajuste o empilhamento ou a posição. Outros elementos position:fixed do site (voltar ao topo, anúncios flutuantes, uma barra de suporte própria) com z-index maior cobrem o botão do 美洽, ou o tema calcula mal suas coordenadas, deixando-o «fora da tela / coberto». Selecione o contêiner do 美洽 no F12 para ver coordenadas / z-index reais; suba-o ou baixe o z-index do elemento que cobre; evite empilhar vários flutuantes fixos num canto.
美洽 Conflito de DOM com plugin / analytics de terceiros — como resolver?
Outros scripts da página que modificam o DOM ou interceptam requisições podem afetar a carga e exibição normais do widget. Scripts de heatmap / analytics / conversão reescrevem o DOM, injetam overlays ou interceptam requisições; como eles e o 美洽 injetam no mesmo documento, empilhamento / eventos interferem e o contêiner do 美洽 é coberto ou seu init interrompido. Desative plugins suspeitos um a um para localizar o conflito; ajuste ordem de carga / empilhamento do contêiner; faça heatmaps etc. evitarem a área do contêiner do 美洽.
美洽 O widget some após troca de rota SPA — como resolver?
Para apps de página única (SPA), use os hooks de rota do framework para carregar / iniciar o widget do 美洽 para encaixar no roteamento do front. Uma SPA troca de vistas via roteamento do front, destruindo / recriando o DOM, mas meiqia.js injeta uma vez na primeira carga por padrão e não é recriado sozinho na troca de rota, então «troca de página, chat some». Use _MEIQIA('manualInit') para parar o auto-init e chame _MEIQIA('init') num hook de rota (React useEffect / Vue mounted / router afterEach) para remontar sob demanda; evite iniciar várias instâncias.
美洽 Init manual necessário (manualInit / init) — como resolver?
Adicione _MEIQIA('manualInit') após o código de embed do 美洽 para parar o auto-init após o download; chame _MEIQIA('init') para iniciar manualmente quando preciso. Por padrão o 美洽 auto-inicia logo após o download; quando você precisa do contêiner pronto / dados do cliente passados / a rota estável primeiro, esse momento é «cedo demais» — mude para init manual para controlar a sequência. Adicione _MEIQIA('manualInit') após o código; chame _MEIQIA('init') quando as condições estiverem prontas (DOM / sessão / rota); chame as APIs de dados em ordem dentro do tempo de init conforme a doc.
Mais setup de integração: integração web do 美洽, integração SDK de APP; para começar: guia do 美洽. Uma versão completa com busca (incl. esta ferramenta) também em troubleshooting de integração do 美洽 (GitHub Pages).