메인페이지_배너영역 API
이해하기
이 문서는 쇼핑몰 메인페이지 화면 내 '배너(Banner)'영역에 대한 정책과 기능, 사용할 수 있는 API를 소개합니다.
기본 스킨(Another)의 메인화면은 배너 Banner 🅐~🅖와 섹션 Section(노란색영역)으로 구성되어있습니다.
- 배너(Banner)
- 쇼핑몰에서 로고 혹은 프로모션 이벤트를 노출하기 위한 공간이자 이미지입니다.
- 배너그룹(Banner Group)
- 각각의 배너를 유형별로 분류한 개념입니다.
- 모든 배너는 배너그룹으로 그룹핑하여 사용해야 하며, 하나의 배너그룹 안에 여러 개의 배너가 추가될 수 있습니다.
shop by pro 어드민 [ 디자인 > 디자인 설정 > 배너 관리]를 통해,
쇼핑몰 별, 스킨 별로 배너그룹에 해당하는 배너를 조회/ 등록/ 삭제/ 수정 가능합니다.
아래 소개 드릴 배너그룹의 각 위치를 자유롭게 변경하여 스킨을 제작할 수 있습니다.
단, 기본 스킨(Another)의 경우 프론트 소스 수정이 불가능하여 배너그룹의 위치변경이 불가하오니 참고바랍니다.
| 배너그룹 코드 bannerGroupCode | 배너그룹명 bannerGroupName | 배너그룹 타입 bannerGroupType |
|---|---|---|
| LOGO0001 | (ex) 상단 로고 | LOGO (로고 배너) |
| BANNER01 ~ BANNER10 | (ex) 메인상단배너 메인중간 좌측배너 메인 중간배너 1~5 스크롤 우측배너 스크롤 좌측배너 메인 하단배너 | SLIDE (움직이는 배너) |
| NORMAL (일반 배너) |
shop by pro 스킨에서는 PC / Mobile 각각 최대 11개의 배너그룹을 노출할 수 있습니다.
PC/ 모바일 각각 다른 개수로 노출 가능하며, 11개를 초과하여 노출할 수 없습니다.
각 배너그룹은 고유의 배너그룹 코드(bannerGroupCode)를 통해 구분됩니다.
위 도표에 기재된 고정된 11가지 배너코드만 사용 가능합니다.
기본 스킨 Another에서는 11개의 배너그룹의 배너그룹명(bannerGroupName)을
상단로고, 메인 상단배너, 메인 중간배너 1~5, 메인 중간 좌측배너, 메인 하단배너, 스크롤 우측배너,스크롤 좌측배너로 사용하고 있습니다.
해당 배너그룹명은 스킨 제작 시 bannerGroup.csv에 자유롭게 입력할 수 있습니다.
배너그룹은 배너그룹 노출 유형에 따라 3가지 배너그룹타입(bannerGroupType)으로 분류됩니다. ( LOGO), SLIDE, NORMAL로 제공)
LOGO0001 배너그룹은 LOGO (로고배너)로 타입이 고정되어있으며, 나머지 배너그룹은 SLIDE (움직이는 배너) 혹은 NORMAL(일반배너)로 타입을 설정 가능합니다.
- LOGO
- 메인 상단에 노출되는 로고 유형
- SLIDE
- 슬라이드 효과가 추가된 배너 유형 (멀티 배너)
- NORMAL
- 배너 이미지를 노출해주는 기본 배너 유형 (단일 배너)
해당 API로 아래 리턴 값들을 확인할 수 잇습니다
- groupCode는 앞서 설명 드린 배너그룹코드(bannerGroupCode)입니다.
참고로 bannerGroup.csv파일에서는 bannerGroupCode로 정의 하며, API 스키마에서는 groupcode로 정의하고 있습니다.
- skinCode는 각 스킨이 가지고 있는 고유의 번호입니다
skincode는 아래 2가지 시점에 자동 생성됩니다
(1) 신규 상점 생성 시 기본 스킨에 부여 (PC의 경우 SB000001, Mobile의 경우 SB000002)
(2) 어드민(관리자)에 스킨 업로드 시 부여됩니다. (SC000001, SC00002...로 생성됨)
- 사용스킨 isLiveSkin- 현재 쇼핑몰에 적용되어 있는 스킨(PC/Mobile)을 의미합니다.
작업스킨 isWorkSkin- 일종의 알파(alpha)환경으로서, 쇼핑몰에 실제로 적용하기 전에 작업한 스킨을 미리 확인할 수 있습니다.
해당 API에서 리턴값으로 조회한 skinCode 혹은 groupCode 정보를 바탕으로,
아래 소개드릴 GET /skin-banners API 에서 배너 정보를 조회하여 고객들이 보는 쇼핑몰 화면에 배너를 노출합니다.
- get전체 배너 조회
- /skin-banners
쇼핑몰의 모든 배너 정보를 조회합니다.
skinCode 혹은 groupCode 에 연동되어 있는 쇼핑몰의 배너 정보를 조회합니다.
- skinCode로 조회하는 경우에는 해당 스킨에 연동되어 있는 모든 배너 정보를 조회합니다.
groupCode (=bannerGroupCode)로 조회하는 경우에는 요청한 배너그룹 코드에 매칭되는 배너 정보만 조회합니다.
만약 groupCode로 전체 배너 리스트 정보를 조회하기 위해서는 GET /skin-banners/groups-by-skinAPI 에서 리턴 값으로 내려주는 groupCode를 모두 요청하여야만 전체 배너 리스트 정보를 조회할 수 있습니다.
배너 정보는 어드민(관리자) 에서 디자인 > 디자인설정 > 배너관리 화면에서 관리중이며, 해당 API를 통해 고객들이 보는 쇼핑몰 화면에 배너를 노출합니다.
해당 배너 리스트 데이터에 쇼핑몰 로고(Logo)가 포함되어 있습니다.
로고의 경우 화면이 바뀌어도 대부분의 스킨에서 고정된 자리에 위치해있기 때문에, 사실상 모든 화면에서 지속적으로 사용되는 API 입니다.
따라서 기본 스킨에서는 API 호출 횟수를 줄이고자 응답값을 localStorage에 캐싱 주기를 5분으로 설정하였습니다.