외부 스크립트 호출 가이드

어드민에서 설정한 외부 스크립트와 앱 개발사가 추가한 외부 스크립트를 쇼핑몰에 적용할 수 있도록 개발하는 방법을 안내합니다.

외부 스크립트 설정하기

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

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

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

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

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

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

---

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

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

어드민 (관리자)에서 설정한 외부 스크립트를 호출하는 API 입니다.

GET /page/scripts ► 외부 스크립트 조회하기 쇼핑몰에서 사용 중인 외부 스크립트 리스트를 불러옵니다.

앱 개발사에서 직접 등록한 외부 스크립트를 호출하는 API 입니다.

GET /external-scripts

► 외부 스크립트 조회하기 쇼핑몰에서 사용중인 외부 스크립트 리스트를 불러옵니다.

6월 경, GET /page/scripts 가 1.1 버전으로 업그레이드됩니다.

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

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

• deviceType : 스크립트를 적용하고자 하는 디바이스 타입

• pageType : 스크립트를 적용하고자 하는 위치 (ENUM)

• pageTypeLabel : pageType을 한글로 해석한 값

• content : 스크립트 본문

deviceType 과 pageType을 참고하여, 적절한 위치에서 content가 실행될 수 있도록 개발이 진행되어야합니다. deviceType으로 올 수 있는 값들은 'PC', 'Mobile' 두 가지이며, pageType으로 올 수 있는 값들은 다음과 같습니다.

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

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

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 내부에 '<script>console.log('샵바이 CART')</script>'</span>소스가 들어갈 수 있게 해야 하며,

2. Mobile 몰 - 모든 페이지의 window.document.head 내부 맨 끝에 '<script>console.log('샵바이 COMMON\_HEAD')</script></span>' 소스가 들어갈 수 있게 해야 합니다. 단, 해당 소스를 넣기 전 글로벌 변수를 먼저 세팅해야 합니다.

---

외부 스크립트 실행 순서

외부 스크립트는 공통 상단, 페이지별, 공통 하단으로 위치를 지정할 수 있습니다. 각 위치에 삽입된 스크립트는 공통 상단 -> 페이지별 -> 공통 하단 순으로 실행되어야 합니다.

---

글로벌 변수 세팅

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

이 글로벌 변수들은 추후 외부 App용 스크립트에서도 사용될 수 있습니다. 세팅해야 하는 변수는 쇼핑몰 관리자 내 외부스크립트 변수 조회 가이드에서 확인할 수 있습니다.