개발자용 위젯 연동 참고 — 로그인·로그아웃, 세션, JS 함수
개발자용 위젯 연동 참고 — 설치 코드 옵션 전체, JS 함수(push·open·close·toggle·reset·destroy·track), SPA 로그인 직후·로그아웃 때 할 일, 다시 식별하는 때, 위젯 세션 24시간과 지난 상담, 페이지 기록, CSP, 모바일 표시. 키워드: 위젯 SDK, Lenit.reset, 로그아웃, getToken, CSP, trackPageView.
업데이트
개발자가 위젯을 서비스 코드에 붙일 때 보는 참고 문서예요. 설치 화면 안내는 위젯 설치하기 — 위젯 팝업과 보드 링크, 서명(JWT·HMAC) 만드는 법과 방식별 차이는 사용자 식별(SSO)과 고객 속성(traits) 문서를 보세요.
설치 코드와 옵션
설치 코드는 어떤 모양인가요?
설정을 window.Lenit 대기열에 넣고 스크립트를 비동기로 불러와요. 스크립트가 늦게 받아져도 대기열에 넣은 설정이 그대로 적용돼요. 실제 코드는 설정 > 연동 > 서비스 연동의 연동 코드 탭에서 복사하세요 — 보드 키가 채워져 있어요.
<script>
window.Lenit = window.Lenit || [];
window.Lenit.push({ boardKey: "vb_live_…", userId: "user_123" });
</script>
<script src="https://lenit.cloud/widget.js" async></script>스크립트가 받아지기 전에 Lenit.init(...) 을 부르면 오류가 나요. 처음에는 push 를 쓰고, 받아진 뒤에는 Lenit.push·Lenit.init 어느 쪽이든 돼요.
고객을 알려 주는 옵션은 무엇인가요?
보드 키(boardKey)만 필수예요. 나머지는 로그인한 회원을 알려 줄 때 넣어요.
| 옵션 | 기본값 | 뜻 |
|---|---|---|
boardKey | 필수 | 워크스페이스 보드 키 — 공개해도 되는 값 |
userId | 없음(익명) | 로그인한 회원의 바뀌지 않는 내부 ID — 이메일·전화번호는 넣지 마세요 |
userIdSignature | 없음 | userId 의 HMAC 서명(② userId + 서명 방식) |
token | 없음 | 서버가 서명한 JWT(① JWT 방식) |
getToken | 없음 | 식별 직전마다 새 JWT 를 받아 오는 함수 — 콜백이나 Promise 로 5초 안에 돌려줘요 |
profile | 없음 | 이름·이메일·사진(name·email·avatarUrl) — ② 방식에서 서명이 맞을 때만 써요 |
traits | 없음 | 고객 속성(예: plan) — JWT 를 쓰면 토큰 안의 값을 써요 |
런처와 화면을 바꾸는 옵션은 무엇인가요?
모두 선택이에요. 넣지 않으면 아래 기본값으로 동작해요.
| 옵션 | 기본값 | 뜻 |
|---|---|---|
position | "bottom-right" | 버튼 위치 — "bottom-left" 도 돼요 |
color | 위젯 설정의 런처 색 | 버튼 색 — 코드에 적으면 위젯 설정의 색보다 먼저예요(둘 다 없으면 브랜드 색) |
zIndex | 2147483647 | 겹침 순서 — 사이트 요소와 겹칠 때 조정해요 |
showButton | true | false 면 기본 런처 버튼을 숨겨요 |
customLauncherSelector | 없음 | 내 버튼(CSS 선택자)을 누르면 위젯이 열려요 — 기본 버튼은 숨겨져요 |
language | 고객 브라우저 언어 | "ko"·"en" 으로 위젯 언어를 정해요 |
trackPageView | true | false 면 본 페이지를 기록하지 않아요 |
openMode | "panel" | "newtab" 이면 위젯 대신 공개 보드를 새 탭으로 열어요 |
위젯 언어를 설치 코드로 정할 수 있나요?
네. language: "ko" 또는 "en" 을 넣으면 런처 문구와 위젯이 그 언어로 열려요. 넣지 않으면 고객 브라우저 언어를 따라요 — 한국어면 한국어, 그 밖은 영어예요. 다른 값을 넣으면 개발자 콘솔에 경고가 남고 브라우저 언어로 열려요.
고객은 위젯 설정에서 한국어/English 를 직접 바꿀 수도 있어요. 언어 규칙 전체는 언어와 시간대 — 화면·메일·고객에게 보이는 언어, 기준 시간대 문서를 보세요.
openMode: "newtab" 은 언제 쓰나요?
위젯 화면(iframe)을 띄우기 어려운 곳에서만 쓰세요. 런처를 누르면 위젯 대신 공개 보드가 새 탭으로 열리고, 상담은 들어 있지 않아요. 사용자 식별을 쓴다면 기본값("panel")을 쓰세요.
코드로 위젯 다루기
코드에서 부를 수 있는 함수는 무엇인가요?
스크립트가 받아진 뒤 아래 함수를 부를 수 있어요. 받아지기 전에는 window.Lenit.push(설정) 만 써요.
| 함수 | 하는 일 |
|---|---|
Lenit.push(설정) · Lenit.init(설정) | 새 설정으로 위젯을 다시 그려요 — 로그인 직후에 불러요 |
Lenit.open() | 위젯을 열어요(홈) |
Lenit.open({ tab: "chat", prefill: "…" }) | 새 문의 화면을 바로 열고 입력창에 문구를 채워요 |
Lenit.close() · Lenit.toggle() | 닫기 · 열려 있으면 닫고 닫혀 있으면 열기 |
Lenit.reset() (= Lenit.logout()) | 로그아웃 — 이전 사람의 세션·상담·알림 표시를 지우고 익명으로 다시 시작해요 |
Lenit.destroy() | 위젯을 페이지에서 걷어 내요 — 다시 띄우려면 Lenit.push(설정) |
Lenit.track("이름", { 속성 }) | 고객 행동을 기록해요 |
버튼을 누르면 새 문의 화면이 바로 열리게 할 수 있나요?
네. Lenit.open({ tab: "chat", prefill: "문구" }) 를 부르세요. 새 문의 화면이 바로 열리고 입력창에 문구가 채워져요(1,000자까지). 보내기는 고객이 눌러요. 인자 없이 Lenit.open() 은 위젯 홈을 열어요.
document.querySelector("#contact-btn").addEventListener("click", () => {
Lenit.open({ tab: "chat", prefill: "결제 관련 문의" });
});기본 런처 없이 내 버튼으로만 열려면 설치 코드에 showButton: false 를 넣거나 customLauncherSelector 를 쓰세요.
Lenit.track() 으로 보낸 이벤트는 어디서 보나요?
인박스 고객 정보 패널의 최근 활동에 쌓여요. 상담·아이디어·투표·댓글과 함께 시간순으로 보이고, 이벤트 이름 옆에 속성이 몇 개 함께 보여요.
Lenit.track("Order Completed", { plan: "pro", amount: 29000 });사용자 식별(userId)로 들어온 고객의 이벤트만 기록돼요 — 익명 방문자의 이벤트는 남지 않아요. 이벤트는 고객 그룹 조건이나 캠페인 대상에 쓰이지 않으니, 그룹으로 나눌 값은 traits 로 넘기세요.
로그인·로그아웃과 위젯
SPA 에서 로그인했는데 위젯이 계속 익명이에요
로그인을 마친 뒤 Lenit.push(설정) 을 한 번 더 부르세요. 위젯은 설치 코드에 넘긴 값으로 고객을 알아봐요. 새로고침 없이 화면만 바뀌는 사이트(SPA)는 처음 그린 위젯이 익명 그대로라, 로그인한 사람의 값(userId·token·getToken)을 담아 다시 부르면 위젯을 새로 그리며 그 사람으로 식별해요.
// 로그인 성공 직후 — fetchLenitToken 은 서버에서 새 JWT 를 받아 오는 함수
Lenit.push({ boardKey: "vb_live_…", getToken: fetchLenitToken });페이지를 새로 여는 사이트는 따로 할 일이 없어요 — 로그인 뒤 첫 페이지의 설치 코드가 로그인한 사람의 값을 넘기면 돼요.
우리 서비스에서 로그아웃할 때 위젯도 로그아웃시키려면?
로그아웃 처리에서 Lenit.reset()(같은 함수 Lenit.logout())을 부르세요. 위젯에 저장된 세션·상담 신원·안 읽은 표시를 지우고, 열린 위젯을 닫은 뒤 익명으로 다시 시작해요.
페이지를 새로 여는 사이트는 로그아웃 뒤 다음 페이지의 설치 코드에 userId 가 없거나 다른 값이 넘어가는 순간 위젯이 이전 사람의 정보를 알아서 버려요. 새로고침 없이 로그아웃하는 SPA 는 reset 을 불러야 그 자리에서 바뀌어요.
공용 PC 에서 고객이 바뀌면 이전 사람의 상담이 보이지 않나요?
보이지 않아요. 설치 코드의 userId(또는 토큰 속 userId)가 바뀌는 순간 위젯이 이전 사람의 세션·상담 신원·알림 표시를 버리고 새로 식별해요. 다만 새로고침 없이 로그아웃하는 화면에서 Lenit.reset() 을 부르지 않으면, 다음 사람이 로그인할 때까지 위젯은 이전 사람으로 남아 있어요.
다시 식별하는 때와 위젯 세션
위젯은 언제 고객을 다시 식별하나요?
getToken 을 쓰면 위젯이 뜰 때마다 다시 식별해요. 고정 token 이나 userId(서명 포함)를 쓰면 같은 브라우저에서는 저장해 둔 세션을 이어 쓰고, 아래일 때만 다시 식별해요.
- 그 브라우저에서 위젯이 처음 뜰 때
- 설치 코드의 사람이 바뀌었을 때 — 로그인·로그아웃·다른 회원
- 직전 식별 뒤 6시간이 지나 위젯이 다시 뜰 때
- 위젯 세션이 끝났을 때(아래 ‘위젯 세션은 얼마나 유지되나요?’)
고객 속성(traits)과 서명으로 넘긴 이름·이메일·사진은 다시 식별할 때 갱신돼요.
고객 속성(traits)을 바꿨는데 늦게 반영돼요
속성은 위젯이 다시 식별할 때만 반영돼요. 고정 토큰이나 userId 를 쓰면 같은 브라우저에서는 직전 식별 뒤 6시간이 지나 위젯이 다시 뜰 때까지 이전 값이 남아요. 요금제처럼 바로 반영돼야 하는 값은 getToken 으로 토큰을 받게 하세요 — 위젯이 뜰 때마다 새 토큰으로 다시 식별해요.
고객 목록의 마지막 방문은 이와 따로, 위젯이 떠 있고 탭이 보이는 동안 1분마다 갱신돼요.
위젯 세션은 얼마나 유지되나요?
마지막으로 쓴 뒤 24시간이에요. 위젯은 식별할 때 받은 세션으로 상담·알림을 주고받고, 쓰는 동안은 1시간마다 저절로 연장돼요. 세션이 끝나면 다음에 위젯이 뜰 때 알아서 다시 식별하니 따로 할 일은 없어요.
JWT 의 만료 시간(exp)과는 따로예요 — 토큰은 식별할 때만 쓰여요. 다시 식별할 때 고정 토큰이 이미 만료됐다면 그 고객은 익명으로 열리니, 페이지마다 새 토큰을 넣거나 getToken 을 쓰세요.
고객이 하루 지나 다시 오거나 다른 기기에서 열면 지난 상담이 보이나요?
서명(JWT·userId + 서명)으로 식별한 고객은 어느 기기에서든 자기 상담이 모두 보여요.
서명 없이 userId 만 보내거나 익명으로 문의한 고객은 그 브라우저의 위젯 세션에서 만든 상담만 보여요(회사가 먼저 보낸 메시지 중 아직 답하지 않은 것은 보여요). 그래서 다른 기기·브라우저에서는 지난 상담이 보이지 않고, 24시간 넘게 오지 않아 세션이 끝나면 같은 브라우저에서도 위젯 목록에서 사라져요. 서명 없는 userId 는 누구나 흉내 낼 수 있어서예요.
상담은 인박스에 그대로 있고, 고객은 답장 알림 메일의 대화 이어가기로 그 상담에 돌아갈 수 있어요. 기기를 바꿔도 보이게 하려면 서명 방식으로 식별하세요.
페이지 기록과 개인정보
위젯은 어떤 페이지 정보를 보내나요?
고객이 본 페이지의 주소와 제목을 보내 인박스 고객 정보 패널의 최근 본 페이지에 보여 줘요. 처음 뜬 페이지와, 새로고침 없이 화면이 바뀔 때(SPA 라우팅)도 따라가요. 같은 주소는 5분에 한 번만 보내요.
사용자 식별(userId)로 들어온 고객만 기록돼요. 끄려면 설치 코드에 trackPageView: false 를 넣으세요. 브라우저·OS·언어·시간대·유입 경로 같은 접속 환경은 이 설정과 상관없이 식별할 때 함께 보내요.
페이지 주소에 들어 있는 토큰 같은 값도 저장되나요?
아니요. 위젯은 레닛으로 보내는 페이지 주소에서 출처와 경로만 남기고, 쿼리는 utm_source·utm_medium·utm_campaign·utm_term·utm_content·ref 만 남기며, # 뒷부분은 지워요. 페이지 기록·track 이벤트·상담을 시작한 페이지·유입 경로가 모두 같은 규칙이라, ?token=·#access_token= 같은 값은 레닛에 저장되지 않아요.
보안 정책(CSP)과 모바일
CSP 때문에 위젯이 안 떠요. 어떤 주소를 허용해야 하나요?
스크립트와 위젯 화면은 https://lenit.cloud, 통신은 https://api.lenit.cloud 를 허용하세요. 위젯은 https://lenit.cloud/widget.js 를 불러 같은 주소의 위젯 화면(iframe)을 띄우고, 실시간 알림을 포함한 통신은 https://api.lenit.cloud 와 해요.
| CSP 지시어 | 허용할 주소 |
|---|---|
script-src | https://lenit.cloud |
frame-src | https://lenit.cloud |
connect-src | https://api.lenit.cloud |
런처 위 새 답변 미리보기의 사진·이미지는 여러분 페이지에서 바로 불러와요. img-src 를 좁게 막아 두었다면 미리보기의 사진만 안 보이고 위젯은 그대로 동작해요.
모바일에서는 위젯이 어떻게 보이나요?
위젯을 처음 열 때 화면 폭이 520px 보다 좁으면 화면 전체를 덮어요. 열려 있는 동안 런처 버튼을 숨기고 뒤 페이지 스크롤을 잠그며, 위젯 위쪽의 닫기(X)로 닫아요.
그보다 넓으면 런처 위에 폭 400px 패널로 열려요(높이는 최대 720px, 화면이 낮으면 줄어요). 공지·도움말 문서·캠페인 본문을 펼치면 폭 470px 로 넓어져요. 런처는 지름 60px 원형 버튼이고, 화면 아래 모서리에서 24px 떨어져 있어요.