Passo 1: dividi in quattro gruppi (caricamento / config / framework / visualizzazione)
Qualunque sia il tuo «la chat non è comparsa», restringilo prima a quattro gruppi — solo questo risparmia la maggior parte delle deviazioni. Il diagramma di flusso chiarisce la decisione: verifica se lo script ha caricato (meiqia.js in F12), poi se è config, framework o un problema di livello di visualizzazione. Per le basi vedi la guida all'integrazione web di 美洽.
Come funziona l'integrazione: perché questa iniezione JS fallisce / viene bloccata
Basta una frase: il widget web di 美洽 non è un componente statico nella tua pagina — è un meiqia.js caricato in modo asincrono dal dominio esterno di 美洽 che inietta dinamicamente un contenitore di chat (DOM / iframe) e apre una connessione persistente cross-origin. Perché l'iniezione riesca servono «lo script caricato (buona posizione, niente adblock), il contenitore non coperto da CSS / altri plugin, entId e dominio corrispondenti, e il rimontaggio dopo un cambio rotta SPA». Il diagramma sotto disegna questa catena e quattro punti di blocco — ecco perché lo stesso codice funziona su un sito / framework ma non su un altro.
Codice ben posizionato ma ancora non visibile: esegui il pannello di autoverifica dell'integrazione
Se posizione, meiqia.js 200 ed entId sono tutti confermati ma ancora non si mostra, è fondamentalmente «adblock» o «framework / impilamento». Il pannello sotto è ordinato per importanza: il verde di solito è a posto, i rossi (adblock, impilamento SPA / plugin di terze parti) sono le trappole frequenti. Verificarli voce per voce localizza in fretta.
Tabella completa dei sintomi (comportamento / posizionamento ufficiale · causa radice L2)
La tabella sotto elenca in un colpo i sintomi comuni di non visualizzazione / errore, ciascuno con il suo posizionamento ufficiale e causa radice L2. Il campo di ricerca sopra è alimentato dai dati di questa tabella — cerca la parola chiave incontrata.
| Sintomo | Gruppo | Comportamento L1 / posizionamento ufficiale | Causa radice L2 |
|---|---|---|---|
| La finestra / bolla di chat non si mostra affatto | Errore di caricamento | Il widget web di 美洽 carica una finestra di chat fluttuante con un singolo snippet JS incollato; conferma che il codice sia ben incorporato e il sito di integrazione configurato nella console. | Il widget è meiqia.js iniettato nel DOM dopo un caricamento asincrono, quindi «niente del tutto» di solito significa «lo script non si è mai caricato»: posizione errata, bloccato da adblock / cache, o dominio / entId non corrispondenti, quindi l'iniezione non è mai avvenuta. |
| Script caricato ma manca il pulsante di chat | Problemi di visualizzazione | Il codice del widget si adatta al sito e mostra un pulsante di chat; se la visualizzazione fallisce, controlla se è nascosto dagli stili o se l'inizializzazione è stata interrotta. | Se lo script carica ma manca il pulsante, di solito è un problema di «livello di visualizzazione»: il CSS globale sovrascrive la posizione del pulsante / mette display:none, lo z-index perde, o un altro elemento fisso lo copre; un altro errore JS può anche interrompere l'inizializzazione. |
| meiqia.js bloccato da un'estensione adblock | Errore di caricamento | Lo script di chat di 美洽 proviene da un dominio di terze parti; se è installata un'estensione di blocco, può trattarlo come pubblicità / tracker e impedire il caricamento — disattiva il blocco o whitelist. | ERR_BLOCKED_BY_CLIENT significa che un'estensione del browser (AdBlock / uBlock / AdGuard) ha bloccato la richiesta con le sue liste di filtri. Lo script di 美洽 è «terze parti fuori dominio + comunicazione in tempo reale», che queste regole spesso scambiano per pubblicità / tracker, causando un falso fallimento «console a posto, lato utente assente». |
| meiqia.js 404 / stato errato / contenuto misto | Errore di caricamento | Dopo il deploy, cerca meiqia.js nel pannello Network; uno stato 200 significa che lo script è ben posizionato e caricato. | Cause comuni di non-200: codice trattenuto da cache pagina / CDN (non aggiornata dopo la pubblicazione), caricamento su pagina HTTP / catena di certificati incompleta che scatena il blocco contenuto misto, o codice rotto / copiato parzialmente. Se questo passo fallisce, iniezione e connessione non avvengono mai. |
| Codice mal posizionato (blocco in head / senza effetto) | Errore di caricamento | 美洽 raccomanda di incollare il codice in fondo alla pagina, prima di </body>; il widget gira dopo il caricamento del contenuto principale. | Il widget deve iniettare il contenitore dopo che il DOM è pronto. In <head> blocca il render (schermo bianco prima su rete lenta) o gira prima che il DOM sia pronto e fallisce; in qualche scope async / di modulo anche l'ordine di caricamento può andare storto. |
| Stile della finestra / pulsante di chat rotto | Problemi di visualizzazione | Il widget inietta i propri stili e si adatta al sito; conflitti con stili globali possono causare anomalie visive. | Lo script di 美洽 inietta CSS a runtime; se gli stili globali (selettori universali / regole ad alta priorità / reset) sovrascrivono prima le sue classi, posizione, impilamento e font si rompono — un effetto collaterale di «iniezione dinamica + condivisione di un unico spazio di stile del documento». |
| Pulsante fuori schermo / coperto | Problemi di visualizzazione | Il pulsante del widget appare come fluttuante a posizione fissa; se coperto da altri elementi fissi, regola l'impilamento o la posizione. | Altri elementi position:fixed del sito (torna su, pubblicità fluttuanti, una barra di supporto propria) con z-index maggiore coprono il pulsante di 美洽, o il tema calcola male le sue coordinate, lasciandolo «fuori schermo / coperto». |
| Conflitto DOM con plugin / analytics di terze parti | Problemi di visualizzazione | Altri script della pagina che modificano il DOM o intercettano richieste possono influire sul caricamento e la visualizzazione normali del widget. | Gli script di heatmap / analytics / conversione riscrivono il DOM, iniettano overlay o intercettano richieste; poiché loro e 美洽 iniettano nello stesso documento, impilamento / eventi interferiscono e il contenitore di 美洽 viene coperto o il suo init interrotto. |
| Il widget sparisce dopo un cambio rotta SPA | Integrazione framework | Per le app a pagina singola (SPA), usa gli hook di rotta del framework per caricare / inizializzare il widget di 美洽 così da adattarsi al routing del front. | Una SPA cambia viste via routing del front, distruggendo / ricreando il DOM, ma meiqia.js inietta una volta al primo caricamento di default e non viene ricreato da solo al cambio rotta, quindi «cambi pagina, la chat sparisce». |
| Init manuale necessario (manualInit / init) | Integrazione framework | Aggiungi _MEIQIA('manualInit') dopo il codice di embed di 美洽 per fermare l'auto-init dopo il download; chiama _MEIQIA('init') per inizializzare manualmente quando serve. | Di default 美洽 si auto-inizializza subito dopo il download; quando ti serve il contenitore pronto / i dati cliente passati / la rotta stabile prima, quella tempistica è «troppo presto» — passa all'init manuale per controllare la sequenza. |
| entId non corrisponde / gli agenti non ricevono chat | Config / autorizzazione | Il numero dopo entId nel codice è l'id univoco della tua azienda; se non corrisponde alla workbench, gli agenti non possono gestire la chat — trova l'ID azienda in Impostazioni - Team - ricerca ID. | entId lega lo snippet a uno specifico account aziendale. Con codice di altri / di un altro ambiente, o account confusi, il front carica la finestra ma i messaggi vanno a «un'altra azienda», quindi questa workbench non ne riceve nessuno — il classico «sembra a posto ma non riceve nulla». |
| Dominio del sito non autorizzato nella console | Config / autorizzazione | La console di 美洽 permette «Aggiungi sito di integrazione», ciascuno con la sua config; un sito nuovo va configurato nella console prima di integrarsi bene. | 美洽 gestisce più siti come «siti di integrazione»; il dominio va registrato / autorizzato nella console per essere riconosciuto. Un nuovo dominio di produzione non aggiunto può non essere accettato o mappato alla config sbagliata. |
| Multi-sito / sotto-canale (sonda) incrociato | Config / autorizzazione | 美洽 supporta il deploy di widget e link di chat diversi per sito (sotto-canali / sonda); oltre al sito predefinito puoi aggiungerne altri, ciascuno con la sua config. | Linee di business diverse richiedono gruppi di agenti / messaggi automatici diversi, ma se ogni sito condivide l'unico snippet predefinito, le origini non si distinguono e le config si incrociano. I sotto-canali (sonda) sono pensati per «un'azienda, più ingressi, instradati». |
| Chat web mobile non si mostra / richiede deploy a parte | Mobile / SDK | Il codice del widget si adatta al sito; mobile / PC usano lo stesso snippet ma vanno distribuiti separatamente. | Molti team hanno pagine / template PC e mobile separati e hanno incollato il codice solo nel template PC. Lo snippet è lo stesso e si autoadatta, ma il passo di «incollare» va fatto anche nel template mobile; omesso, il mobile non ha chat. |
| Integrazione dell'SDK nativo di app / AppKey | Mobile / SDK | L'integrazione in-app richiede un AppKey dalla workbench di 美洽 (Impostazioni - Integrazione - SDK, «Aggiungi config APP»), e gli sviluppatori integrano l'SDK iOS / Android secondo la doc e il demo ufficiali. | Un'app usa l'SDK nativo, non JS web: prima «Aggiungi config APP» per un AppKey, poi integra l'SDK per piattaforma per la UI di chat, non letti, push, ecc. — un percorso del tutto diverso dal widget web. |
| Il push di messaggi dell'SDK non arriva | Mobile / SDK | Il push dell'SDK di 美洽 ha due modalità: con «niente push», i messaggi dell'agente arrivano solo dentro l'app (aprila per ricevere); con un «server push personalizzato», gli utenti ricevono push sul telefono anche dopo aver lasciato l'app. | La mancanza di «push offline» di solito significa che la modalità push è «niente push», o manca il server push personalizzato / i certificati push per piattaforma. Il percorso è «美洽 → server dell'app → telefono dell'utente»; un anello mancante lascia solo la ricezione in-app. |
| Nascondere il pulsante predefinito / ingresso proprio | Chiamate API | Chiama _MEIQIA('withoutBtn') per non mostrare il pulsante nativo di 美洽; dopo un init riuscito, chiama _MEIQIA('showPanel') per aprire la chat. | Di default viene renderizzato il pulsante fluttuante nativo; per usare il tuo ingresso devi dichiarare «nessun pulsante nativo» prima / durante l'init e legare «apri chat» al tuo elemento — una questione di tempistica API, non un «pulsante rotto». |
| Passare / sincronizzare i dati cliente senza effetto | Chiamate API | Il widget web di 美洽 offre le API «passare dati cliente», «sincronizzare identità cliente» e «aggiungere info evento personalizzata» per portare i dati del visitatore nella chat. | Queste API vanno chiamate entro la tempistica di init corretta: dopo un init riuscito (o nella tempistica manualInit + init). Troppo presto / tardi, o formati di campo errati, e resta «impostato ma senza effetto». |
美洽 cause di non visualizzazione & confronto dei metodi di integrazione (stima 2026)
Le seguenti sono stime 2026 sintetizzate dall'aiuto ufficiale di 美洽 (Canali di accesso / API del widget web JavaScript) e dal troubleshooting pubblico di integrazione (non sono impegni del fornitore né misurazioni dirette; di riferimento, cambiano per versione e policy del browser):
| Dimensione | Stima / confronto |
|---|---|
| Distribuzione delle cause di non visualizzazione (community / ticket · st.) | posizione / non caricato ~35% > adblock / estensione del browser ~25% > config / autorizzazione (entId / dominio) ~20% > framework (SPA) ~12% > conflitto di stile / plugin di terze parti ~8% |
| Cosa è davvero l'integrazione | il widget web = JS asincrono di terze parti fuori dominio che inietta il DOM + una connessione persistente cross-origin (non un componente statico incorporato); da qui l'effetto di posizione, regole adblock, impilamento CSS, ciclo di vita SPA |
| Integrazione per piattaforma (st.) | web PC / mobile = widget JS (stesso codice, distribuito a parte); app = SDK nativo (AppKey); WeChat / Douyin / RED = integrazione autorizzata per canale |
| Impatto dell'adblock (st.) | circa il 30-40% degli utenti PC usa un'estensione adblock → lo script di chat di terze parti viene bloccato dalle regole pubblicitarie (ERR_BLOCKED_BY_CLIENT), causa principale di «console a posto, lato utente assente» |
| Tempo di attivazione del widget JS (ufficiale) | incolla il JS dedicato in fondo alla pagina e va in attivazione in circa 3-5 minuti; entId è l'id univoco dell'azienda, e una discrepanza con la workbench lascia gli agenti senza chat |
Base della stima: baseline delle fonti + estrapolazione temporale (meiqia.com/help Canali di accesso / widget web JavaScript, guida all'integrazione meiqia.im, troubleshooting pubblico, 2026); cambia con la versione e la policy di blocco del browser. Segui le informazioni ufficiali più recenti di 美洽. Non ufficiale · localizzazione LLM.
Cinque metodi di integrazione di 美洽 a confronto (codice / difficoltà / funzioni / scenario / tempo di attivazione)
Quale metodo di integrazione? Il confronto sotto sintetizza la doc ufficiale di 美洽 per un riferimento incrociato rapido (volume di codice, funzioni, miglior adattamento, tempo di attivazione). La maggior parte dei siti sceglie il «widget JS web».
| Metodo di integrazione | Codice / difficoltà | Funzioni complete | Ideale per | Tempo di attivazione |
|---|---|---|---|---|
| Widget JS web | uno snippet JS · basso | il più completo (fluttuante / popup / saluto automatico / traccia visitatore) | siti PC + mobile (consigliato ufficiale) | ~3-5 min |
| Link di chat | senza codice · minimo | chat di base | senza tecnica / mettere un link di chat rapido | istantaneo |
| API / SDK WebIM | richiede dev · alto | personalizzazione profonda (UI propria / sistema / integrazione ordini) | team con capacità dev per fusione profonda | secondo dev |
| SDK nativo di app | integrare SDK · alto | chat in-app + push di messaggi | app iOS / Android | secondo dev |
| Config rapida CMS | plugin / un clic · basso | come il widget JS | siti WordPress / Fkw / Shopify | minuti |
Canale / scenario → mappa del risultato di integrazione
Lo stesso 美洽 si integra in modo diverso per canale / scenario. La mappa sotto mostra canali comuni: verde = incolla e vai, ambra = serve setup (deploy a parte / init / whitelist), rosso = cambia metodo di default (adblock / entId / l'app usa l'SDK).
Domande frequenti
美洽 La finestra / bolla di chat non si mostra affatto — come si risolve?
Il widget web di 美洽 carica una finestra di chat fluttuante con un singolo snippet JS incollato; conferma che il codice sia ben incorporato e il sito di integrazione configurato nella console. Il widget è meiqia.js iniettato nel DOM dopo un caricamento asincrono, quindi «niente del tutto» di solito significa «lo script non si è mai caricato»: posizione errata, bloccato da adblock / cache, o dominio / entId non corrispondenti, quindi l'iniezione non è mai avvenuta. F12 → Network, cerca meiqia.js: nessuna richiesta → codice senza effetto (controlla la posizione / svuota la cache); richiesta ma non-200 → bloccato o problema di percorso; tutto a posto ma ancora nascosto → controlla entId / autorizzazione dominio e i gruppi sotto.
美洽 Script caricato ma manca il pulsante di chat — come si risolve?
Il codice del widget si adatta al sito e mostra un pulsante di chat; se la visualizzazione fallisce, controlla se è nascosto dagli stili o se l'inizializzazione è stata interrotta. Se lo script carica ma manca il pulsante, di solito è un problema di «livello di visualizzazione»: il CSS globale sovrascrive la posizione del pulsante / mette display:none, lo z-index perde, o un altro elemento fisso lo copre; un altro errore JS può anche interrompere l'inizializzazione. F12 → Elements, trova il contenitore di 美洽 — presente, nascosto o fuori schermo?; disabilita temporaneamente CSS / script propri per ritestare; controlla la console per un errore che ha interrotto l'esecuzione.
美洽 meiqia.js bloccato da un'estensione adblock — come si risolve?
Lo script di chat di 美洽 proviene da un dominio di terze parti; se è installata un'estensione di blocco, può trattarlo come pubblicità / tracker e impedire il caricamento — disattiva il blocco o whitelist. ERR_BLOCKED_BY_CLIENT significa che un'estensione del browser (AdBlock / uBlock / AdGuard) ha bloccato la richiesta con le sue liste di filtri. Lo script di 美洽 è «terze parti fuori dominio + comunicazione in tempo reale», che queste regole spesso scambiano per pubblicità / tracker, causando un falso fallimento «console a posto, lato utente assente». Ritesta in incognito o con l'adblock off — se appare, il blocco era la causa; chiedi agli utenti di whitelist il sito; il front può caricare lo script di chat in modo ritardato / condizionale per aggirare alcune regole automatiche.
美洽 meiqia.js 404 / stato errato / contenuto misto — come si risolve?
Dopo il deploy, cerca meiqia.js nel pannello Network; uno stato 200 significa che lo script è ben posizionato e caricato. Cause comuni di non-200: codice trattenuto da cache pagina / CDN (non aggiornata dopo la pubblicazione), caricamento su pagina HTTP / catena di certificati incompleta che scatena il blocco contenuto misto, o codice rotto / copiato parzialmente. Se questo passo fallisce, iniezione e connessione non avvengono mai. Svuota la cache CDN / browser (o incognito) dopo la pubblicazione; assicura HTTPS completo con catena di certificati integra e senza contenuto misto; verifica che il codice copiato sia completo e non escaped.
美洽 Codice mal posizionato (blocco in head / senza effetto) — come si risolve?
美洽 raccomanda di incollare il codice in fondo alla pagina, prima di </body>; il widget gira dopo il caricamento del contenuto principale. Il widget deve iniettare il contenitore dopo che il DOM è pronto. In <head> blocca il render (schermo bianco prima su rete lenta) o gira prima che il DOM sia pronto e fallisce; in qualche scope async / di modulo anche l'ordine di caricamento può andare storto. Metti il JS di 美洽 nel footer comune di ogni pagina, prima di </body>; per le SPA vedi la voce «rotta SPA» e usa manualInit; assicurati che un bundler non lo elimini con il tree-shaking.
美洽 Stile della finestra / pulsante di chat rotto — come si risolve?
Il widget inietta i propri stili e si adatta al sito; conflitti con stili globali possono causare anomalie visive. Lo script di 美洽 inietta CSS a runtime; se gli stili globali (selettori universali / regole ad alta priorità / reset) sovrascrivono prima le sue classi, posizione, impilamento e font si rompono — un effetto collaterale di «iniezione dinamica + condivisione di un unico spazio di stile del documento». F12 per vedere quale regola del sito sovrascrive il contenitore di 美洽; restringi gli stili globali / riduci l'impatto sulle classi generiche; se serve, chiedi a 美洽 di regolare l'impilamento del contenitore.
美洽 Pulsante fuori schermo / coperto — come si risolve?
Il pulsante del widget appare come fluttuante a posizione fissa; se coperto da altri elementi fissi, regola l'impilamento o la posizione. Altri elementi position:fixed del sito (torna su, pubblicità fluttuanti, una barra di supporto propria) con z-index maggiore coprono il pulsante di 美洽, o il tema calcola male le sue coordinate, lasciandolo «fuori schermo / coperto». Seleziona il contenitore di 美洽 in F12 per vedere coordinate / z-index reali; alzalo o abbassa lo z-index dell'elemento che copre; evita di impilare più fluttuanti fissi in un angolo.
美洽 Conflitto DOM con plugin / analytics di terze parti — come si risolve?
Altri script della pagina che modificano il DOM o intercettano richieste possono influire sul caricamento e la visualizzazione normali del widget. Gli script di heatmap / analytics / conversione riscrivono il DOM, iniettano overlay o intercettano richieste; poiché loro e 美洽 iniettano nello stesso documento, impilamento / eventi interferiscono e il contenitore di 美洽 viene coperto o il suo init interrotto. Disabilita i plugin sospetti uno a uno per localizzare il conflitto; regola ordine di caricamento / impilamento del contenitore; fai sì che le heatmap evitino l'area del contenitore di 美洽.
美洽 Il widget sparisce dopo un cambio rotta SPA — come si risolve?
Per le app a pagina singola (SPA), usa gli hook di rotta del framework per caricare / inizializzare il widget di 美洽 così da adattarsi al routing del front. Una SPA cambia viste via routing del front, distruggendo / ricreando il DOM, ma meiqia.js inietta una volta al primo caricamento di default e non viene ricreato da solo al cambio rotta, quindi «cambi pagina, la chat sparisce». Usa _MEIQIA('manualInit') per fermare l'auto-init e chiama _MEIQIA('init') in un hook di rotta (React useEffect / Vue mounted / router afterEach) per rimontare su richiesta; evita di inizializzare più istanze.
美洽 Init manuale necessario (manualInit / init) — come si risolve?
Aggiungi _MEIQIA('manualInit') dopo il codice di embed di 美洽 per fermare l'auto-init dopo il download; chiama _MEIQIA('init') per inizializzare manualmente quando serve. Di default 美洽 si auto-inizializza subito dopo il download; quando ti serve il contenitore pronto / i dati cliente passati / la rotta stabile prima, quella tempistica è «troppo presto» — passa all'init manuale per controllare la sequenza. Aggiungi _MEIQIA('manualInit') dopo il codice; chiama _MEIQIA('init') quando le condizioni sono pronte (DOM / sessione / rotta); chiama le API dati in ordine entro il tempo di init secondo la doc.
Più setup di integrazione: integrazione web di 美洽, integrazione SDK di APP; per iniziare: guida di 美洽. Una versione completa ricercabile (incl. questo strumento) anche su troubleshooting di integrazione di 美洽 (GitHub Pages).