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

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

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

#### 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;


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://workspace-help.nhn-commerce.com/aurora-guide/api/script.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.