> For the complete documentation index, see [llms.txt](https://workspace-help.nhn-commerce.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://workspace-help.nhn-commerce.com/aurora-guide/api/script.md).

# 외부 스크립트 호출 가이드

### 외부 스크립트 설정하기

외부 스크립트를 추가할 수 있는 방법은 두가지 입니다.

#### 1. 관리자 > 외부 스크립트 설정에서 추가하기  

쇼핑몰에 적용할 스크립트를 설정할 수 있는 기능을 제공합니다.

```
샵바이 베이직/프로 : 설정 > 기본정책 > 외부서비스 설정
샵바이 프리미엄 : 서비스 관리 > 외부 서비스 설정
```

#### 2. 앱 개발사 > server api 로 추가하기 

쇼핑몰에서 앱 설치 시 등록된 스크립트가 실행되어야 합니다. 

***

### 쇼핑몰에 외부 스크립트 조회하기 

두가지 방법으로 등록된 외부 스크립트를 모두 조회해야 정상적으로 외부 스크립트가 실행됩니다. 

<mark style="background-color:yellow;">어드민 (관리자)</mark>에서 설정한 외부 스크립트를 호출하는 API 입니다.&#x20;

> [GET /page/scripts](https://docs.shopby.co.kr/?url.primaryName=manage/#/Page/search-external-script)\
> ► 외부 스크립트 조회하기\
> 쇼핑몰에서 사용 중인 외부 스크립트 리스트를 불러옵니다.

<mark style="background-color:yellow;">앱 개발사</mark>에서 직접 등록한 외부 스크립트를 호출하는 API 입니다.&#x20;

> [GET /external-scripts](https://docs.shopby.co.kr/?url.primaryName=workspace/#/ExternalScript/get-external-scripts)
>
> ► 외부 스크립트 조회하기\
> 쇼핑몰에서 사용중인 외부 스크립트 리스트를 불러옵니다.&#x20;

{% hint style="info" %}
6월 경, [GET /page/scripts](https://docs.shopby.co.kr/?url.primaryName=manage/#/Page/search-external-script) 가 1.1 버전으로 업그레이드됩니다.&#x20;

1.1 버전에서는 어드민 스크립트와 외부 스크립트로 등록된 모든 스크립트를 한 번에 조회할 수 있습니다.\
1.1 버전 업그레이드 시 기본 스킨에도 적용할 예정입니다.
{% endhint %}

상기 API를 호출하면, 스크립트 내용을 담은 객체들이 배열에 담긴 형태로 응답 값이 옵니다.\
해당 객체가 갖고 있는 속성들의 의미는 다음과 같습니다.&#x20;

* deviceType : 스크립트를 적용하고자 하는 디바이스 타입
* pageType : 스크립트를 적용하고자 하는 위치 (ENUM)
* pageTypeLabel : pageType을 한글로 해석한 값
* content : 스크립트 본문

<mark style="background-color:yellow;">deviceType</mark> 과 <mark style="background-color:yellow;">pageType</mark>을 참고하여, \
적절한 위치에서 content가 실행될 수 있도록 개발이 진행되어야합니다.\ <mark style="background-color:yellow;">deviceType</mark>으로 올 수 있는 값들은 'PC', 'Mobile' 두 가지이며,\ <mark style="background-color:yellow;">pageType</mark>으로 올 수 있는 값들은 다음과 같습니다.

<table><thead><tr><th width="280.3333333333333">ENUM 명</th><th width="256">적용 페이지</th><th>소스 위치</th></tr></thead><tbody><tr><td>COMMON_HEAD</td><td>모든 화면</td><td>header 태그 내부 끝</td></tr><tr><td>COMMON_FOOTER</td><td>모든 화면</td><td>body 태그 내부 끝</td></tr><tr><td>MAIN</td><td>메인 화면</td><td>body 태그 내부</td></tr><tr><td>DISPLAY_SECTION</td><td>메인분류 상품조회 화면</td><td>body 태그 내부</td></tr><tr><td>PRODUCT</td><td>상품 상세화면</td><td>body 태그 내부</td></tr><tr><td>PRODUCT_LIST</td><td>상품 리스트 화면</td><td>body 태그 내부</td></tr><tr><td>PRODUCT_SEARCH</td><td>상품 검색결과 화면</td><td>body 태그 내부</td></tr><tr><td>MEMBER_JOIN_COMPLETE</td><td>회원가입 완료 화면</td><td>body 태그 내부</td></tr><tr><td>CART</td><td>장바구니 화면</td><td>body 태그 내부</td></tr><tr><td>ORDER</td><td>주문서 작성 화면</td><td>body 태그 내부</td></tr><tr><td>ORDER_COMPLETE</td><td>주문 완료 화면</td><td>body 태그 내부</td></tr><tr><td>ORDER_DETAIL</td><td>마이페이지 내 주문 상세 화면</td><td>body 태그 내부</td></tr><tr><td>MY_PAGE</td><td>마이페이지</td><td>body 태그 내부</td></tr></tbody></table>

예를 들어 하기와 같은 응답값이 들어왔다고 가정하면,

```
1
2    scriptContents: [{
3      deviceType: 'PC',
4      pageType: 'CART',
5      pageTypeLabel: (생략),
6      content: '<script>console.log('샵바이 CART')</script>'
7    },
8    {
9      deviceType: 'Mobile',
10      pageType: 'COMMON_HEAD',
11      pageTypeLabel: (생략),
12      content: '<script>console.log('샵바이 COMMON_HEAD')</script>'
13    }, ]
14
```

1. PC 몰 - 장바구니 페이지의 window\.document.body 내부에 *'*<mark style="background-color:yellow;">\<script>console.log('샵바이 CART')\</script>'\</span></mark>소스가 들어갈 수 있게 해야 하며,
2. Mobile 몰 - 모든 페이지의 window\.document.head 내부 맨 끝에 *'*<mark style="background-color:yellow;">\<script>console.log('샵바이 COMMON\\\_HEAD')\</script>\</span></mark>*'* 소스가 들어갈 수 있게 해야 합니다.\
   단, 해당 소스를 넣기 전 **글로벌 변수**를 먼저 세팅해야 합니다.

***

### 외부 스크립트 실행 순서&#x20;

외부 스크립트는 공통 상단, 페이지별, 공통 하단으로 위치를 지정할 수 있습니다.\
각 위치에 삽입된 스크립트는 <mark style="background-color:yellow;">공통 상단 -> 페이지별 -> 공통 하단</mark> 순으로 실행되어야 합니다.&#x20;

***

### 글로벌 변수 세팅

외부 스크립트를 설정할 때 몰의 정보 (ex. 장바구니 데이터)를 이용한 스크립트도 사용할 수 있도록 쇼핑몰에 글로벌 변수들을 세팅해야 합니다.&#x20;

이 글로벌 변수들은 추후 외부 App용 스크립트에서도 사용될 수 있습니다.\
세팅해야 하는 변수는 [쇼핑몰 관리자 내 외부스크립트 변수 조회 가이드](https://admin-remote.shopby.co.kr/popup/variable-guide)에서 확인할 수 있습니다.&#x20;