> For the complete documentation index, see [llms.txt](https://help.genser.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.genser.ai/developers/script-guide/genser-discovery-mini.md).

# 젠서 디스커버리 미니

## **1. 개요**

<figure><img src="https://2560922032-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyYVX6HW5LNuPHRnSB2po%2Fuploads%2FlDtOcjdoq83AXJzsz12q%2F%EC%A0%A0%EC%84%9C%EB%94%94%EC%8A%A4%EC%BB%A4%EB%B2%84%EB%A6%AC%EB%AF%B8%EB%8B%88-%ED%9D%90%EB%A6%84%EB%8F%84.png?alt=media" alt=""><figcaption></figcaption></figure>

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

### 1-1. 한눈에 보기

위젯을 띄우는 데 꼭 필요한 것은 **스니펫과 `init()` 두 가지**입니다. 나머지는 필요한 것만 골라 더하면 됩니다. 상품을 누르면 상세 페이지로 이동하는 동작(utm 포함)은 따로 넣지 않아도 됩니다.

<table data-search="false"><thead><tr><th>하고 싶은 것</th><th>쓰는 것</th><th>필요한 경우</th><th>자세히</th></tr></thead><tbody><tr><td>위젯 띄우기</td><td>스니펫 + <code>init()</code></td><td>필수</td><td><p><a href="#id-2-1.-quick-start"><strong>2-1. Quick Start</strong></a></p><p><a href="#id-2-2.-init-config"><strong>2-2. init(config)</strong></a></p></td></tr><tr><td>상품 이동을 직접 처리 (앱 웹뷰, 자체 라우터 등)</td><td><code>init()</code>의 <code>onUrlOpen</code></td><td>선택</td><td><a href="#id-3-1.-onurlopen"><strong>3-1. onUrlOpen</strong></a></td></tr><tr><td>직접 만든 버튼으로 오버레이 열고 닫기</td><td><code>open()</code> · <code>close()</code> · <code>toggle()</code></td><td>위젯 유형이 커스텀일 때</td><td><a href="#id-2-5"><strong>2-5. 위젯 유형</strong></a></td></tr><tr><td>일부 방문자에게만 위젯 보이기 (예: 회원만)</td><td><code>showWidget()</code> · <code>hideWidget()</code></td><td>선택</td><td><a href="#id-2-6"><strong>2-6. 위젯 보이기 / 숨기기</strong></a></td></tr><tr><td>로그인 회원의 지난 대화를 계정에 저장</td><td><code>login(memberId)</code> · <code>logout()</code></td><td>선택</td><td><a href="#id-4"><strong>4. 로그인 연동</strong></a></td></tr><tr><td>언어 바꾸기</td><td><code>changeLanguage(lang)</code></td><td>선택</td><td><a href="#id-6.-api"><strong>6. API 레퍼런스</strong></a></td></tr><tr><td>상품 클릭 이벤트를 따로 받기</td><td><code>on()</code> · <code>off()</code></td><td>선택</td><td><a href="#id-3-2.-on-off"><strong>3-2. on / off</strong></a></td></tr></tbody></table>

상황별 전체 코드는 [**\[7. 작성 예시\]**](#id-7)에 있습니다.

### 1-2. 부르는 시점

스니펫은 메인 스크립트를 비동기로 불러옵니다. 그래서 함수마다 **부를 수 있는 시점이 다릅니다.**

| 시점                                           | 쓸 수 있는 함수                                                                                          |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| 스니펫 바로 다음 (메인 스크립트가 뜨기 전에도 됨)                | `init()` · `showWidget()` · `hideWidget()`                                                         |
| 메인 스크립트가 뜬 뒤 (`init()`의 `onReady` 안 또는 그 이후) | `login()` · `logout()` · `open()` · `close()` · `toggle()` · `changeLanguage()` · `on()` · `off()` |

`showWidget()` · `hideWidget()`을 스니펫 바로 다음에 부르려면 두 함수를 받아 두는 줄이 든 스니펫이 필요합니다. ([**2-1 참고**](#id-2-1.-quick-start))

{% hint style="warning" %}
**아래 줄 함수(`login()` 등)는 메인 스크립트가 뜨기 전에 부르면 함수가 없어 오류가 날 수 있습니다.** 페이지를 열자마자 불러야 하는 `login()`은 `init()`의 `onReady` 안에서 호출해 주세요. ([**4-3 참고**](#id-4-3.-login-memberid))
{% endhint %}

`showWidget()` · `hideWidget()` · `login()`으로 바꾼 상태는 **그 페이지에서만 유지**됩니다. 페이지를 이동할 때마다 화면이 새로 뜨는 사이트(JSP 등)는 페이지마다 다시 호출해 주세요.

***

## **2. 연동 방식**

### 2-1. Quick Start

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

```html
<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 });
      };
    }
    ['showWidget', 'hideWidget'].forEach(function (m) {
      if (!w[l][m]) {
        w[l][m] = function () {
          w[l].q.push({ type: m, args: [].slice.call(arguments) });
        };
      }
    });
    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',
  });
</script>
```

{% hint style="warning" %}
**스니펫 앞부분의 `['showWidget', 'hideWidget'].forEach…` 줄은 지우지 마세요.** 메인 스크립트가 뜨기 전에 부른 `showWidget()` · `hideWidget()`을 받아 두는 줄입니다. 이 줄이 없으면 스니펫 바로 다음에 두 함수를 부를 때 `is not a function` 오류가 나고, 그 아래 코드가 실행되지 않습니다. 이 줄이 없는 스니펫을 쓰고 있다면 위 코드로 바꿔 주세요.

스니펫은 다른 코드보다 먼저 실행되어야 합니다. 스니펫보다 먼저 `showWidget()` · `hideWidget()`을 부르면 동작하지 않습니다. ([**2-6 참고**](#id-2-6))
{% endhint %}

### 2-2. init(config)

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

| 옵션          | 타입                 | 필수 | 설명                                                                                 |
| ----------- | ------------------ | -- | ---------------------------------------------------------------------------------- |
| vendorId    | string             | 필수 | 고객사 식별 ID                                                                          |
| onUrlOpen   | function           | -  | 상품 이동을 직접 처리할 때만 쓰는 콜백. 일반 웹 설치에서는 넣지 않습니다 ([**3-1 참고**](#id-3-1.-onurlopen))      |
| environment | 'web' \| 'webview' | -  | 실행 환경. 미지정 시 자동 감지                                                                 |
| onReady     | function           | -  | UI 렌더링 완료 후 1회 호출. `login()` 등 메인 스크립트가 뜬 뒤에 쓰는 함수는 여기서 호출 ([**1-2 참고**](#id-1-2)) |
| 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()`를 직접 연결해줘야 합니다.

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

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

{% hint style="info" %}
위젯 유형을 커스텀으로 설정한 경우, `open()`/`close()`를 연결하지 않으면 오버레이가 열리거나 닫히지 않습니다. `open()`/`close()`의 상세 스펙은 [**\[6. API 레퍼런스\]**](#id-6.-api)를 참고해 주세요.
{% endhint %}

### 2-6. 위젯 보이기 / 숨기기

* 역할: 방문자 조건에 따라 위젯을 보이거나 숨깁니다. 예를 들어 로그인한 회원에게만 위젯을 보여줄 때 씁니다.
* 함수명: `window.genserDiscovery.showWidget()`, `window.genserDiscovery.hideWidget()`
* 반환: 없음

```js
// 회원에게만 위젯 보이기
if (isMember) {
  window.genserDiscovery.showWidget();
} else {
  window.genserDiscovery.hideWidget();
}
```

| 항목                         | 동작                                                                                                                                  |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| 숨기는 범위                     | 위젯과 오버레이를 모두 숨깁니다. 오버레이가 열려 있으면 닫고 숨깁니다                                                                                             |
| 숨긴 동안                      | `open()` · `toggle()`이나 링크로 여는 기능으로도 열리지 않습니다                                                                                       |
| 부르는 시점                     | 스니펫 바로 다음부터 `init()` 전후 언제든 부를 수 있습니다. 화면에 그리기 전에 반영되어, 위젯이 잠깐 보였다가 사라지지 않습니다. 2-1의 스니펫이 필요합니다 ([**2-1 참고**](#id-2-1.-quick-start)) |
| 유지 범위                      | 그 페이지에서만 유지됩니다. 페이지가 새로 뜨면 다시 보이므로 페이지마다 호출해 주세요                                                                                    |
| 어드민 설정과의 관계                | 어드민에서 위젯을 끈 경우 `showWidget()`으로 켜지지 않습니다                                                                                            |
| init 옵션 `hideWidget: true` | 쓰지 마세요. 이 옵션으로 숨기면 `showWidget()`으로 다시 보이지 않습니다. 숨김은 `hideWidget()` 함수로 해 주세요                                                       |

{% hint style="info" %}
숨김은 화면에서 감추는 기능입니다. 비로그인 방문자 페이지에 위젯 스크립트를 아예 넣지 않으려면, 서버에서 로그인 상태일 때만 스니펫을 출력하는 방식도 쓸 수 있습니다.

회원 전용으로 쓰면서 지난 대화도 회원 계정에 저장하려면 [**\[4. 로그인 연동\]**](#id-4)을 함께 써 주세요. 전체 코드는 [**\[7-2. 회원에게만 보이기 + 로그인 연동\]**](#id-7-2.--jsp)에 있습니다.
{% endhint %}

***

## **3. 이벤트 처리 방식**

상품을 클릭하면 스크립트가 상품 URL에 utm을 붙여 이동합니다. 팝업 여부와 새 창/현재 창은 어드민 PDP 오픈 방식 설정을 따릅니다. 일반 웹 설치에서는 따로 할 일이 없습니다.

앱 웹뷰, 자체 라우터 이동처럼 이동을 직접 처리해야 할 때만 아래 두 방법 중 하나를 씁니다: **콜백 방식**(이벤트가 발생하면 자동 실행되는 함수를 `init()`에 미리 등록하는 `onUrlOpen`)과 **구독 방식**(원하는 이벤트만 따로 등록해서 듣는 `on`/`off`). 이때 스크립트는 이동하지 않고 고객사 코드만 실행되므로, utm은 `payload.utmParams`를 URL에 직접 붙여야 합니다.

{% hint style="info" %}
상품을 클릭했을 때 팝업(모달)을 거칠지 바로 이동할지, 현재 창에서 이동할지 새 창으로 열지는 어드민의 [**\[부가 옵션 > 상품 카드 > PDP 오픈 방식\]**](https://help.genser.ai/design/additional-options#id-2-2.-pdp) 설정을 따릅니다. **창 열기 방식이 새 창이면 콜백과 구독 핸들러는 실행되지 않고, 스크립트가 utm을 붙여 새 창으로 엽니다.**
{% endhint %}

| 이벤트명               | 설명              |
| ------------------ | --------------- |
| product.openDetail | 상품 상세 페이지 이동 요청 |

### 3-1. onUrlOpen (콜백 방식)

일반 웹 설치에서는 넣지 않습니다. 이동을 직접 처리해야 할 때(앱 웹뷰, 자체 라우터 이동 등)만 씁니다.

{% hint style="warning" %}
**넣으면 스크립트는 이동하지 않고 이 콜백만 실행됩니다.** utm이 빠지지 않도록 `payload.utmParams`를 URL에 붙여 주세요(아래 예시). `pcUrl` 등에 이미 붙어 있는 파라미터(genserRequestId 등)는 지우지 말고 그대로 써 주세요.
{% endhint %}

```
onUrlOpen(payload, context)
```

{% hint style="warning" %}
**콜백 인자는 payload, context 2개입니다.**\
이벤트 타입이 필요하면 `context.message.type`으로 확인합니다.
{% endhint %}

| 인자      | 설명                                                                                   |
| ------- | ------------------------------------------------------------------------------------ |
| 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         | 어드민 UTM 설정값. 직접 이동할 때 URL 쿼리로 붙여 주세요 |

**예시**

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

**URL 우선순위**

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

| 우선순위 | 필드                  |
| ---- | ------------------- |
| 1    | payload.pcUrl       |
| 2    | payload.mobileUrl   |
| 3    | payload.fallbackUrl |

**예시 (utm 포함)**

```js
function handleUrlOpen(payload, context) {
  var url = payload.pcUrl || payload.mobileUrl || payload.fallbackUrl;
  if (!url) {
    return { ok: false, reason: 'url_not_found' };
  }
  // 어드민 UTM 설정값(payload.utmParams)을 URL에 붙입니다
  var target = new URL(url, window.location.origin);
  var utm = payload.utmParams || {};
  Object.keys(utm).forEach(function (key) {
    var value = utm[key];
    if (value != null && String(value).trim() !== '') {
      target.searchParams.set(key, String(value));
    }
  });
  window.location.href = target.toString();
  return { ok: true, url: target.toString() };
}

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

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

`init()`에 콜백을 등록하는 대신, 원하는 이벤트가 발생할 때마다 실행할 동작을 별도로 미리 등록(구독)해둘 수도 있습니다. `on()`은 메인 스크립트가 뜬 뒤(`init()`의 `onReady` 안 또는 그 이후)에 호출해 주세요. ([**1-2 참고**](#id-1-2))

구독 핸들러도 `onUrlOpen`과 같게 동작합니다. 스크립트는 이동하지 않으므로 utm을 직접 붙여야 하고, 어드민 창 열기 방식이 새 창이면 실행되지 않습니다. `reset()`을 부르면 등록한 핸들러가 지워지므로 다시 등록해 주세요.

```js
// 3-1의 handleUrlOpen(utm 포함)을 그대로 씁니다
window.genserDiscovery.on('product.openDetail', function (payload, context) {
  var result = handleUrlOpen(payload, context);
  context.reply('product.openDetail.result', result);
});
```

{% hint style="warning" %}
**on()은 반환값이 자동 회신되지 않습니다.**

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

**구독 해제**

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

***

## **4. 로그인 연동 (선택)**

고객사 사이트에서 로그인한 방문자를 젠서에 알려주면, 지난 대화가 회원 계정에 저장되어 기기를 바꿔도 이어집니다. 연동 여부는 선택이며, 연동하지 않아도 채팅·상품검색 등 모든 기능은 그대로 동작합니다.

### 4-1. 동작 방식

젠서 디스커버리는 로그인 화면을 제공하지 않습니다. 로그인은 고객사 사이트에서 처리하고, 젠서는 「지금 이 방문자가 로그인한 사람인지」만 전달받습니다.

이름·이메일 등 계정 정보는 전달받지 않으므로 화면에 표시되지도 않습니다.

쓰는 함수는 2개입니다.

| 함수                | 언제 호출하나       |
| ----------------- | ------------- |
| `login(memberId)` | 방문자가 로그인했을 때  |
| `logout()`        | 방문자가 로그아웃했을 때 |

값을 전달할 때와 전달하지 않을 때의 차이입니다.

| 항목       | 전달하지 않을 때                        | 전달할 때                               |
| -------- | -------------------------------- | ----------------------------------- |
| 지난 대화    | 이 브라우저에서는 보입니다. 다만 기기를 바꾸면 사라집니다 | 회원 계정에 저장됩니다. 기기를 바꿔도 이어집니다         |
| 로그인 전 대화 | —                                | 넘어오지 않습니다. 비로그인 대화와 계정 대화는 따로 관리됩니다 |
| 화면 표시    | —                                | 이름은 표시되지 않습니다. 젠서는 이름을 전달받지 않습니다    |

### 4-2. memberId 규칙

`memberId`는 방문자를 구별하는 값입니다. 같은 값이면 같은 사람으로 봅니다.

{% hint style="warning" %}
**계정 정보를 그대로 넣지 말아 주세요.** 이메일·로그인 아이디·이름·전화번호를 넣으면 그 개인정보가 젠서에 저장됩니다. 권장 사항이 아니라 연동 시 반드시 지켜 주셔야 하는 조건입니다.
{% endhint %}

| 항목              | 내용                                                                                                                  |
| --------------- | ------------------------------------------------------------------------------------------------------------------- |
| 넣을 값            | UUID v4(36자) 또는 고객사 내부 관리번호. 빈 문자열이 아닌 문자열이어야 합니다. 숫자는 `String(memberNo)`처럼 문자열로 바꿔 주세요(숫자를 그대로 넘기면 `false`를 반환합니다) |
| 예               | `550e8400-e29b-41d4-a716-446655440000`                                                                              |
| 넣지 말 것          | 이메일 · 로그인 아이디 · 이름 · 전화번호 등 계정 정보                                                                                   |
| 같은 사람은 같은 값     | 회원 1명은 언제나 같은 값이어야 합니다. 값이 바뀌면 다른 사람으로 보고 지난 대화가 끊깁니다                                                               |
| 형식 검사           | 하지 않습니다. 빈 문자열이 아닌 문자열이면 그대로 받으므로 위 규칙은 고객사에서 지켜 주셔야 합니다                                                            |
| 다른 값으로 호출할 때    | 다른 사람으로 봅니다. 대화가 섞이지 않습니다                                                                                           |
| 다른 고객사와 값이 겹칠 때 | 값은 고객사 단위로 관리되어 섞이지 않습니다                                                                                            |

UUID v4는 `8-4-4-4-12` 자리 16진수를 하이픈으로 이은 36자 형식입니다(RFC 4122).

### 4-3. login(memberId)

로그인한 방문자가 보는 페이지에서 호출합니다. **메인 스크립트가 뜬 뒤에만 쓸 수 있으므로 `init()`의 `onReady` 안에서 호출해 주세요.** ([**1-2 참고**](#id-1-2))

```js
window.genserDiscovery.init({
  vendorId: 'YOUR_VENDOR_ID',
  environment: 'web',
  onReady: function () {
    var ok = window.genserDiscovery.login('550e8400-e29b-41d4-a716-446655440000');
    // ok === true  정상
    // ok === false 실패
  },
});
```

호출하면 바로 반영됩니다. 그때부터 대화가 계정에 저장되고, 로그인 전에 하던 대화는 계정으로 넘어오지 않습니다.

사이트 구성에 따라 부르는 곳이 다릅니다.

| 사이트 구성                             | `login()`을 부르는 곳                                                                                                  |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| 페이지를 이동할 때마다 화면이 새로 뜨는 사이트 (JSP 등) | 로그인 상태인 **모든 페이지**의 `onReady` 안. 로그인 상태는 다음 페이지로 이어지지 않으므로, 로그인한 페이지에서만 부르면 다음 페이지부터 비로그인으로 동작합니다. 공통 템플릿에 넣어 주세요 |
| 새로고침 없이 화면 일부만 바뀌는 사이트 (SPA)       | 앱에 처음 들어올 때 이미 로그인 상태라면 `onReady` 안에서 한 번, 그 뒤에는 로그인 처리가 끝난 시점에 한 번                                               |

{% hint style="warning" %}
**스니펫 바로 다음 줄에서 `login()`을 부르지 마세요.** 메인 스크립트가 뜨기 전이라 함수가 없어 오류가 나고, 로그인이 반영되지 않습니다.
{% endhint %}

### 4-4. logout()

회원 연결을 끊고 새 비로그인 상태로 시작합니다. 로그인 전에 하던 대화로 돌아가지 않습니다.

```js
var ok = window.genserDiscovery.logout();
// ok === true  정상
// ok === false 실패
```

로그아웃 뒤에 페이지가 새로 뜨는지에 따라 필요 여부가 다릅니다.

| 로그아웃 뒤                         | `logout()`                                                                        |
| ------------------------------ | --------------------------------------------------------------------------------- |
| 페이지가 새로 뜸 (메인·로그인 화면으로 이동 등)   | 필요 없습니다. 새 페이지에서 `login()`을 부르지 않으면 비로그인으로 시작합니다                                  |
| 페이지가 그대로 (새로고침 없이 로그아웃, SPA 등) | **반드시 호출해 주세요.** 회원 전용으로 쓰는 경우 `hideWidget()`도 함께 호출해 주세요 ([**2-6 참고**](#id-2-6)) |

{% hint style="warning" %}
**페이지가 그대로인 로그아웃에서는 `logout()`을 꼭 호출해 주세요.** 오버레이는 고객사 페이지 위에 얹혀 있어, 방문자가 사이트에서 로그아웃해도 그 사실이 젠서에 전달되지 않습니다. 호출하지 않으면 공용 PC·매장 단말에서 다음 사람이 앞사람의 지난 대화를 볼 수 있습니다.
{% endhint %}

### 4-5. 호출 시점과 화면 갱신

`login()`·`logout()`이 상태를 실제로 바꾸면 오버레이 화면을 다시 불러와 home으로 이동합니다. 방문자가 대화 중이었다면 그 화면이 home으로 바뀝니다.

같은 페이지 안에서 바뀌는 것이 없는 호출은 화면도 그대로입니다.

| 호출                           | 반환     | 화면        |
| ---------------------------- | ------ | --------- |
| 새 값으로 `login()`              | `true` | home으로 이동 |
| 같은 페이지에서 같은 값으로 `login()` 다시 | `true` | 그대로       |
| 로그인 상태에서 `logout()`          | `true` | home으로 이동 |
| 이미 로그아웃 상태에서 `logout()`      | `true` | 그대로       |

* 호출 시점은 페이지를 연 직후(`onReady`)나 로그인·로그아웃 처리 시점에 맞춰 주세요. 방문자가 대화 중일 때 호출하면 보던 화면이 home으로 바뀝니다.
* 페이지가 새로 뜨는 사이트는 페이지마다 `login()`을 부르면 그때마다 오버레이 화면을 한 번 더 불러옵니다. 오버레이가 닫혀 있는 시점이라 방문자 화면에는 보이지 않습니다.

### 4-6. 상태 구분

| 상태        | 어떤 경우               | 젠서가 받는 값 | 지난 대화가 저장되는 곳 |
| --------- | ------------------- | -------- | ------------- |
| 미연동       | 로그인 연동을 하지 않은 사이트   | 없음       | 이 브라우저        |
| 연동 · 비로그인 | 연동했지만 방문자가 로그인 안 함  | 없음       | 이 브라우저        |
| 연동 · 로그인  | `login()`으로 값을 전달받음 | 값 1개     | 회원 계정         |

앞의 두 상태는 젠서가 받는 값이 같습니다. 비로그인 방문자도 이 브라우저의 지난 대화는 볼 수 있습니다.

### 4-7. 연동 전 확인

| 확인할 것                                            | 지키지 않으면                                           | 어떻게                                                                    |
| ------------------------------------------------ | ------------------------------------------------- | ---------------------------------------------------------------------- |
| `login()`을 `onReady` 안에서 부르나                     | 메인 스크립트가 뜨기 전이라 함수가 없어 오류가 나고, 로그인이 반영되지 않습니다     | `init()`의 `onReady` 안으로 옮겨 주세요 ([**4-3 참고**](#id-4-3.-login-memberid)) |
| 페이지가 새로 뜨는 사이트에서, 로그인 상태인 모든 페이지에 `login()`을 넣었나 | 다음 페이지부터 비로그인으로 동작해 대화가 계정에 저장되지 않습니다             | 공통 템플릿에 넣어 주세요 ([**4-3 참고**](#id-4-3.-login-memberid))                 |
| 페이지가 그대로인 로그아웃에 `logout()`을 넣었나                  | 로그인 상태가 그대로 남습니다. 공용 PC에서 다음 사람이 앞사람 대화를 볼 수 있습니다 | 로그아웃 처리에 한 줄 추가해 주세요 ([**4-4 참고**](#id-4-4.-logout))                   |
| 대화 도중에 호출하지 않나                                   | 화면이 home으로 이동해 방문자가 보던 대화가 사라집니다                  | 페이지를 연 직후나 로그인·로그아웃 처리 시점에만 호출해 주세요 ([**4-5 참고**](#id-4-5))            |
| `memberId`를 문자열로 넘기나                             | 숫자를 그대로 넘기면 `false`를 반환하고 로그인이 반영되지 않습니다          | `String(memberNo)`처럼 바꿔 주세요 ([**4-2 참고**](#id-4-2.-memberid))          |
| 반환값을 확인하나                                        | 실패해도(`false`) 모른 채 넘어가 로그인이 반영되지 않습니다             | `true`/`false`를 확인해 실패 시 로그를 남겨 주세요                                    |
| 계정 정보를 그대로 넣지 않았나                                | 개인정보가 젠서에 저장됩니다. 연동 조건에 어긋나고, 형식 검사도 없어 그대로 저장됩니다 | 관리번호나 UUID로 바꿔 주세요 ([**4-2 참고**](#id-4-2.-memberid))                   |
| 회원 1명에 값 1개를 고정했나                                | 매번 다른 사람으로 보여 지난 대화가 매번 사라집니다                     | 회원마다 고정값 1개를 저장해 두고 써 주세요                                              |

***

## **5. 환경별 주의 사항**

### 5-1. SPA

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

로그인 연동을 쓰는 경우 로그인·로그아웃 처리 시점에 `login()`·`logout()`을 호출합니다. 위젯 숨김을 쓰는 경우 상태가 바뀌는 시점에 `showWidget()`·`hideWidget()`을 호출합니다. ([**2-6**](#id-2-6), [**4장 참고**](#id-4))

### 5-2. JSP

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

`showWidget()`·`hideWidget()`·`login()`으로 바꾼 상태는 다음 페이지로 이어지지 않습니다. 이 함수들도 같은 템플릿에 넣어 페이지마다 호출해 주세요. ([**7-2 참고**](#id-7-2.--jsp))

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

***

## **6. API 레퍼런스**

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

<table data-search="false"><thead><tr><th>메서드</th><th>반환</th><th>설명</th></tr></thead><tbody><tr><td>init(config)</td><td>Promise</td><td>초기화. 옵션은 <a href="#id-2-2.-init-config"><strong>2-2</strong></a> 참고</td></tr><tr><td>on(type, handler)</td><td>-</td><td>이벤트 구독. 메인 스크립트가 뜬 뒤(<code>onReady</code> 안 또는 그 이후)에 호출 (<a href="#id-3-2.-on-off"><strong>3-2 참고</strong></a>)</td></tr><tr><td>off(type, handler?)</td><td>-</td><td>이벤트 구독 해제</td></tr><tr><td>open()</td><td>-</td><td>오버레이 열기. active 상태에서만 동작하며, 열려있는 상태에서 재호출 시 동작 없음</td></tr><tr><td>close()</td><td>-</td><td>오버레이 닫기. 닫혀있는 상태에서 재호출 시 동작 없음</td></tr><tr><td>toggle()</td><td>-</td><td>오버레이 열기/닫기 토글</td></tr><tr><td>showWidget()</td><td>-</td><td>위젯 보이기. 스니펫 바로 다음부터 호출 가능(2-1의 스니펫 필요). 그 페이지에서만 유지 (<a href="#id-2-6"><strong>2-6 참고</strong></a>)</td></tr><tr><td>hideWidget()</td><td>-</td><td>위젯과 오버레이 숨기기. 숨긴 동안 <code>open()</code>·<code>toggle()</code>로도 열리지 않음. 스니펫 바로 다음부터 호출 가능(2-1의 스니펫 필요). 그 페이지에서만 유지 (<a href="#id-2-6"><strong>2-6 참고</strong></a>)</td></tr><tr><td>changeLanguage(lang)</td><td>boolean</td><td>iframe 재로드 없이 앱 언어 변경. 지원 lang 값(ko, en, ja)</td></tr><tr><td>login(memberId)</td><td>boolean</td><td>로그인 상태 전달. 정상 <code>true</code> / 실패 <code>false</code>. <code>memberId</code>는 빈 문자열이 아닌 문자열. 메인 스크립트가 뜬 뒤(<code>onReady</code> 안)에 호출. 상태가 바뀌면 화면이 갱신되어 home으로 이동 (<a href="#id-4-3.-login-memberid"><strong>4-3 참고</strong></a>)</td></tr><tr><td>logout()</td><td>boolean</td><td>회원 연결 해제 후 새 비로그인 상태로 시작. 정상 <code>true</code> / 실패 <code>false</code>. 상태가 바뀌면 화면이 갱신되어 home으로 이동 (<a href="#id-4-4.-logout"><strong>4-4 참고</strong></a>)</td></tr></tbody></table>

`init()`·`showWidget()`·`hideWidget()`은 스니펫 바로 다음부터 호출할 수 있습니다(`showWidget()`·`hideWidget()`은 2-1의 스니펫 필요). 나머지(`on`·`off`·`open`·`close`·`toggle`·`changeLanguage`·`login`·`logout`)는 메인 스크립트 로드 및 렌더링 완료 이후(`onReady` 안 또는 그 이후)에 호출해 주세요. ([**1-2 참고**](#id-1-2))\
`open()`/`close()`는 파라미터와 반환값이 없으며, 위젯 유형(기본/커스텀)과 무관하게 모두 사용할 수 있습니다.

***

## **7. 작성 예시**

코드 작성 예시를 보여줍니다. 7-1은 모든 방문자에게 위젯을 보여주는 기본 연동, 7-2는 로그인한 회원에게만 위젯을 보여주고 지난 대화를 계정에 저장하는 연동입니다.

### 7-1. 기본 연동

```html
<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 });
      };
    }
    ['showWidget', 'hideWidget'].forEach(function (m) {
      if (!w[l][m]) {
        w[l][m] = function () {
          w[l].q.push({ type: m, args: [].slice.call(arguments) });
        };
      }
    });
    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',
    onReady: function () {
      console.log('Genser Discovery Mini ready');
    },
    onError: function (err) {
      console.error('Genser Discovery Mini init failed', err);
    },
  });
</script>
```

### 7-2. 회원에게만 보이기 + 로그인 연동 (JSP 등)

페이지를 이동할 때마다 화면이 새로 뜨는 사이트 기준입니다. 공통 페이지 템플릿에 넣어 모든 페이지에서 실행되게 해 주세요.

```html
<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 });
      };
    }
    ['showWidget', 'hideWidget'].forEach(function (m) {
      if (!w[l][m]) {
        w[l][m] = function () {
          w[l].q.push({ type: m, args: [].slice.call(arguments) });
        };
      }
    });
    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');

  // 서버에서 로그인 여부와 내부 회원번호를 넣어 주세요 (아래는 예시 값)
  var isMember = true;
  var memberNo = 100245;

  // 1) 회원에게만 위젯 보이기 - 메인 스크립트가 뜨기 전에 불러도 됩니다
  if (isMember) {
    window.genserDiscovery.showWidget();
  } else {
    window.genserDiscovery.hideWidget();
  }

  // 2) 초기화 + 로그인 연동 - login()은 onReady 안에서
  window.genserDiscovery.init({
    vendorId: 'YOUR_VENDOR_ID',
    environment: 'web',
    onReady: function () {
      if (!isMember) return;
      var ok = window.genserDiscovery.login(String(memberNo)); // 숫자는 문자열로
      if (!ok) console.warn('Genser Discovery Mini login failed');
    },
  });
</script>
```

* 로그아웃 뒤에 페이지가 새로 뜨는 사이트라 `logout()`은 넣지 않았습니다. 새로고침 없이 로그아웃되는 화면이 있다면, 그 처리에 `logout()`과 `hideWidget()`을 추가해 주세요. ([**4-4 참고**](#id-4-4.-logout))
* 비로그인 방문자 페이지에 스크립트를 아예 넣지 않으려면, 서버에서 `isMember`일 때만 이 블록을 출력하고 1)은 빼도 됩니다.
* 로그인 연동 없이 회원에게만 보이게 하려면, 1)을 `window.genserDiscovery.hideWidget();`(기본 숨김)으로 바꾸고 로그인 회원 페이지에만 서버에서 `<script>window.genserDiscovery.showWidget();</script>` 한 줄을 출력해도 됩니다. 이 줄은 스니펫 뒤라면 어디에 넣어도 됩니다.

***

## **8. 유의 사항**

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

   회신하지 않으면 응답 대기 상태로 남을 수 있습니다.
5. `login()`·`logout()`은 메인 스크립트가 뜬 뒤에만 동작합니다. `init()`의 `onReady` 안이나 로그인·로그아웃 처리 시점에 호출해 주세요. 상태가 바뀌면 화면이 갱신되어 home으로 이동하고, 이미 같은 상태라면 화면은 바뀌지 않습니다. ([**4-3**](#id-4-3.-login-memberid), [**4-5 참고**](#id-4-5))
6. `memberId`에 이메일·아이디 등 계정 정보를 넣지 말아 주세요. 형식을 검사하지 않아 넣은 값이 그대로 저장됩니다. ([**4-2 참고**](#id-4-2.-memberid))
7. `showWidget()`·`hideWidget()`·`login()`으로 바꾼 상태는 그 페이지에서만 유지됩니다. 페이지가 새로 뜨는 사이트는 페이지마다 호출해 주세요. ([**1-2 참고**](#id-1-2))
8. 스니펫 앞부분의 `['showWidget', 'hideWidget'].forEach…` 줄은 지우지 마세요. 이 줄이 없으면 스니펫 바로 다음에 `showWidget()`·`hideWidget()`을 부를 때 오류가 나고 그 아래 코드가 실행되지 않습니다. ([**2-1 참고**](#id-2-1.-quick-start))
9. 위젯 숨김은 init 옵션 `hideWidget: true`가 아니라 `hideWidget()` 함수로 해 주세요. 옵션으로 숨기면 `showWidget()`으로 다시 보이지 않습니다. ([**2-6 참고**](#id-2-6))
10. 상품 이동은 스크립트가 utm을 붙여 처리합니다. `onUrlOpen`이나 `on('product.openDetail')`은 이동을 직접 처리해야 할 때만 넣고, 넣으면 `payload.utmParams`를 URL에 붙여 주세요. ([**3-1 참고**](#id-3-1.-onurlopen))
