> For the complete documentation index, see [llms.txt](https://nsl-solution.gitbook.io/livesolution/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://nsl-solution.gitbook.io/livesolution/viewer/web/javascript.md).

# javascript 모듈

본 페이지에서는 서드파티 웹페이지 내에 javascript 모듈을 임포트하여 적용하는 방법을 가이드합니다.

### 1. 모듈 임포트 <a href="#import" id="import"></a>

페이지의 \<head>에서 쇼핑라이브 뷰어 모듈을 임포트합니다.

```html
<script type="text/javascript" src="https://im.pstatic.net/live-commerce/modules/launcher/0.20.1/index.js"></script>
```

### 2. 모듈 초기화 영역 설정  <a href="#dom" id="dom"></a>

모듈을 초기화할 DOM 엘레먼트를 설정합니다. 쇼핑라이브 뷰어는 풀페이지뷰를 전제하며, GNB, 푸터 등과 같은 별도 컴포넌트와 함께 노출하거나 다른 스타일을 적용하는 경우에는 UI의 완전성을 보장하지 않습니다.

```html
<body style="margin: 0; background-color: #000; height: 100%">
  <div id="product-root" style="height: 100%"></div>
</body>
```

### 3. 모듈 초기화 설정  <a href="#initialize" id="initialize"></a>

모듈이 초기화될 타겟 엘레먼트 하위에 모듈 초기화 설정을 위한 script를 추가합니다.

<details>

<summary>전체 예제코드</summary>

<pre class="language-html"><code class="lang-html">&#x3C;script>
  // 뷰어 초기화 코드
  const moduleConfig = {
    playMode: string, // "REPLAY", "LIVE"
    broadcastId: string, // broadcastId
    externalServiceId: 'yourservice', // 발급받은 솔루션 연동 ID
    accountConfig: { // 서드파티 회원정보 주입
      esuk: string, // 서드파티 유저 유니크키
      esun: string, // 서드파티 유저 닉네임
      loginUrl: "https://yourserivce.com/login", //서드파티 로그인 콜백 페이지
    },
    productConfig: {
      share: {
        shareUrl: 'https://yourservice.com/lives/', //공유하기시 공유할 URL
      },
    },
    events: {
      onClickReplayButton: (broadcastInfo) => alert('onClickReplayButton' + broadcastInfo), // 다시보기 버튼 클릭
      onClickBackButton: () => alert('onClickBackButton'), // 우상단 닫기 클릭
      onClickOtherLiveButton: (broadcastInfo) => alert('onClickOtherLiveButton' + broadcastInfo), // 다른 라이브 보기 버튼 클릭 시
      onClickBridgeButton: (originalLink, broadcastId) => alert('onClickBridgeButton' + originalLink + ' ' + broadcastId), // 예고페이지 보러가기 버튼 클릭 시
      onClickShareButton: () => alert('onClickShareButton'), // 공유하기 버튼 클릭
      onLinkOpen: (url) => console.log('onLinkOpen' + url), // 뷰어 내 외부 링크 클릭
      onOpenProduct: (url, name) => console.log('onOpenProduct' + url + name), // 뷰어내 상품 클릭
      onLoginRequest: () => console.log('onLoginRequest'), // 로그인 요청됨
      onLocationMove: () => console.log('onLocationMove'), // 로고 클릭 등 다른페이지 이동
      onViewerLoad: () => console.log('onViewerLoad'), // 뷰어 준비완료 상태가 되었을때 - 방송 진입
      onVideoPause: () => console.log('onVideoPause'), // 뷰어 일시정지시
      onVideoPlay: () => console.log('onVideoPlay'), // 뷰어가 재생시
      onStartBroadcast: () => console.log('onStartBroadcast'), // 방송 시작시
      onEndBroadcast: () => console.log('onEndBroadcast') // 방송 종료시
    },
    target: document.getElementById('product-root'),
  }
<strong>  lico.launcher({
</strong>    name: 'DisplayViewer',
    module: {
      resourcePath: 'https://im.pstatic.net/live-commerce/products/display-viewer/latest/real/',
      entry: 'index.js',
    },
    moduleConfig,
    onLoad: (instance) => {
      console.log('created instance', instance)
      globalThis.viewer = instance
    },
    onError: (error) => {
      console.log('error')
    },
  })
&#x3C;/script>
</code></pre>

</details>

#### 3.1 콘텐츠 정보 설정 <a href="#contents-info" id="contents-info"></a>

접근할 콘텐츠에 대한 정보를 설정합니다.&#x20;

<table><thead><tr><th width="182.33333333333331">field</th><th width="106">type</th><th>desc</th></tr></thead><tbody><tr><td>playMode</td><td>string</td><td><p>라이브, 다시보기 중 어떤 뷰어로 진입할지 설정합니다. </p><ul><li><code>"LIVE"</code> : 온에어 뷰어</li><li><code>"REPLAY"</code> : 다시보기 뷰어</li><li><code>"SHORTCLIP"</code> : 숏클립 뷰어</li></ul></td></tr><tr><td>broadcastId</td><td>string</td><td>접근할 방송 번호를 설정합니다. (온에어 혹은 다시보기인 경우)</td></tr><tr><td>shortclipId</td><td>string</td><td>접근할 숏클립 ID를 설정합니다. (playMode : shortclip인 경우)</td></tr><tr><td>externalServiceId</td><td>string</td><td>발급받은 솔루션 연동 ID를 설정합니다. 서비스별 커스텀이 적용되며, 해당 ID에 연동된 방송만 접근이 가능합니다.</td></tr></tbody></table>

```javascript
const moduleConfig = {
    playMode: string, // "REPLAY", "LIVE", "SHORTCLIP"
    broadcastId: string, // playMode : "LIVE" or "REPLAY" 인 경우만 필수
    shortclipId: string, // playMode : "SHORTCLIP"인 경우만 필수
    externalServiceId: 'yourservice' // 발급받은 솔루션 연동 ID
}
```

#### 3.2 서드파티 회원정보 연동 <a href="#member" id="member"></a>

서드파티 회원의 유니크키 및 닉네임 정보를 주입하여 뷰어를 사용할 수 있습니다. `moduleConfig` 내 `accountConfig`에 다음과 같이 설정합니다.

<table><thead><tr><th width="168.33333333333331">field</th><th width="106">type</th><th>desc</th></tr></thead><tbody><tr><td>esuk</td><td>string</td><td>서드파티 유저의 유니크키 : 없는 경우 비로그인으로 식별합니다.</td></tr><tr><td>esun</td><td>string</td><td>서드파티 유저의 닉네임(UTF-8 encode) 없는 경우 <a data-footnote-ref href="#user-content-fn-1">랜덤 닉네임</a>을 부여합니다.</td></tr><tr><td>loginUrl</td><td>string</td><td><p>뷰어 이용중 유저가 로그인이 필요한 액션을 하는 경우, 본 loginUrl 설정값으로 랜딩합니다. 이 때 다음과 같이 <code>returnUrl</code> 파라미터로 진입한 뷰어 URL을 전달합니다.</p><pre><code>https://yourservice.com/login?returnUrl={뷰어주소}
</code></pre></td></tr></tbody></table>

```javascript
const moduleConfig = {
    accountConfig: { // 서드파티 회원정보 주입
        esuk: string, // 서드파티 유저 유니크키
        esun: string, // 서드파티 유저 닉네임
        loginUrl: "https://yourserivce.com/login", //서드파티 로그인 콜백 페이지
    }
}
```

#### 3.3 모듈 커스텀 설정  <a href="#custom" id="custom"></a>

`moduleConfig` 하위의 `productConfig`에 다음과 같이 설정합니다.

<table><thead><tr><th width="168.33333333333331">field</th><th width="106">type</th><th>desc</th></tr></thead><tbody><tr><td>share.shareUrl</td><td>string</td><td><strong>뷰어>더보기>공유하기</strong> 클릭시 공유할 URL을 설정합니다.</td></tr></tbody></table>

```javascript
const moduleConfig = {
  productConfig: {
    share: {
      shareUrl: 'https://yourservice.com/lives/', //공유하기시 공유할 URL
    }
  }
}
```

#### 3.4 타겟 엘레먼트 설정 <a href="#target" id="target"></a>

`moduleConfig` 하위에 다음 예제와 같이 초기화할 DOM 엘레먼트의 id를 세팅합니다.

```javascript
const moduleConfig = {
    target: document.getElementById('product-root')
}
```

#### 3.5 모듈 런처 설정 <a href="#launcher" id="launcher"></a>

**module.resourcePath**

> <https://im.pstatic.net/live-commerce/products/display-viewer/><mark style="color:blue;">{version}</mark>/<mark style="color:blue;">{phase}</mark>/

* version : `latest` 으로 항상 최신버전 유지 혹은 패키지 버전 `0.0.0`으로 설정
* phase : 상용 서비스 환경에서는 `real` , 별도 테스트환경 분리가 필요한 경우 `beta`로 설정

**onLoad**

초기화시 동작을 설정합니다.&#x20;

**onError**&#x20;

초기화 오류시 동작을 정의합니다.

```javascript
lico.launcher({
    name: 'DisplayViewer',
    module: {
      resourcePath: 'https://im.pstatic.net/live-commerce/products/display-viewer/latest/real/',
      entry: 'index.js',
    },
    moduleConfig,
    onLoad: (instance) => {
      console.log('created instance', instance)
      globalThis.viewer = instance
    },
    onError: (error) => {
      console.log('error')
    },
  })
```

### 4. 이벤트 핸들러 추가 <a href="#event-handler" id="event-handler"></a>

뷰어의 특정 이벤트를 수신하여 서드파티 서비스의 비즈니스 로직을 구현할 수 있습니다. `moduleConfig.events` 하위에 필요에 따라 다음과 같은 핸들러를 추가합니다.

{% hint style="info" %}
핸들러는 필수설정 요소가 아니며, 핸들러를 추가하지 않는 경우 **기본 스펙으로 제공**됩니다. (기본 스펙을 희망하는 경우,핸들러 자체를 제거해주세요.
{% endhint %}

<table><thead><tr><th width="228.33333333333331">핸들러</th><th width="203">변수</th><th>설명</th></tr></thead><tbody><tr><td>onClickOtherLiveButton</td><td></td><td>온에어 뷰어에서 라이브 종료후 노출되는 <strong>"다른 라이브 보기"</strong> 버튼 클릭시 호출</td></tr><tr><td>onClickReplayButton</td><td>broadcastInfo // 방송ID</td><td>온에어 뷰어에서 라이브 종료후 노출되는 <strong>"라이브 다시보기"</strong> 버튼 클릭시 호출</td></tr><tr><td>onClickBridgeButton</td><td>originalLink // 예고URL<br>broadcastId // 방송ID</td><td>뷰어>라이브소개 내 <strong>"라이브 정보 자세히 보기"</strong> 버튼 클릭시 호출. <a data-footnote-ref href="#user-content-fn-2">사용시 설정 필요.</a></td></tr><tr><td>onClickBackButton</td><td>-</td><td>우상단 <strong>닫기 버튼 클릭</strong>시 호출. 콜백 설정 없는 경우 <code>history.back</code> 혹은 히스토리 없는 경우 창닫기로 동작합니다.</td></tr><tr><td>onClickShareButton</td><td>-</td><td>상단 더보기 > <strong>공유하기</strong> 버튼 클릭시 호출</td></tr><tr><td>onLinkOpen</td><td>url // 이동할 URL</td><td>공지사항 등 직접 세팅한 URL로 이동시 호출. 이동할 url을 전달 받아 처리할 수 있습니다.</td></tr><tr><td>onOpenProduct</td><td>url // 상품상세 URL<br>name // 상품명</td><td><strong>상품 클릭</strong>시 호출. 상품상세URL과 상품명을 전달받아 처리할 수 있습니다.  <a data-footnote-ref href="#user-content-fn-3">사용시 설정 필요.</a></td></tr><tr><td>onLoginRequest</td><td>-</td><td>로그인 요청시 호출</td></tr><tr><td>onLocationMove</td><td>-</td><td>좌상단 로고 클릭 등 외부로 이동시 호출</td></tr><tr><td>onViewerLoad</td><td>-</td><td>뷰어 진입 후 로드된 시점에 호출</td></tr><tr><td>onVideoPause</td><td>-</td><td>영상이 일시정지된 경우 호출</td></tr><tr><td>onVideoPlay</td><td>-</td><td>영상이 재생된 경우 호출</td></tr><tr><td>onStartBroadcast</td><td>-</td><td>라이브가 시작된 경우 호출 (상태 변경 : READY → ONAIR)</td></tr><tr><td>onEndBroadcast</td><td>-</td><td>라이브가 종료된 경우 호출 (상태 변경 : ONAIR → END)</td></tr></tbody></table>

```javascript
const moduleConfig = {
  events: {
      onClickReplayButton: (broadcastInfo) => alert('onClickReplayButton' + broadcastInfo), // 다시보기 버튼 클릭
      onClickBackButton: () => alert('onClickBackButton'), // 우상단 닫기 클릭
      onClickOtherLiveButton: (broadcastInfo) => alert('onClickOtherLiveButton' + broadcastInfo), // 다른 라이브 보기 버튼 클릭 시
      onClickBridgeButton: (originalLink, broadcastId) => alert('onClickBridgeButton' + originalLink + ' ' + broadcastId), // 예고페이지 보러가기 버튼 클릭 시
      onClickShareButton: () => alert('onClickShareButton'), // 공유하기 버튼 클릭
      onLinkOpen: (url) => console.log('onLinkOpen' + url), // 뷰어 내 외부 링크 클릭
      onOpenProduct: (url, name) => console.log('onOpenProduct' + url + name), // 뷰어내 상품 클릭
      onLoginRequest: () => console.log('onLoginRequest'), // 로그인 요청됨
      onLocationMove: () => console.log('onLocationMove'), // 로고 클릭 등 다른페이지 이동
      onViewerLoad: () => console.log('onViewerLoad'), // 뷰어 준비완료 상태가 되었을때 - 방송 진입
      onVideoPause: () => console.log('onVideoPause'), // 뷰어 일시정지시
      onVideoPlay: () => console.log('onVideoPlay'), // 뷰어가 재생시
      onStartBroadcast: () => console.log('onStartBroadcast'), // 방송 시작시
      onEndBroadcast: () => console.log('onEndBroadcast') // 방송 종료시
    }
}
```

### 5. 뷰어로 요청 <a href="#request" id="request"></a>

뷰어 전시 모듈의 기능들을 instance에서 이벤트로 처리할 수 있도록 제공합니다.

<table><thead><tr><th width="158">이벤트</th><th>설명</th></tr></thead><tbody><tr><td>play()</td><td>뷰어 재생 요청</td></tr><tr><td>pause()</td><td>뷰어 일시정지 요청</td></tr></tbody></table>

{% code title="예제" %}

```javascript
exampleInstance.play()
```

{% endcode %}

{% hint style="warning" %}

#### 크로스 도메인으로 적용하는 경우의 한계

웹뷰어를 크로스도메인 환경에서 iframe 형태로 적용하시는 경우, 다음과 같은 기능적 제약이 발생합니다.

* 네이버 로그인 불가 - 네이버 로그인이 필수적인 기능 미노출
* 네이버 쿠폰 다운로드 불가 (쿠폰 버튼 미노출) : 상품상세(새창)에서 다운로드 가능합니다.
* 상품 클릭시 상세 페이지는 새창으로 랜딩됩니다. (크로스도메인 아닌 경우 본창 내 모달 형태로 랜딩)
  {% endhint %}

[^1]: 형용사 + 명사 조합 (ex. 귀여운+고양이)

[^2]: 기본적으로 네이버에서 제공하는 기본 예고페이지로 랜딩되며, 자체 서드파티 예고페이지를 구현하시는 경우 사용합니다. <mark style="color:blue;">설정 변경을 위해서는 네이버 담당자에 문의하세요.</mark>

[^3]: 네이버에서 처리하는 랜딩 스펙을 제거하고 직접 랜딩 처리하시는 경우, 네이버 담당자에게 문의하세요.
