그림: 美洽 채팅 연동 미표시 / 오류 조회 (L1 현상 + L2 근본 원인 + 5가지 연동 방식)
美洽(Meiqia)웹 채팅 위젯을 붙였는데 안 보이거나, 채팅 버튼이 안 나타나거나, 콘솔에 meiqia.js 차단이 뜨거나, 상담 백엔드에서 대화를 못 받나요? 먼저 세 가지를 구분하세요 — 스크립트가 아예 안 로드됐는지(배치 / 광고 차단 / 캐시), 로드됐지만 페이지 스타일·스태킹에 가려졌는지, 로드는 됐지만 설정이 안 맞는지(entId / 도메인 / SPA 생명주기). 겪고 있는 증상이나 키워드(예: not showing, adblock, entId, SPA, mobile, sdk push)를 조회해 먼저 L1 현상·공식 위치, 다음 L2 근본 원인·해결을 보세요. 설치 / 가이드는 美洽 다운로드 / 고객센터 연동 가이드 참고.
1단계: 스크립트가 로드됐는지 먼저 확인하고 네 갈래로 분류
美洽 채팅이 안 보일 때 열에 아홉은 네 갈래 중 하나입니다 — 먼저 스크립트가 로드됐는지 확인: F12 → Network에서 meiqia.js 검색, 요청이 없거나 200이 아니면 미로드. ① 로딩 실패 — 코드 위치 오류(</body> 앞이어야 함, <head> 아님), 광고 차단 규칙(ERR_BLOCKED_BY_CLIENT), CDN / 브라우저 캐시, HTTPS 인증서 / 혼합 콘텐츠. ② 설정 / 인증 — entId가 워크벤치와 불일치(로드는 되나 상담원이 대화를 못 받음), 사이트 도메인 미인증. ③ 프레임워크 연동 — Vue/React/Next SPA가 라우트 변경 시 컨테이너를 파괴, 위젯 미재생성. ④ 표시 / 모바일 / SDK — 사이트 CSS가 버블을 화면 밖으로, 제3자 플러그인이 DOM을 덮음, 모바일은 별도 배포, 앱 내부는 SDK. 더 자세한 설치는 美洽 사이트 연동 가이드.
로딩 실패위치 · 광고 차단 · 캐시 · HTTPS
美洽 JS를
앞에 붙이기(아님); F12 → Network에서 meiqia.js 상태 확인(200이어야 함); ERR_BLOCKED_BY_CLIENT는 보통 광고 차단 확장 — 시크릿 모드로 재시도하거나 화이트리스트; 게시 후 CDN 캐시 비우기; 전체 HTTPS·혼합 콘텐츠 없음 확인.
설정 / 인증entId · 도메인 화이트리스트 · 서브채널
entId는 기업 고유 식별자; 워크벤치와 불일치 시 "로드는 되나 상담원이 대화를 못 받음"(설정-팀 관리-ID 조회); 사이트 도메인은 "접속 사이트 추가"로 인증해야 함; 비즈니스 라인마다 별도 서브채널(프로브) 사용.
프레임워크 연동SPA · 라우트 변경 · manualInit
Vue/React/Next SPA는 라우트 변경 시 DOM을 파괴하고 위젯이 자동 재생성되지 않음; _MEIQIA('manualInit')로 자동 초기화를 막고 라우트 훅(useEffect / mounted)에서 _MEIQIA('init')로 필요 시 재마운트.
표시 이상스타일 충돌 · 스태킹 · 제3자 플러그인
로드는 됐는데 안 보임: 보통 사이트 전역 CSS가 버블 위치를 덮거나, 히트맵 / 분석 / SEO 플러그인이 DOM을 바꿔 컨테이너를 덮음; F12 → Elements에서 meiqia 컨테이너를 찾아 display:none / z-index 패배 / 화면 밖 좌표 확인.
모바일 / SDK모바일 웹 · AppKey · 푸시
모바일 / PC 웹은 같은 코드지만 별도 배포 필요; 앱 내부는 네이티브 SDK(콘솔에서 "APP 설정 추가"로 AppKey 먼저); 푸시는 "푸시 안 함"(앱 내부만)과 "커스텀 푸시 서버"(앱 종료 후에도 수신)로 나뉨.
API 호출withoutBtn · showPanel · 고객 정보
자체 버튼 사용: _MEIQIA('withoutBtn')로 기본 버튼 숨기고 클릭 시 _MEIQIA('showPanel')로 채팅 열기; 고객 정보 전달 / 동기화는 init 타이밍 안에서 호출해야 적용됨.
그림1: 美洽 미표시 분류 — 스크립트 로드 확인(F12에서 meiqia.js) 후 로딩 / 설정 / 프레임워크 / 표시로 분류
2단계: 가장 자주 놓치는 근본 원인 → L2 (위젯 = 제3자 외부도메인 비동기 JS 주입)
핵심은 한 문장입니다: 美洽 웹 위젯은 페이지에 박힌 정적 컴포넌트가 아니라, meiqia.js가 美洽 외부 도메인에서 비동기로 로드된 뒤 채팅 컨테이너(DOM / iframe)를 동적으로 주입하고 美洽 서버와 교차출처 장기 연결을 맺는 구조입니다. 이것이 대부분의 "미스터리" 미표시를 설명합니다 — ① 제3자 외부도메인 스크립트라서 AdBlock / uBlock이 "제3자 추적 / 광고" 규칙으로 차단(ERR_BLOCKED_BY_CLIENT), 버튼이 안 나타남(콘솔은 정상으로 보임). ② DOM을 비동기 주입해서 <head>에 있으면 블로킹, SPA 라우트 변경 시 컨테이너가 파괴되고 자동 재생성 안 됨(manualInit + _MEIQIA('init') 필요), 히트맵 / 분석 플러그인이 DOM을 바꿔 스태킹을 덮음. ③ entId로 기업에 바인딩되고 도메인 화이트리스트로 게이팅되어, entId가 틀리거나 도메인 미인증이면 로드는 되나 "대화 연결이 안 됨". ④ 모바일과 PC는 별도 연동, 앱 내부는 SDK(AppKey), 푸시는 "푸시 안 함" vs "커스텀 푸시 서버"로 나뉩니다. 이 주입 경로를 이해하면 아래 모든 증상에 하나의 논리가 생깁니다. 아래는 연동 자가점검 패널, 그 아래는 5가지 연동 방식과 2026 추정치.
그림2: 美洽 연동 자가점검 패널(초록=확인됨 / 빨강=놓치기 쉬움)그림: "코드 위치 + meiqia.js 200 + 초기화"를 먼저, 다음 "광고 차단 + 프레임워크/스태킹" — 뒤 둘이 가장 놓치기 쉬움
전체 증상 대조표 (L1 현상 / 공식 위치 · L2 근본 원인)
美洽 5가지 연동 방식 비교 (코드 / 난이도 / 기능 / 시나리오 / 적용 시간 · 공식 기준)
연동 방식
코드 / 난이도
기능 완성도
적합 대상
적용 시간
웹 JS 위젯
JS 한 줄 · 낮음
최대(플로트 / 팝업 / 자동 인사 / 방문자 추적)
PC + 모바일 사이트(공식 권장)
약 3-5분
채팅 링크
코드 없음 · 최저
기본 채팅
비개발 / 빠른 채팅 링크
즉시
API / WebIM SDK
개발 필요 · 높음
심층 커스텀(자체 UI / 시스템 / 주문 연동)
심층 융합 개발 역량 보유 팀
개발에 따라
네이티브 앱 SDK
SDK 통합 · 높음
앱 내부 채팅 + 메시지 푸시
iOS / Android 앱
개발에 따라
CMS 빠른 설정
플러그인 / 원클릭 · 낮음
JS 위젯과 동일
WordPress / Fkw / Shopify 사이트
수 분
美洽 미표시 원인 & 연동 방식 비교 (2026 추정)
다음은 美洽 공식 도움말(접속 채널 / JavaScript 웹 위젯 API)과 공개 연동 트러블슈팅을 종합한 2026 추정치입니다(벤더 약속·일차 측정 아님, 참고용, 버전·브라우저 정책에 따라 변동):
항목
추정 / 비교
미표시 원인 분포(커뮤니티 / 티켓 · 추정)
위치 / 미로드 ~35% > 광고 차단 / 브라우저 확장 ~25% > 설정 / 인증(entId / 도메인) ~20% > 프레임워크(SPA) ~12% > 스타일 / 제3자 플러그인 충돌 ~8%
연동의 본질
웹 위젯 = 제3자 외부도메인 비동기 JS의 DOM 주입 + 교차출처 장기 연결(임베드 정적 컴포넌트 아님); 따라서 위치·광고 차단 규칙·페이지 CSS 스태킹·SPA 생명주기의 영향을 받음
플랫폼별 연동(추정)
PC / 모바일 웹 = JS 위젯(같은 코드, 별도 배포); 앱 = 네이티브 SDK(AppKey); WeChat / Douyin / RED = 채널 인증 연동
광고 차단 영향(추정)
PC 사용자의 약 30-40%가 광고 차단 확장 사용 → 제3자 채팅 스크립트가 광고 규칙으로 차단(ERR_BLOCKED_BY_CLIENT), "콘솔 정상, 사용자 측 미표시"의 주요 원인
JS 위젯 적용 시간(공식)
전용 JS를 페이지 하단에 붙이면 약 3-5분 만에 적용; entId는 기업 고유 ID로, 워크벤치와 불일치 시 상담원이 대화를 못 받음
추정 근거: 출처 베이스라인 + 시간 외삽(meiqia.com/help 접속 채널 / JavaScript 웹 위젯, meiqia.im 사이트 연동 가이드, 공개 연동 트러블슈팅, 2026); 버전·브라우저 차단 정책에 따라 변동. 美洽 최신 공식 정보 기준. 비공식·LLM 현지화.
실제 사례 빠른 판단
코드를 붙였는데 채팅 버블이 없음: 먼저 F12 → Network에서 meiqia.js 검색 — 요청이 없거나 200이 아니면 위치 오류 / 캐시; CDN 캐시를 비우거나 시크릿 창에서 다시 열기.
콘솔에 meiqia.js net::ERR_BLOCKED_BY_CLIENT: 광고 차단(AdBlock / uBlock / AdGuard)이 제3자 채팅 스크립트를 광고 규칙으로 차단함 — 확장을 끄거나 사이트를 화이트리스트; "일부 사용자에게만 안 보이고 내 콘솔은 정상"인 이유.
스크립트는 로드됨(콘솔 typeof _MEIQIA가 function)인데 버튼이 없음: 보통 테마 CSS가 버블을 화면 밖으로 밀었거나 히트맵 / 분석 플러그인이 DOM 스태킹을 바꿈 — F12 → Elements에서 美洽 컨테이너를 하나씩 확인.
Vue / React SPA 홈에는 채팅이 있는데 2차 라우트에선 없음: SPA 라우트 변경이 컨테이너를 파괴하고 위젯이 재생성 안 됨 — manualInit로 자동 초기화를 막고 라우트 훅에서 _MEIQIA('init')로 재마운트.
채팅 창은 열리는데 상담원이 방문자 메시지를 못 받음: 대부분 entId가 워크벤치와 불일치(남의 스니펫 복사 / 계정 혼동) — 설정-팀 관리-ID 조회의 기업 ID와 코드의 entId 대조.
스테이징에선 되는데 운영 도메인에서 로드 안 됨: 운영 도메인이 "접속 사이트 추가"로 인증 안 됨 — 라이브 도메인을 접속 사이트 목록에 추가 후 재배포.
美洽 기본 원형 버튼을 없애고 자체 "상담" 버튼을 쓰고 싶음: _MEIQIA('withoutBtn')로 기본 버튼을 숨기고 자체 버튼에 _MEIQIA('showPanel')을 바인딩해 채팅 열기.
