incento 개발자센터MPA 연동
MPA(Multi-Page Application) 환경에서 인센토 위젯을 연동하는 가이드입니다.
이 가이드는 페이지 이동 시 전체 새로고침이 일어나는 일반 웹사이트(MPA) 기준입니다.
React · Vue · Next.js 등 SPA 환경은 SPA 연동 가이드를 참고하세요. 연동 전 필요한 조건은 사전 준비에서 확인하세요.
연동 절차
스크립트 삽입 (snippet)
모든 페이지의 <head> 또는 <body> 안에 아래 스니펫을 삽입합니다. 스니펫은 실제 SDK
파일을 비동기로 로드하는 로더이며, 한 페이지에 중복 삽입해도 한 번만 실행됩니다.
<script>(function(){var w=window;if(w.Incento&&!w.Incento.q){return;}var i=function(){i.c(arguments);};i.q=[];i.c=function(a){i.q.push(a);};w.Incento=i;function l(){if(w.IncentoInitialized){return;}w.IncentoInitialized=true;var s=document.createElement('script');s.type='text/javascript';s.async=true;s.src='https://s3.incento.kr/scripts/sdk/incento.min.js';var x=document.getElementsByTagName('script')[0];if(x.parentNode){x.parentNode.insertBefore(s,x);}}if(document.readyState==='complete'){l();}else{w.addEventListener('DOMContentLoaded',l);w.addEventListener('load',l);}})();</script>boot — SDK 초기화
boot는 SDK의 진입점으로, 캠페인 조회 및 위젯 마운트를 시작합니다. 스니펫이
window.Incento를 커맨드 큐로 즉시 정의하므로, SDK 파일 로드가 끝나기 전에 호출해도
큐에 쌓였다가 로드 후 순서대로 처리됩니다.
<script>
Incento('boot', {
apiKey: 'inc_pk_YOUR_KEY'
});
</script><script>
Incento('boot', {
apiKey: 'inc_pk_YOUR_KEY',
userId: '회원_고유_ID'
});
</script>전체 파라미터와 boot 동작 순서는 boot 파라미터 레퍼런스를 참고하세요.
loginRequired 이벤트 등록
위젯 내 로그인 버튼이 동작하려면 loginRequired 이벤트를 반드시 등록해야 합니다.
자세한 내용은 이벤트 훅 절을 참고하세요.
이벤트 훅
Incento('on', 이벤트명, 핸들러) 형태로 등록합니다. boot 이전이든 이후든 언제든 등록할 수
있고, 같은 이벤트에 여러 핸들러를 등록하면 등록 순서대로 모두 호출됩니다. 이벤트 목록과 공통
규칙은 이벤트 훅 레퍼런스에 정리되어 있습니다.
loginRequired (필수)
미등록 시 위젯 내 [로그인] 버튼이 동작하지 않습니다. 반드시 등록하세요.
<script>
Incento('on', 'loginRequired', function() {
// 로그인 완료 후 위젯을 자동으로 열려면 returnUrl에 incento_popup=true를 추가합니다.
var returnUrl = window.location.href
+ (window.location.search ? '&' : '?')
+ 'incento_popup=true';
window.location.href = '/login?returnUrl=' + encodeURIComponent(returnUrl);
});
</script>incento_popup=true를 returnUrl에 포함하면 로그인 완료 후 원래 페이지로 돌아왔을 때 위젯이 자동으로 열립니다. 참고: URL 파라미터returnUrl파라미터명은 고객사 로그인 페이지에서 사용하는 이름으로 변경하세요.
widgetOpen / widgetClose
<script>
Incento('on', 'widgetOpen', function() {
console.log('위젯이 열렸습니다');
});
Incento('on', 'widgetClose', function() {
console.log('위젯이 닫혔습니다');
});
</script>커스텀 버튼
id가 show-incento-widget인 요소를 클릭하면 위젯이 열립니다. SDK가 자동으로 클릭 이벤트를
연결합니다.
<button id="show-incento-widget">혜택 받기</button>여러 요소에 같은 id를 사용해도 모두 동작합니다. SDK는 DOM에 즉시 존재하지 않는 경우에도 최대 10초간 DOM 추가를 감지하므로, 동적으로 삽입되는 버튼에도 적용됩니다.
shutdown — SDK 종료
<script>
Incento('shutdown');
</script>shutdown은 SDK가 삽입한 DOM 요소를 제거하고 초기화 플래그를 리셋합니다.
제거되는 요소
#incento-widget(위젯 iframe 컨테이너)#incento-launcher(런처 버튼)#show-incento-widget요소들 (hidden = true처리)
shutdown 이후 Incento('boot', ...)를 재호출하면 다시 초기화할 수 있습니다.
<script>
// 로그아웃 시 shutdown 후 비로그인 상태로 재boot하는 예시
Incento('shutdown');
Incento('boot', { apiKey: 'inc_pk_YOUR_KEY' }); // userId 없이
</script>MPA에서는 페이지 이동 시 자동으로 새로고침되므로 일반적으로 shutdown을 명시적으로
호출할 필요가 없습니다. 주로 로그아웃 처리나 특정 시점에 위젯을 완전히 제거할 때 사용합니다.