1단계: 네 갈래로 분류(로딩 / 설정 / 프레임워크 / 표시)
어떤 "채팅이 안 나옴"이든 먼저 네 갈래로 좁히세요 — 이것만으로 우회의 대부분을 아낍니다. 흐름도가 결정을 명확히 합니다: 스크립트가 로드됐는지(F12에서 meiqia.js), 다음 설정·프레임워크·표시 레이어 문제인지. 기본은 美洽 사이트 연동 가이드 참고.
연동 원리: 왜 이 JS 주입이 실패 / 차단되는가
한 문장이면 충분합니다: 美洽 웹 위젯은 페이지의 정적 컴포넌트가 아니라, meiqia.js가 美洽 외부 도메인에서 비동기 로드돼 채팅 컨테이너(DOM / iframe)를 동적 주입하고 교차출처 장기 연결을 맺습니다. 주입 성공에는 "스크립트 로드(위치 정확·광고 차단 안 됨), 컨테이너가 사이트 CSS / 다른 플러그인에 안 덮임, entId·도메인 일치, SPA 라우트 변경 후 재마운트"가 필요. 아래 다이어그램이 이 경로와 네 차단점을 그립니다 — 같은 코드가 사이트 / 프레임워크에 따라 되고 안 되는 이유.
코드는 맞게 붙였는데 안 보임: 연동 자가점검 패널을 확인
위치·meiqia.js 200·entId를 다 확인했는데 안 보이면 기본적으로 "광고 차단"이나 "프레임워크 / 스태킹"입니다. 아래 패널은 중요도순: 초록은 보통 정상, 빨강(광고 차단, SPA / 제3자 플러그인 스태킹)이 잦은 함정. 하나씩 점검하면 빠르게 좁힙니다.
전체 증상표(현상 / 공식 위치 · L2 근본 원인)
아래 표는 흔한 미표시 / 오류 증상을 한 번에 나열하고 각각 공식 위치와 L2 근본 원인을 함께 적습니다. 위 검색창은 이 표 데이터로 구동됩니다 — 겪은 키워드로 검색하세요.
| 증상 | 분류 | L1 현상 / 공식 위치 | L2 근본 원인 |
|---|---|---|---|
| 채팅 창 / 버블이 아예 안 보임 | 로딩 실패 | 美洽 웹 위젯은 붙여넣은 JS 스니펫 하나로 플로팅 채팅 창을 로드합니다; 코드가 올바르게 임베드됐는지, 접속 사이트가 콘솔에 설정됐는지 확인하세요. | 위젯은 비동기 로드 후 DOM에 주입되는 meiqia.js라서, "전혀 안 보임"은 보통 "스크립트가 로드된 적 없음" — 위치 오류, 광고 차단 / 캐시, 또는 도메인 / entId 불일치로 주입 단계가 실행되지 않은 것. |
| 스크립트는 로드됐으나 채팅 버튼이 안 나타남 | 표시 이상 | 위젯 코드는 사이트에 자동 적응해 채팅 버튼을 표시합니다; 표시가 이상하면 스타일로 숨겨졌는지 초기화가 중단됐는지 확인하세요. | 로드는 됐는데 버튼이 없으면 보통 "표시 레이어" 문제: 사이트 전역 CSS가 버튼 위치를 덮거나 display:none, z-index 패배, 또는 다른 고정 요소가 덮음; 다른 JS 오류가 초기화를 중단시킬 수도. |
| meiqia.js가 광고 차단 확장에 막힘 | 로딩 실패 | 美洽 채팅 스크립트는 제3자 도메인에서 옵니다; 차단 확장이 설치돼 있으면 광고 / 추적으로 인식해 로드를 막을 수 있으니 차단을 끄거나 화이트리스트하세요. | ERR_BLOCKED_BY_CLIENT는 브라우저 확장(AdBlock / uBlock / AdGuard)이 필터 목록으로 요청을 차단한 것. 美洽 스크립트는 "제3자 외부도메인 + 실시간 통신"이라 이런 규칙이 광고 / 추적으로 오인해 "콘솔 정상, 사용자 측 미표시" 가짜 실패를 만듦. |
| meiqia.js 404 / 비정상 상태 / 혼합 콘텐츠 | 로딩 실패 | 배포 후 Network 패널에서 meiqia.js를 검색하세요; 200이면 스크립트 위치가 올바르고 로드된 것입니다. | 흔한 비200 원인: 페이지 / CDN 캐시(게시 후 미갱신), HTTP 페이지 로드 / 인증서 체인 불완전으로 혼합 콘텐츠 차단, 또는 코드 손상 / 부분 복사. 이 단계가 실패하면 주입과 연결이 일어나지 않음. |
| 코드 위치 오류(head 블로킹 / 미적용) | 로딩 실패 | 美洽는 코드를 페이지 하단 </body> 태그 앞에 붙이길 권장합니다; 위젯은 페이지 주요 콘텐츠 로드 후 실행됩니다. | 위젯은 DOM 준비 후 컨테이너를 주입해야 함. <head>에선 렌더링 블로킹(약한 네트워크에서 빈 화면 먼저)이거나 DOM 미준비 시 실행돼 주입 실패; 일부 비동기 / 모듈 스코프에선 로드 순서가 꼬일 수도. |
| 채팅 창 / 버튼 스타일 깨짐 | 표시 이상 | 위젯은 자체 스타일을 주입하고 사이트에 자동 적응합니다; 사이트 전역 스타일과 충돌하면 외관 이상이 생길 수 있습니다. | 美洽 스크립트는 런타임에 CSS를 주입; 사이트 전역 스타일(범용 셀렉터 / 고우선순위 규칙 / reset)이 먼저 클래스를 덮으면 버튼 위치·스태킹·폰트가 깨짐 — "동적 주입 + 한 문서 스타일 공간 공유"의 부작용. |
| 버튼이 화면 밖 / 가려짐 | 표시 이상 | 위젯 버튼은 고정 위치 플로팅으로 나타납니다; 다른 고정 요소에 덮이면 스태킹이나 위치를 조정하세요. | 사이트의 다른 position:fixed 요소(맨 위로, 플로팅 광고, 커스텀 상담바)가 더 높은 z-index로 美洽 버튼을 덮거나, 테마가 좌표를 잘못 계산해 버튼이 "화면 밖 / 가려짐". |
| 제3자 플러그인 / 분석 DOM 충돌 | 표시 이상 | DOM을 수정하거나 요청을 가로채는 페이지의 다른 스크립트는 위젯의 정상 로드와 표시에 영향을 줄 수 있습니다. | 히트맵 / 분석 / 전환 스크립트는 DOM을 재작성하고 오버레이를 주입하거나 요청을 가로챔; 美洽와 같은 문서에 주입돼 스태킹 / 이벤트가 간섭해 컨테이너가 덮이거나 init이 중단됨. |
| SPA 라우트 변경 후 위젯 사라짐 | 프레임워크 연동 | 단일 페이지 앱(SPA)에선 프레임워크 라우트 훅으로 美洽 위젯을 로드 / init해 프런트엔드 라우팅에 맞추세요. | SPA는 프런트엔드 라우팅으로 뷰를 교체하며 DOM을 파괴 / 재생성하지만, meiqia.js는 기본적으로 첫 로드에 한 번만 주입하고 라우트 변경 시 자동 재생성 안 함 — "페이지 바꾸면 채팅 사라짐". |
| 수동 초기화 필요(manualInit / init) | 프레임워크 연동 | 美洽 임베드 코드 뒤에 _MEIQIA('manualInit')을 넣으면 다운로드 후 자동 init을 막습니다; 필요할 때 _MEIQIA('init')으로 수동 초기화. | 기본은 다운로드 직후 자동 init; 컨테이너 준비 / 고객 정보 전달 / 라우트 안정 후 표시해야 할 때 그 타이밍은 "너무 이름" — 수동 init으로 순서 제어. |
| entId 불일치 / 상담원이 대화를 못 받음 | 설정 / 인증 | 코드의 entId 뒤 숫자는 기업 고유 ID입니다; 워크벤치와 불일치하면 상담원이 대화를 받을 수 없으니 설정-팀 관리-ID 조회에서 기업 ID를 확인하세요. | entId는 스니펫을 특정 기업 계정에 바인딩. 남의 / 다른 환경 코드를 쓰거나 계정을 혼동하면 프런트엔드는 창을 로드하지만 메시지가 "다른 기업"으로 가서 이 워크벤치는 못 받음 — "표시는 정상인데 수신 안 됨"의 전형. |
| 사이트 도메인이 콘솔에 미인증 | 설정 / 인증 | 美洽 콘솔에서 "접속 사이트 추가"가 가능하며 각각 자체 설정이 있습니다; 새 사이트는 콘솔에서 설정해야 제대로 연동됩니다. | 美洽는 여러 사이트를 "접속 사이트"로 관리; 도메인은 콘솔에 등록 / 인증해야 인식됨. 새 운영 도메인을 추가 안 하면 인식 안 되거나 잘못된 설정에 매핑될 수 있음. |
| 다중 사이트 / 서브채널(프로브) 교차 배선 | 설정 / 인증 | 美洽는 사이트별 다른 위젯과 채팅 링크 배포를 지원합니다(서브채널 / 프로브); 기본 사이트 외에 더 추가할 수 있고 각각 자체 설정. | 비즈니스 라인마다 다른 상담 그룹 / 자동 메시지가 필요하지만 모든 사이트가 하나의 기본 스니펫을 공유하면 출처를 구분 못 하고 설정이 교차됨. 서브채널(프로브)은 "한 기업, 여러 진입점, 라우팅"용 설계. |
| 모바일 웹 채팅 미표시 / 별도 배포 필요 | 모바일 / SDK | 위젯 코드는 사이트에 자동 적응하며 모바일 / PC가 같은 스니펫이지만 별도 배포해야 합니다. | 많은 팀이 PC와 모바일 페이지 / 템플릿이 분리돼 있고 PC 템플릿에만 코드를 붙임. 스니펫은 같고 자동 적응하지만 "붙이기" 단계를 모바일 템플릿에도 해야 함; 빠뜨리면 모바일엔 없음. |
| 네이티브 앱 SDK 연동 / AppKey | 모바일 / SDK | 앱 내부 연동은 美洽 워크벤치(설정-연동-SDK, "APP 설정 추가")에서 AppKey가 필요하며, 개발자가 공식 문서 / 데모대로 iOS / Android SDK를 통합합니다. | 앱은 웹 JS가 아닌 네이티브 SDK를 사용: 먼저 "APP 설정 추가"로 AppKey, 그다음 플랫폼별 SDK로 채팅 UI·미읽음·푸시 구현 — 웹 위젯과 완전히 다른 경로. |
| SDK 메시지 푸시가 안 옴 | 모바일 / SDK | 美洽 SDK 푸시는 두 모드: "푸시 안 함"이면 상담원 메시지가 앱 내부에만(앱을 열어야 수신); "커스텀 푸시 서버"를 설정하면 앱을 나가도 폰으로 푸시 수신. | "오프라인 푸시" 누락은 보통 푸시 모드가 "푸시 안 함"이거나 커스텀 푸시 서버 / 플랫폼별 푸시 인증서가 없는 것. 경로는 "美洽 → 앱 서버 → 사용자 폰"; 한 고리가 빠지면 앱 내부 수신만. |
| 기본 버튼 숨김 / 커스텀 진입점 | API 호출 | _MEIQIA('withoutBtn')을 호출하면 美洽 기본 채팅 버튼을 표시하지 않습니다; init 성공 후 _MEIQIA('showPanel')로 채팅을 엽니다. | 기본은 내장 플로팅 버튼을 렌더; 자체 진입점을 쓰려면 init 전 / 중에 "내장 버튼 없음"을 선언하고 "채팅 열기"를 자체 요소에 바인딩해야 함 — "버튼 고장"이 아니라 API 타이밍 문제. |
| 고객 정보 전달 / 동기화가 적용 안 됨 | API 호출 | 美洽 웹 위젯은 "고객 정보 전달", "고객 신원 동기화", "고객 커스텀 이벤트 정보 추가" API로 방문자 데이터를 대화에 가져옵니다. | 이 API들은 올바른 init 타이밍 안에서 호출해야 함: init 성공 후(또는 manualInit + init 타이밍). 너무 이르거나 늦거나 필드 형식이 틀리면 "설정했으나 적용 안 됨". |
美洽 미표시 원인 & 연동 방식 비교 (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 현지화.
美洽 5가지 연동 방식 비교(코드 / 난이도 / 기능 / 시나리오 / 적용 시간)
어떤 연동 방식? 아래 비교는 美洽 공식 정보를 종합한 빠른 횡단 참조(코드량, 기능 완성도, 적합도, 적용 시간). 대부분 사이트는 "웹 JS 위젯"을 선택.
| 연동 방식 | 코드 / 난이도 | 기능 완성도 | 적합 대상 | 적용 시간 |
|---|---|---|---|---|
| 웹 JS 위젯 | JS 한 줄 · 낮음 | 최대(플로트 / 팝업 / 자동 인사 / 방문자 추적) | PC + 모바일 사이트(공식 권장) | 약 3-5분 |
| 채팅 링크 | 코드 없음 · 최저 | 기본 채팅 | 비개발 / 빠른 채팅 링크 | 즉시 |
| API / WebIM SDK | 개발 필요 · 높음 | 심층 커스텀(자체 UI / 시스템 / 주문 연동) | 심층 융합 개발 역량 보유 팀 | 개발에 따라 |
| 네이티브 앱 SDK | SDK 통합 · 높음 | 앱 내부 채팅 + 메시지 푸시 | iOS / Android 앱 | 개발에 따라 |
| CMS 빠른 설정 | 플러그인 / 원클릭 · 낮음 | JS 위젯과 동일 | WordPress / Fkw / Shopify 사이트 | 수 분 |
채널 / 시나리오 → 연동 성패 맵
같은 美洽도 채널 / 시나리오마다 연동 방식이 다릅니다. 아래 맵은 흔한 채널: 초록=붙이면 됨, 노랑=설정 필요(별도 배포 / init / 화이트리스트), 빨강=기본적으로 방식 변경(광고 차단 / entId / 앱은 SDK).
자주 묻는 질문
美洽 채팅 창 / 버블이 아예 안 보임 — 어떻게 해결하나요?
美洽 웹 위젯은 붙여넣은 JS 스니펫 하나로 플로팅 채팅 창을 로드합니다; 코드가 올바르게 임베드됐는지, 접속 사이트가 콘솔에 설정됐는지 확인하세요. 위젯은 비동기 로드 후 DOM에 주입되는 meiqia.js라서, "전혀 안 보임"은 보통 "스크립트가 로드된 적 없음" — 위치 오류, 광고 차단 / 캐시, 또는 도메인 / entId 불일치로 주입 단계가 실행되지 않은 것. F12 → Network에서 meiqia.js 검색: 요청 없음 → 코드 미적용(위치 / 캐시 확인); 요청 있으나 200 아님 → 차단 또는 경로 문제; 모두 정상인데 안 보임 → entId / 도메인 인증과 아래 갈래 확인.
美洽 스크립트는 로드됐으나 채팅 버튼이 안 나타남 — 어떻게 해결하나요?
위젯 코드는 사이트에 자동 적응해 채팅 버튼을 표시합니다; 표시가 이상하면 스타일로 숨겨졌는지 초기화가 중단됐는지 확인하세요. 로드는 됐는데 버튼이 없으면 보통 "표시 레이어" 문제: 사이트 전역 CSS가 버튼 위치를 덮거나 display:none, z-index 패배, 또는 다른 고정 요소가 덮음; 다른 JS 오류가 초기화를 중단시킬 수도. F12 → Elements에서 美洽 컨테이너를 찾아 존재 / 숨김 / 화면 밖인지 확인; 커스텀 CSS / 다른 스크립트를 임시 비활성화해 재테스트; 콘솔에서 실행 중단 오류 확인.
美洽 meiqia.js가 광고 차단 확장에 막힘 — 어떻게 해결하나요?
美洽 채팅 스크립트는 제3자 도메인에서 옵니다; 차단 확장이 설치돼 있으면 광고 / 추적으로 인식해 로드를 막을 수 있으니 차단을 끄거나 화이트리스트하세요. ERR_BLOCKED_BY_CLIENT는 브라우저 확장(AdBlock / uBlock / AdGuard)이 필터 목록으로 요청을 차단한 것. 美洽 스크립트는 "제3자 외부도메인 + 실시간 통신"이라 이런 규칙이 광고 / 추적으로 오인해 "콘솔 정상, 사용자 측 미표시" 가짜 실패를 만듦. 시크릿 모드나 광고 차단을 끄고 재테스트 — 표시되면 차단이 원인; 사용자에게 사이트 화이트리스트 안내; 프런트엔드에서 채팅 스크립트를 지연 / 조건부 로드해 일부 자동 규칙 우회.
美洽 meiqia.js 404 / 비정상 상태 / 혼합 콘텐츠 — 어떻게 해결하나요?
배포 후 Network 패널에서 meiqia.js를 검색하세요; 200이면 스크립트 위치가 올바르고 로드된 것입니다. 흔한 비200 원인: 페이지 / CDN 캐시(게시 후 미갱신), HTTP 페이지 로드 / 인증서 체인 불완전으로 혼합 콘텐츠 차단, 또는 코드 손상 / 부분 복사. 이 단계가 실패하면 주입과 연결이 일어나지 않음. 게시 후 CDN / 브라우저 캐시 비우기(또는 시크릿); 전체 HTTPS·완전한 인증서 체인·혼합 콘텐츠 없음 확인; 복사한 코드가 완전하고 이스케이프 안 됐는지 확인.
美洽 코드 위치 오류(head 블로킹 / 미적용) — 어떻게 해결하나요?
美洽는 코드를 페이지 하단 </body> 태그 앞에 붙이길 권장합니다; 위젯은 페이지 주요 콘텐츠 로드 후 실행됩니다. 위젯은 DOM 준비 후 컨테이너를 주입해야 함. <head>에선 렌더링 블로킹(약한 네트워크에서 빈 화면 먼저)이거나 DOM 미준비 시 실행돼 주입 실패; 일부 비동기 / 모듈 스코프에선 로드 순서가 꼬일 수도. 美洽 JS를 모든 페이지 공통 푸터 </body> 앞에; SPA는 "SPA 라우트" 항목 참고해 manualInit; 번들러가 tree-shaking으로 제거 안 하게.
美洽 채팅 창 / 버튼 스타일 깨짐 — 어떻게 해결하나요?
위젯은 자체 스타일을 주입하고 사이트에 자동 적응합니다; 사이트 전역 스타일과 충돌하면 외관 이상이 생길 수 있습니다. 美洽 스크립트는 런타임에 CSS를 주입; 사이트 전역 스타일(범용 셀렉터 / 고우선순위 규칙 / reset)이 먼저 클래스를 덮으면 버튼 위치·스태킹·폰트가 깨짐 — "동적 주입 + 한 문서 스타일 공간 공유"의 부작용. F12로 어떤 사이트 규칙이 美洽 컨테이너를 덮는지 확인; 전역 스타일 범위를 좁히기 / 범용 클래스 영향 줄이기; 필요 시 美洽에 컨테이너 레이어링 조정 요청.
美洽 버튼이 화면 밖 / 가려짐 — 어떻게 해결하나요?
위젯 버튼은 고정 위치 플로팅으로 나타납니다; 다른 고정 요소에 덮이면 스태킹이나 위치를 조정하세요. 사이트의 다른 position:fixed 요소(맨 위로, 플로팅 광고, 커스텀 상담바)가 더 높은 z-index로 美洽 버튼을 덮거나, 테마가 좌표를 잘못 계산해 버튼이 "화면 밖 / 가려짐". F12에서 美洽 컨테이너를 선택해 실제 좌표 / z-index 확인; 그것을 올리거나 덮는 요소의 z-index 낮추기; 한 모서리에 고정 플로트 여러 개 쌓지 않기.
美洽 제3자 플러그인 / 분석 DOM 충돌 — 어떻게 해결하나요?
DOM을 수정하거나 요청을 가로채는 페이지의 다른 스크립트는 위젯의 정상 로드와 표시에 영향을 줄 수 있습니다. 히트맵 / 분석 / 전환 스크립트는 DOM을 재작성하고 오버레이를 주입하거나 요청을 가로챔; 美洽와 같은 문서에 주입돼 스태킹 / 이벤트가 간섭해 컨테이너가 덮이거나 init이 중단됨. 의심 플러그인을 하나씩 비활성화해 충돌원 찾기; 로드 순서 / 컨테이너 레이어링 조정; 히트맵 등이 美洽 컨테이너 영역을 피하게.
美洽 SPA 라우트 변경 후 위젯 사라짐 — 어떻게 해결하나요?
단일 페이지 앱(SPA)에선 프레임워크 라우트 훅으로 美洽 위젯을 로드 / init해 프런트엔드 라우팅에 맞추세요. SPA는 프런트엔드 라우팅으로 뷰를 교체하며 DOM을 파괴 / 재생성하지만, meiqia.js는 기본적으로 첫 로드에 한 번만 주입하고 라우트 변경 시 자동 재생성 안 함 — "페이지 바꾸면 채팅 사라짐". _MEIQIA('manualInit')로 자동 init을 막고, 라우트 훅(React useEffect / Vue mounted / router afterEach)에서 _MEIQIA('init')로 재마운트; 여러 인스턴스 초기화 회피.
美洽 수동 초기화 필요(manualInit / init) — 어떻게 해결하나요?
美洽 임베드 코드 뒤에 _MEIQIA('manualInit')을 넣으면 다운로드 후 자동 init을 막습니다; 필요할 때 _MEIQIA('init')으로 수동 초기화. 기본은 다운로드 직후 자동 init; 컨테이너 준비 / 고객 정보 전달 / 라우트 안정 후 표시해야 할 때 그 타이밍은 "너무 이름" — 수동 init으로 순서 제어. 임베드 코드 뒤 _MEIQIA('manualInit'); 조건 준비(DOM / 로그인 상태 / 라우트) 후 _MEIQIA('init'); 정보 API는 문서 순서대로 init 타이밍 안에서 호출.
더 많은 연동 설정은 美洽 사이트 연동, APP SDK 연동; 입문은 美洽 가이드. 검색 가능한 전체판(이 도구 포함)은 美洽 연동 트러블슈팅(GitHub Pages).