문제 해결과 점검 목록

도구

• 개발자 도구 → 네트워크: loader.js, core.<hash>.js, WebSocket 연결(“메시지” 또는 “프레임” 탭에 init, init_ok, error 표시), 또는 HTTP 대체 연결 요청(h/auf, …/sse, …/tx)입니다.
• 진단 켜기: 로더 태그에 data-rc-debug="true"를 넣거나 콘솔에서 localStorage.setItem('rc_debug','1')을 실행한 뒤 새로고침합니다.
• 콘솔: ReactiveChat('getSession'), ReactiveChat('getEndpoint'), ReactiveChat('isOpen'), ReactiveChat.version.

채팅 버튼이 보이지 않음

• 사이트 키가 없거나 유효하지 않음. 로더가 조용히 중단됩니다. 실행된 태그의 data-rc-site-key를 확인합니다(A–Z a–z 0–9 _ - 중 8–64자). 태그 관리자와 프레임워크 도우미가 가끔 속성을 누락합니다.
• script 태그의 type="module": 이 경우 로더가 자신의 태그를 찾지 못합니다. 일반 스크립트로 삽입합니다.
• data-rc-hide-launcher="true" 또는 계정의 “자체 링크로만(채팅 아이콘 없음)” 설정.
• 스니펫에 브랜드 색상이 없음: 유효한 data-rc-brand 색상이 없으면 연결 후에야 버튼이 나타납니다. 계정에서 스니펫을 다시 복사합니다.
• 프로젝트 일시 중지 또는 알 수 없는 사이트 키: 서버는 unknown_site_key(종료 코드 4002)로 응답합니다. 위젯은 이 탭에서 10분 동안 다시 시도하지 않습니다.
• 코어가 로드되지 않음: 콘솔에 [reactive.chat] core.js …가 표시됩니다. script-src 또는 광고 차단기가 주소를 막는 경우가 많습니다. 자체 도메인을 참조합니다.

채팅 버튼은 있지만 메시지가 도착하지 않음

• 직접 호스팅한 loader.js에 data-rc-ws-url이 없음: 위젯이 자체 도메인 아래에서 채팅 서버를 찾습니다. 네트워크 탭에 wss://ws.<your-domain>/rc_wss/로의 실패한 연결 시도가 보입니다. 해결: data-rc-ws-url="wss://ws.reactive.chat/rc_wss/".
• origin_denied, 종료 코드 1008: 허용된 출처에 페이지 도메인이 없습니다. 채팅 서브도메인이 아닌 웹사이트 도메인을 입력합니다.
• CSP 차단: 콘솔에 CSP 메시지가 표시됩니다. 대상: wss://… 또는 https://…/rc_wss/h/auf. connect-src에 두 형식을 모두 추가합니다.
• WebSocket 없는 기업 네트워크: 두 번 실패하면 HTTP 대체 연결로 전환합니다. 이것도 작동하지 않으면 30초 미만에 요청을 중단하거나 응답을 버퍼링하는 프록시를 확인합니다(전송).
• 악용 방지에 의한 차단(종료 코드 1008 blocked): 유효한 프록시 키 없는 자체 프록시 뒤에서 모든 방문자가 같은 주소로 보일 때 흔합니다.
• 메시지가 너무 김: 위젯은 요금제 제한(1000자 또는 4000자)을 넘는 텍스트를 보내지 않습니다.

로그인 사용자를 익명으로 간주함

error 프레임에 auth_failed와 detail.reason이 포함됩니다.

• no_hash – identify에 userHash가 없습니다.
• no_secret – 프로젝트에 시크릿을 설정하지 않았습니다.
• bad_exp – exp가 초 대신 밀리초이거나 정수가 아닙니다.
• expired – 페이지를 오래 열어 두었거나 서버 시계가 잘못되었습니다. 페이지 로드 시 해시를 새로 계산합니다.
• exp_too_far – 24시간보다 먼 미래입니다.
• bad_hash – 시크릿, 순서(userId + "." + exp) 또는 문자 집합이 일치하지 않습니다. 시크릿은 디코딩한 바이트가 아닌 문자열 키입니다. 이메일 주소가 있으면 전달하는 그대로 서명해야 합니다.

자세한 내용: 방문자 식별.

고객 데이터가 도착하지 않음

• 로그인했는데도 어시스턴트가 로그인하라고 함: exp가 없거나 만료되었습니다. exp가 없으면 고객 데이터는 제공되지 않습니다.
• 계정의 연결 테스트에서 원인을 표시합니다(http_401, zeitueberschreitung, umleitung, adresse_privat 등). 서명 문자열은 X-RC-Zeit + "." + raw body입니다. 다시 인코딩한 JSON이 아니라 받은 그대로의 바이트로 검증합니다.
• 어시스턴트 답변에 필드가 없음: 계정에서 활성화하지 않았거나 절대 수집하지 않는 필드 목록에 있습니다.

자세한 내용: 고객 데이터 엔드포인트.

웹훅이 도착하지 않음

• 연동을 켜고 이벤트를 선택했나요(선택하지 않으면 모두)? 켠 뒤 최대 15초를 기다립니다.
• 엔드포인트 응답이 10초를 넘거나 리디렉션으로 응답합니다.
• 엔드포인트가 한 번 410으로 응답하면 연동이 비활성화됩니다. 다시 켭니다.
• 서명이 일치하지 않음: 원시 본문과 X-RC-Timestamp + "." + body로 계산하고 sha256= 접두사를 확인합니다.
• data에 내용이 없음: 이벤트별 필드는 웹훅에 있습니다. 선택하지 않은 이벤트는 전혀 도착하지 않습니다.

서버 API

• 401 auth_failed: 키 폐기, 오타 또는 생성자가 더 이상 관리자가 아님.
• 403 insufficient_scope: 권한 범위가 부족하며 required_scope가 필요한 범위를 표시합니다.
• 429: 분당 요청 120회를 초과했습니다. Retry-After를 준수합니다.
• 415/413: Content-Type: application/json이 없거나 본문이 64 KiB를 넘습니다.

개인정보 보호 안내가 나타나지 않음

• 페이지에 로더가 없거나 동의 플랫폼에서 차단함: datenschutz.js를 직접 삽입합니다.
• 웹사이트가 프로젝트 도메인으로 등록되지 않았거나 프로젝트가 일시 중지되었습니다.
• 요소의 data-rc-privacy-state="error"는 요청 실패를 나타냅니다.

실제 적용 전 점검 목록

1. 웹사이트의 모든 도메인을 허용된 출처에 입력했습니다.
2. 개인정보 처리방침 페이지를 포함해 채팅을 표시할 모든 페이지에 계정의 스니펫을 변경 없이 넣었습니다.
3. CSP: script-src의 배포 위치, connect-src의 wss:// 및 https://, 이미지용 img-src를 확인했습니다.
4. 동의: data-rc-consent 또는 동의 플랫폼(TCF v2 / consented.eu)을 확인하고 동의가 있는 경우와 없는 경우 모두 테스트했습니다.
5. 개인정보 처리방침을 확장했습니다(<div data-rc-privacy> 또는 문구).
6. 신원: 서버에서 exp가 포함된 userHash를 계산하고 시크릿은 서버 환경에만 있으며 init_ok.identity.verified가 true입니다.
7. 기밀 텍스트 영역을 data-rc-private로 표시했습니다.
8. 자체 도메인: 다섯 검사 단계가 모두 “정상”이며 프록시 키는 프록시 설정에만 있고 /rc_wss/h/는 접근 로그에 없습니다.
9. 웹훅: 서명과 타임스탬프를 검증하고 X-RC-Delivery로 중복을 감지하며 빠르게 2xx로 응답합니다.
10. data-rc-transport="http"로 HTTP 대체 연결을 한 번 테스트했습니다.
11. 모바일 화면(480픽셀 미만에서 전체 화면으로 열림)과 키보드 조작을 확인했습니다.