젠서 디스커버리 미니

1. 개요

젠서 디스커버리 미니는 고객사 사이트에 코드 한 줄만 넣으면 자동으로 나타나는 연동 방식입니다.
젠서 디스커버리 미니 안에서 사용자가 상품을 클릭해 상세 페이지로 이동하려 할 때, 그 동작을 고객사가 원하는 방식(자체 페이지 이동 로직 등)으로 직접 연결할 수 있도록 "이벤트가 발생하면 자동으로 실행되는 함수(콜백)"를 제공합니다.

2. 연동 방식

2-1. Quick Start

아래 코드 조각(스니펫)을 페이지에 붙여 넣으면, 이 코드가 실제 위젯 프로그램(메인 스크립트)을 자동으로 불러와(로더) 초기화까지 진행합니다.

<script>
  (function (w, d, s, l) {
    w[l] = w[l] || { q: [] };
    if (!w[l].init) {
      w[l].init = function (c) {
        w[l].q.push({ c: c });
      };
    }
    var f = d.getElementsByTagName(s)[0];
    var j = d.createElement(s);
    j.async = true;
    j.setAttribute('data-vendor-id', 'YOUR_VENDOR_ID');
    j.src = 'https://cdn.genser.ai/dist/genser-discovery-loader-kr.min.js';
    f.parentNode.insertBefore(j, f);
  })(window, document, 'script', 'genserDiscovery');

  window.genserDiscovery.init({
    vendorId: 'YOUR_VENDOR_ID',
    environment: 'web',
    onUrlOpen: function (payload, context) {
      var url = payload.pcUrl || payload.mobileUrl || payload.fallbackUrl;
      if (!url) return { ok: false, reason: 'url_not_found' };
      window.location.href = url;
      return { ok: true, url: url };
    },
  });
</script>

2-2. init(config)

역할: 이 함수를 호출해야 위젯이 실제로 화면에 나타나고 동작을 시작합니다.
함수명: window.genserDiscovery.init
반환: 실행 결과를 비동기로 알려주는 값(Promise)
파라미터

옵션

타입

필수

설명

vendorId

string

필수

고객사 식별 ID

onUrlOpen

function

권장

상품 상세/외부 이동 이벤트 처리 콜백 (3장 참고)

environment

'web' | 'webview'

실행 환경. 미지정 시 자동 감지

onReady

function

UI 렌더링 완료 후 1회 호출

onError

function

초기화/로드 실패 시 에러 객체와 함께 호출

2-3. 콜백 이름 (alias)

이동 처리 콜백은 아래 이름 중 하나로 지정할 수 있으며, 여러 개를 넣으면 위에서부터 우선 적용됩니다.

onOpen > openCallback > onUrlOpen > onProductOpenDetail > onProductDetail > productDetailCallback

onUrlOpen을 표준으로 사용하는 것을 권장합니다.

2-4. environment 자동 감지

environment를 지정하지 않으면 SDK가 실행 환경을 자동 감지합니다. 네이티브 WebView(브릿지 존재) 환경이면 webview, 그 외에는 web으로 동작합니다. 일반 웹 연동 시에는 environment: 'web' 명시를 권장합니다.

2-5. 위젯 유형 (기본 / 커스텀)

위젯 유형은 어드민에서 설정하며, 두 가지 방식이 있습니다.

기본: 별도 스크립트 작업 없이, SDK가 제공하는 오버레이 트리거를 그대로 사용합니다.
커스텀: SDK가 제공하는 기본 위젯 요소 대신 고객사가 직접 만든 요소(버튼 등)를 트리거로 사용합니다. 이 경우 해당 요소의 클릭 이벤트에 open()을, 닫는 동작이 필요한 지점에는 close()를 직접 연결해줘야 합니다.

document.querySelector('#my-custom-trigger').addEventListener('click', function () {
  window.genserDiscovery.open();
});

document.querySelector('#my-custom-close-button').addEventListener('click', function () {
  window.genserDiscovery.close();
});

위젯 유형을 커스텀으로 설정한 경우, open()/close()를 연결하지 않으면 오버레이가 열리거나 닫히지 않습니다. open()/close()의 상세 스펙은 [5. API 레퍼런스]를 참고해 주세요.

3. 이벤트 처리 방식

사용자가 위젯에서 상품을 클릭했을 때, 그 클릭을 우리 사이트가 알아채고 반응하도록 만드는 방법은 두 가지입니다: 콜백 방식(이벤트가 발생하면 자동 실행되는 함수를 init()에 미리 등록하는 onUrlOpen)과 구독 방식(원하는 이벤트만 따로 등록해서 듣는 on/off).

product.openDetail 이벤트가 팝업(모달)을 거쳐 발생할지, 클릭 즉시 발생할지는 어드민의 [부가 옵션 > 상품 카드 > PDP 오픈 방식] 설정에 따라 달라집니다.

이벤트명

설명

product.openDetail

상품 상세 페이지 이동 요청

3-1. onUrlOpen (콜백 방식)

onUrlOpen(payload, context)

콜백 인자는 payload, context 2개입니다. 이벤트 타입이 필요하면 context.message.type으로 확인합니다.

인자

설명

payload

클릭된 상품의 정보와 이동할 URL이 담긴 데이터

context

이 이벤트에 대해 응답(회신)할 수 있는 통로가 되는 객체 (원본 메시지는 context.message, 응답 함수는 context.reply)

payload 필드

필드

타입

설명

productSku

string

상품 SKU

pcUrl

string

PC 이동 URL

mobileUrl

string | null

Mobile 이동 URL

fallbackUrl

string

기본 fallback URL

source

string

이벤트 발생 위치 (예: product-card)

utmParams

object

(선택) URL 쿼리로 병합할 UTM 파라미터

예시

{
  "productSku": "3370616",
  "pcUrl": "https://shop.example.com/product/3370616",
  "mobileUrl": null,
  "fallbackUrl": "https://shop.example.com/product/3370616",
  "source": "product-card"
}

URL 우선순위

이동 URL은 아래 순서로 선택하는 것을 권장합니다. (SDK 기본 처리도 동일한 순서를 사용합니다.)

우선순위

필드

payload.pcUrl

payload.mobileUrl

payload.fallbackUrl

권장 예시

function handleUrlOpen(payload, context) {
  var url = payload.pcUrl || payload.mobileUrl || payload.fallbackUrl;
  if (!url) {
    return { ok: false, reason: 'url_not_found' };
  }
  window.location.href = url;
  return { ok: true, url: url };
}

window.genserDiscovery.init({
  vendorId: 'YOUR_VENDOR_ID',
  environment: 'web',
  onUrlOpen: handleUrlOpen,
});

3-2. on / off (구독 방식)

init()에 콜백을 등록하는 대신, 원하는 이벤트가 발생할 때마다 실행할 동작을 별도로 미리 등록(구독)해둘 수도 있습니다.

window.genserDiscovery.on('product.openDetail', function (payload, context) {
  var url = payload.pcUrl || payload.mobileUrl || payload.fallbackUrl;
  if (!url) {
    context.reply('product.openDetail.result', { ok: false, reason: 'url_not_found' });
    return;
  }
  window.location.href = url;
  context.reply('product.openDetail.result', { ok: true, url: url });
});

on()은 반환값이 자동 회신되지 않습니다.

on()으로 구독한 핸들러는 반환값이 자동으로 회신되지 않으므로, 반드시 context.reply('<이벤트명>.result', { … })로 직접 결과를 회신해야 합니다. (반면 init의 onUrlOpen은 반환값이 자동 회신됩니다.(3-1 참고)

구독 해제

window.genserDiscovery.off('product.openDetail', handler); // 특정 핸들러만 해제
window.genserDiscovery.off('product.openDetail');          // 해당 타입 전체 해제

4. 환경별 주의 사항

4-1. SPA

SPA(페이지를 이동해도 새로고침 없이 화면 일부만 바뀌는 방식)에서는 앱 최초 진입 시 1회만 스니펫을 로드하고 init()을 호출합니다. 이후 라우팅(페이지 이동) 시에는 init()을 반복 호출하지 마세요.

4-2. JSP

JSP(페이지를 이동할 때마다 화면이 통째로 새로고침되는 방식)는 페이지 이동 시마다 전체 페이지가 새로고침되므로, 페이지 템플릿에 스니펫과 init()을 함께 넣습니다.

<script>
  window.genserDiscovery.init({
    vendorId: '<%= vendorId %>',
    environment: 'web',
    onUrlOpen: handleUrlOpen,
  });
</script>

5. API 레퍼런스

window.genserDiscovery에서 제공하는 주요 메서드입니다.

메서드

반환

설명

init(config)

Promise

초기화. 옵션은 2장 참고

on(type, handler)

이벤트 구독 (3-2 참고)

off(type, handler?)

이벤트 구독 해제

open()

미니 오버레이 열기. active 상태에서만 동작하며, 열려있는 상태에서 재호출 시 동작 없음

close()

미니 오버레이 닫기. 닫혀있는 상태에서 재호출 시 동작 없음

toggle()

Discovery 오버레이 열기/닫기 토글

changeLanguage(lang)

boolean

iframe 재로드 없이 앱 언어 변경. 지원 lang 값(ko, en, ja)

toggle, changeLanguage 등은 메인 스크립트 로드 및 렌더링 완료 이후에 동작합니다. open()/close()는 파라미터와 반환값이 없으며, 위젯 유형(기본/커스텀)과 무관하게 모두 사용할 수 있습니다.

6. 작성 예시

코드 작성 예시를 보여줍니다.

<script>
  (function (w, d, s, l) {
    w[l] = w[l] || { q: [] };
    if (!w[l].init) {
      w[l].init = function (c) {
        w[l].q.push({ c: c });
      };
    }
    var f = d.getElementsByTagName(s)[0];
    var j = d.createElement(s);
    j.async = true;
    j.setAttribute('data-vendor-id', 'YOUR_VENDOR_ID');
    j.src = 'https://cdn.genser.ai/dist/genser-discovery-loader-kr.min.js';
    f.parentNode.insertBefore(j, f);
  })(window, document, 'script', 'genserDiscovery');

  function handleUrlOpen(payload, context) {
    var url = payload.pcUrl || payload.mobileUrl || payload.fallbackUrl;
    if (!url) {
      return { ok: false, reason: 'url_not_found' };
    }
    window.location.href = url;
    return { ok: true, url: url };
  }

  window.genserDiscovery.init({
    vendorId: 'YOUR_VENDOR_ID',
    environment: 'web',
    onUrlOpen: handleUrlOpen,
    onReady: function () {
      console.log('Genser Discovery Mini ready');
    },
    onError: function (err) {
      console.error('Genser Discovery Mini init failed', err);
    },
  });
</script>

7. 유의 사항

로더 파일명은 genser-discovery-loader-kr.min.js를 사용해 주세요.
vendorId는 고객사 식별 값으로, 임의 변경 시 데이터 집계에 영향을 줄 수 있습니다.
SPA 환경에서는 init() 중복 호출을 피해 주세요.
on() 구독 방식을 사용할 경우 반드시 context.reply(...)로 결과를 회신해 주세요.
회신하지 않으면 응답 대기 상태로 남을 수 있습니다.

이전스크립트 가이드 다음앱 임베드 가이드

마지막 업데이트 15일 전