위젯 설치하기

RolChat 위젯은 켜 둔 모듈에 맞춰 바뀌는 하나의 플로팅 버튼입니다. 채팅, 콜백 요청 양식, 미팅 예약, 리드 양식, 지식 베이스 검색이 모두 그 안에 있습니다. 한 번만 설치하면 되고, 무엇을 보여 줄지는 대시보드에서 정합니다.

1. 스니펫 복사하기

설정 → 위젯에서 사이트를 선택하고 설치 스니펫을 복사합니다. 다음과 같은 형태입니다.

<!-- RolChat widget -->
<script>
  window.rolchatConfig = {
    "site_id": "ste_…",
    "account_id": "…",
    "widget_key": "wk1.<site>.<signature>",
    "modules": ["chat"]
  };
</script>
<script async src="https://widget.rolchat.com/stub.js"></script>

위젯 키는 공개 정보이므로 페이지에 넣어도 안전합니다. 키는 사이트를 가리키고 서명되어 있어, 누구도 위젯 사본을 여러분의 계정으로 연결할 수 없습니다. 위젯 설정(인사말, 헤더 제목, 테마, 근무 시간, 뷰포트별 레이아웃)을 바꾸면 대시보드가 객체에 키를 추가합니다. 설정을 바꾼 뒤에는 스니펫을 다시 복사하거나, 객체를 최소한으로 두고 나머지는 위젯이 가져오게 하세요.

stub.js는 몇 킬로바이트에 불과하며 나머지는 방문자에게 필요할 때만 불러옵니다. 채팅 화면은 처음 열 때, 추적은 동의 후에, 동의 배너는 필요한 경우에만 불러옵니다.

2. </body> 앞에 붙여 넣기

위젯을 표시할 모든 페이지에 스니펫을 추가합니다. 사이트 템플릿이나 태그 관리자를 이용하면 모든 페이지에 한 번에 적용됩니다. 스크립트는 비동기로 로드되어 렌더링을 막지 않으며, 첫 로드 번들은 Core Web Vitals에 영향을 주지 않도록 의도적으로 작게 유지됩니다.

3. 작동 확인하기

시크릿 창에서 사이트를 엽니다. 선택한 모서리에 버튼이 나타납니다. 대시보드의 방문자에 새 익명 세션이 실시간으로 표시되고, 위젯에서 보낸 메시지는 받은편지함에 새 대화로 나타납니다.

로그인한 사용자 식별하기

방문자가 여러분의 제품에 로그인한다면, 그들이 누구인지 RolChat에 알려 대화가 올바른 연락처에 연결되게 하세요.

window.rolchat.identify({
  email: "alice@example.com",
  first_name: "Alice",
  last_name: "Martin",
  phone: "+15551234567",
  external_id: "user_12345",
  custom_fields: { plan: "pro" },
});

허용되는 속성은 email, phone, first_name, last_name, external_id와 평면 구조의 custom_fields 객체이며, 그 외의 값은 무시됩니다. RolChat은 CRM에서 이메일을 조회합니다. 연락처가 있으면 세션이 해당 연락처에 연결되어 상담원이 프로필을 볼 수 있고, 없으면 정보가 보관되었다가 방문자가 처음 메시지를 보낼 때 리드가 생성됩니다.

더 높은 신뢰가 필요하다면 백엔드에서 신원에 서명할 수 있습니다. RolChat이 해당 사용자에게 발급한 서명을 속성과 함께 전달하면, 서명이 검증될 때만 세션이 승격됩니다. 사용자가 로그아웃하면 window.rolchat.reset()을 호출하세요. 그렇지 않으면 그 브라우저를 다음에 쓰는 사람이 이전 대화를 보게 됩니다.

JavaScript API

window.rolchat은 스텁이 실행되는 즉시 사용할 수 있습니다. 번들이 로드되기 전에 한 호출은 대기열에 들어가 순서대로 실행됩니다.

메서드	기능
show() / hide()	런처 표시 또는 숨기기
open() / close()	채팅 패널 열기 또는 닫기
identify(traits)	세션을 사람에게 연결(위 참고)
reset()	신원을 지우고 새 익명 세션 시작
pushEvent(name, props)	트리거 메시지와 자동화를 위한 사용자 지정 이벤트 보고
trackPageView(path?)	싱글 페이지 앱에서 페이지 조회 보고
setLocale(code)	위젯 언어 전환
showConsentPreferences()	동의 환경설정 센터 열기
on(event, handler) / off(event, handler)	chat:opened, chat:closed, message:sent, message:received, session:started 구독

window.rolchat.pushEvent("cart_abandoned", { value: 129.9, currency: "EUR" });
window.rolchat.on("message:received", () => audio.play());

언어와 방향

위젯은 window.rolchatConfig의 lang으로 지정한 언어로 표시됩니다(예: "lang": "de"). 지정하지 않으면 방문자의 브라우저 언어를 브라우저의 선호 순서대로 RolChat이 지원하는 40개 언어 중에서 고르고, 맞는 언어가 없으면 영어를 씁니다. 사이트 자체의 언어 설정은 사용되지 않습니다. 위젯이 사이트의 언어로 표시되게 하려면 lang을 설정하세요. 아랍어와 히브리어는 오른쪽에서 왼쪽으로 표시됩니다. 상담원 메시지는 위젯에서 번역되지 않으며, 대신 상담원 쪽에서 AI 실시간 번역을 사용할 수 있습니다.

쿠키와 동의

동의 배너가 필요한 곳에서는 위젯이 동의 전에 방문자를 추적하지 않습니다. RolChat 개인정보 모듈을 사용하면 배너와 위젯이 하나의 동의 상태를 공유합니다. 다른 동의 도구를 사용한다면 위젯의 분석 이벤트는 설정 → 개인정보 → 임베드에서 설정한 신호를 기다립니다.

위젯 설정 위치

항목	위치
색상, 위치, 인사말, 진입점, 설치 스니펫	설정 → 위젯
위젯 안에 표시할 모듈	설정 → 모듈(사이트별)
근무 시간과 오프라인 메시지	설정 → 사이트 → 근무 시간
특정 페이지에 표시할 트리거 메시지	마케팅 → 트리거