incento 개발자센터MPA 연동
MPA(Multi-Page Application) 환경에서 인센토 위젯을 연동하는 가이드입니다.
이 가이드는 페이지를 이동할 때마다 전체 새로고침이 일어나는 전통적 웹사이트(MPA)를 기준으로 합니다.
React · Vue 등 SPA나 Next.js(App Router) · Nuxt처럼 페이지 전환이 전체 새로고침 없이 일어나는 소프트 네비게이션 환경은 SDK > SPA 연동을 참고하세요. 연동 전 필요한 조건은 SDK > 사전 준비에서 확인하세요.
실제 동작 예제는 github.com/OpenFormatKorea/incento-sdk-sample-apps를 참고해주세요.
연동 절차
스크립트 삽입 (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>SDK 설치 이전부터 존재하던 기존 회원은 회원의 원래 가입 일시를 userCreatedAt로 함께
전달하세요. 고객사 회원 DB의 가입 일시를 그대로 넘기면 됩니다.
<script>
Incento('boot', {
apiKey: 'inc_pk_YOUR_KEY',
userId: '회원_고유_ID',
userCreatedAt: '2023-03-15T09:30:00+09:00' // 회원 DB의 원래 가입 일시 (ISO 8601)
});
</script>자세한 내용은 boot 파라미터 레퍼런스 — userCreatedAt을 참고하세요.
전체 파라미터와 boot 동작 순서는 boot 파라미터 레퍼런스를 참고하세요.
loginRequired 이벤트 등록
위젯 내 로그인 버튼이 동작하려면 loginRequired 이벤트를 반드시 등록해야 합니다.
자세한 내용은 이벤트 훅 절을 참고하세요.
경로 추적
대시보드의 '경로별 리퍼럴 시도 횟수' 차트는 어느 경로에서 공유가 일어났는지 집계합니다.
MPA는 페이지 이동 시 전체 새로고침으로 스니펫과 boot가 다시 실행되므로 현재 경로가 자동으로
반영됩니다. SPA·네이티브와 달리 setPath를 직접 호출할 필요가 없습니다.
기본 경로는 location.pathname입니다. 차트에 표시할 경로를 정규화하고 싶다면 boot에
pagePath를 명시할 수 있습니다(예: 동적 id가 포함된 URL을 /products로). 자세한 내용은
경로별 리퍼럴 시도 추적을 참고하세요.
<script>
Incento('boot', { apiKey: 'inc_pk_YOUR_KEY', pagePath: '/products' });
</script>이벤트 훅
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>커스텀 런처
기본 런처 대신 직접 만든 버튼으로 위젯을 열려면, boot에서 visible: false로 기본 런처를 숨기고 버튼 클릭 시 open을 호출합니다.
<script>
// boot 시 기본 런처 숨김
Incento('boot', { apiKey: 'inc_pk_YOUR_KEY', visible: false });
</script>
<button onclick="Incento('open')">혜택 받기</button>위젯 닫기(close)나 사용자 클릭 없는 조건·시점 기반 자동 오픈 등 open / close의 상세
동작과 사용 시점은 위젯 열기/닫기 레퍼런스를 참고하세요.
shutdown — SDK 종료
<script>
Incento('shutdown');
</script>shutdown은 SDK가 삽입한 DOM 요소를 제거하고 초기화 플래그를 리셋합니다.
제거되는 요소
#incento-widget(위젯 iframe 컨테이너)#incento-launcher(런처)
shutdown 이후 Incento('boot', ...)를 재호출하면 다시 초기화할 수 있습니다.
<script>
// 로그아웃 시 shutdown 후 비로그인 상태로 재boot하는 예시
Incento('shutdown');
Incento('boot', { apiKey: 'inc_pk_YOUR_KEY' }); // userId 없이
</script>MPA에서는 페이지 이동 시 자동으로 새로고침되므로 일반적으로 shutdown을 명시적으로
호출할 필요가 없습니다. 주로 로그아웃 처리나 특정 시점에 위젯을 완전히 제거할 때 사용합니다.