# 젠서 디스커버리 소개
젠서 디스커버리(genser discovery)는 브랜드 자사몰에 AI 대화형 검색 기능을 직접 구현하는 서비스입니다. 소비자는 자사몰 안에서 자연어로 원하는 상품을 설명하거나, 마음에 드는 상품을 기준으로 유사 상품과 다른 가격대를 검색할 수 있습니다. 검색부터 구매까지 모든 과정이 자사몰 안에서 이루어집니다.
아래 순서대로 설정하면 젠서 디스커버리를 시작할 수 있습니다.
***
## **젠서 디스커버리 시작하기**
{% stepper %}
{% step %}
### **사이트 설정**
사이트 설정 페이지에서 사이트 ID를 등록하고 커스텀 도메인을 연결합니다. 커스텀 도메인 연결을 마쳐야 사이트를 공개할 수 있습니다.
자세한 방법은 [**사이트 설정**](https://help.genser.ai/settings/site)을 참고해 주세요.
{% endstep %}
{% step %}
### **상품 데이터 연동**
상품 연동 관리 페이지에서 상품 데이터를 연동합니다. 이미 운영 중인 네이버 쇼핑 EP URL이나 구글 머천트 센터 Feed URL을 등록하거나, API로 직접 전송할 수 있습니다. 한 번 연동해 두면 이후에는 스케줄에 따라 자동으로 갱신됩니다.
자세한 방법은 [**상품 연동 관리**](https://help.genser.ai/products/sync-management)를 참고해 주세요.
{% endstep %}
{% step %}
### **연동 상품 확인**
상품 현황 페이지에서 연동한 상품이 검색 가능 상품으로 반영되었는지 확인합니다.
{% endstep %}
{% step %}
### **상품 데이터 품질 확인**
상품 데이터 품질 평가 페이지에서 연동한 상품의 데이터 품질을 확인합니다. 이미지, 상품명, 카테고리, 상세 설명 네 가지 항목을 자동으로 평가하며, 보완이 필요한 상품은 항목별로 확인하고 CSV로 내려받을 수 있습니다. 데이터가 충실할수록 검색 정확도가 높아집니다.
{% endstep %}
{% step %}
### **디자인 설정**
디자인 설정 페이지에서 브랜드명, 로고, 메인 컬러, 파비콘, 링크 썸네일 등 사이트 디자인 요소를 설정합니다. 디자인 설정을 마쳐야 사이트를 공개할 수 있습니다.
자세한 방법은 [**디자인 설정**](https://help.genser.ai/design/settings)을 참고해 주세요.
{% endstep %}
{% step %}
### **검색 노출**
검색 노출을 켜기 전에 헤더의 [**검색 미리보기**](https://help.genser.ai/overview/search-preview)로 실제 검색 결과를 미리 확인해 보세요. 결과가 의도한 대로 보이면 검색 노출 설정을 On으로 변경합니다. 노출 설정은 검색 결과에 즉시 반영됩니다.
{% endstep %}
{% step %}
### **사이트 공개**
사이트 설정 페이지에서 젠서 디스커버리 공개 여부를 On으로 전환하면 모든 설정이 완료됩니다. 공개하면 방문자가 커스텀 도메인으로 사이트에 접속할 수 있습니다.
{% endstep %}
{% endstepper %}
***
## **더 알아보기**
# 젤라또 소개
젤라또(gelatto)는 소비자가 자연어 대화로 원하는 상품을 발견하고, 파트너사 자사몰로 연결되어 구매까지 이어지는 AI 커머스 서비스입니다.
아래 순서대로 설정하면 젤라또를 시작할 수 있습니다.
***
## **젤라또 시작하기**
{% stepper %}
{% step %}
### **사이트 설정**
{% hint style="info" %} **젤라또 채널** 권한이 있는 경우에만 해당합니다.
{% endhint %}
사이트 설정 페이지에서 사이트 ID를 등록합니다. 사이트 ID는 젤라또 채널 주소에 사용되며, 등록 후에는 변경할 수 없습니다.
{% endstep %}
{% step %}
### **상품 데이터 연동**
상품 연동 관리 페이지에서 상품 데이터를 연동합니다. 이미 운영 중인 네이버 쇼핑 EP URL이나 구글 머천트 센터 Feed URL을 등록하거나, API로 직접 전송할 수 있습니다. 한 번 연동해 두면 이후에는 스케줄에 따라 자동으로 갱신됩니다.
자세한 방법은 [**상품 연동 관리**](https://help.genser.ai/products/sync-management)를 참고해 주세요.
{% endstep %}
{% step %}
### **연동 상품 확인**
상품 현황 페이지에서 연동한 상품이 검색 가능 상품으로 반영되었는지 확인합니다.
{% endstep %}
{% step %}
### **상품 데이터 품질 확인**
상품 데이터 품질 평가 페이지에서 연동한 상품의 데이터 품질을 확인합니다. 이미지, 상품명, 카테고리, 상세 설명 네 가지 항목을 자동으로 평가하며, 보완이 필요한 상품은 항목별로 확인하고 CSV로 내려받을 수 있습니다. 데이터가 충실할수록 검색 정확도가 높아집니다.
{% endstep %}
{% step %}
### **디자인 설정**
{% hint style="info" %} **젤라또 채널** 권한이 있는 경우에만 해당합니다.
{% endhint %}
디자인 설정 페이지에서 브랜드명, 로고, 메인 컬러 등 채널의 디자인 요소를 설정합니다. 디자인 설정을 마쳐야 채널을 공개할 수 있습니다.
자세한 방법은 [**디자인 설정**](https://help.genser.ai/design/settings)을 참고해 주세요.
{% endstep %}
{% step %}
### **검색 노출**
검색 노출 설정을 On으로 변경하면 연동한 상품이 젤라또 검색 결과에 노출됩니다.
{% endstep %}
{% step %}
### **채널 공개**
{% hint style="info" %} **젤라또 채널** 권한이 있는 경우에만 해당합니다.
{% endhint %}
사이트 설정 페이지에서 공개 여부를 On으로 전환하면 채널이 공개되고, 방문자가 채널에 접근할 수 있습니다.
{% endstep %}
{% endstepper %}
***
## **더 알아보기**
# 어드민 로그인
어드민에 로그인하는 주소와 처음 로그인할 때 알아 둘 내용을 안내합니다.
## **1. 로그인 주소**
젠서 디스커버리 · 젠서 GEO · 젤라또 모두 아래 주소로 로그인합니다.
****
어드민에는 이용 중인 서비스의 메뉴만 표시됩니다.
## **2. 처음 로그인할 때**
* **ID**는 계정을 발급할 때 등록한 이메일 주소입니다.
* 처음에는 안내받은 임시 비밀번호로 로그인한 뒤 새 비밀번호를 설정합니다.
* 2단계 인증을 사용 중이라면 로그인할 때 인증코드도 입력합니다. 자세한 내용은 [**계정 > 2단계 인증**](https://help.genser.ai/settings/account#id-3-2)을 참고해 주세요.
* 다른 담당자는 주관리자가 [**계정 > 계정 생성**](https://help.genser.ai/settings/account#id-2-1)에서 계정을 만들면 그 이메일로 받은 임시 비밀번호로 처음 로그인합니다.
## **3. 로그인이 안 될 때**
상황
방법
비밀번호를 잊었을 때
로그인 화면의 [비밀번호 찾기]에서 등록된 이메일로 임시 비밀번호를 받을 수 있습니다.
접속 허용 IP가 설정되어 있을 때
등록된 IP에서만 로그인할 수 있습니다. 주관리자는 다른 네트워크에서도 이메일 인증으로 로그인할 수 있습니다. 자세한 내용은 계정 > 접속 허용 IP를 참고해 주세요.
# 검색 미리보기
{% hint style="info" %}
**젠서 디스커버리 전용 기능**입니다.
{% endhint %}
검색 미리보기는 사이트를 공개하거나 검색 노출을 켜기 전에, 실제 검색 결과를 미리 확인하는 기능입니다. 검색 노출이 꺼져 있어도 미리보기에서는 결과를 확인할 수 있으며, 미리보기 화면은 고객이 실제로 보게 될 화면과 동일하게 동작합니다.
***
## **1. 미리보기 열기**
헤더(화면 상단) 우측의 **\[검색 미리보기]** 버튼을 클릭하면 새 창에서 미리보기가 열립니다. 어느 페이지에 있든 헤더에서 바로 열 수 있습니다.
미리보기를 사용하려면 **사이트 ID 등록이 완료**되어 있어야 합니다. 사이트 ID는 [**사이트 설정**](https://help.genser.ai/settings/site)에서 등록할 수 있습니다.
디자인 설정을 완료하지 않은 상태에서도 미리보기를 열 수 있습니다. 이 경우 화면은 기본 디자인으로 표시되며, 디자인 설정을 완료하면 설정한 값이 그대로 반영됩니다.
***
## **2. 피드백**
미리보기 화면에서 검색 결과에 대해 좋아요·싫어요 피드백을 남길 수 있습니다. 남겨 주신 의견은 검색 품질을 개선하는 데 활용됩니다.
피드백
설명
좋아요
만족스러웠던 점에 대한 의견을 남길 수 있습니다.
싫어요
불만족 사유를 선택하고, 구체적인 의견을 함께 남길 수 있습니다.
{% hint style="info" %}
미리보기에서의 검색·클릭 등 활동은 실제 유저 통계와 분리되어 집계됩니다.
{% endhint %}
***
## **자주 묻는 질문**
Q. 헤더에 검색 미리보기 버튼이 보이지 않습니다.
검색 미리보기는 젠서 디스커버리 전용 기능입니다. 젤라또 채널만 사용 중인 경우에는 버튼이 표시되지 않습니다.
Q. 버튼을 클릭하니 사이트 ID를 등록하라는 창이 나타납니다.
검색 미리보기는 사이트 ID를 등록해야 사용할 수 있습니다. [**사이트 설정**](https://help.genser.ai/settings/site)에서 먼저 등록해 주세요.
Q. 미리보기에서는 보이는 상품이 실제 검색에서는 나오지 않습니다.
사이트의 검색 노출 설정이 꺼져 있을 수 있습니다. 검색 노출 설정이 꺼져 있으면 실제 검색에는 상품이 표시되지 않습니다. 미리보기는 이 설정과 관계없이 표시됩니다. [**상품 현황**](https://help.genser.ai/products/overview)에서 검색 노출 설정을 확인해 주세요.
Q. 미리보기 화면이 기본 디자인으로 표시됩니다.
디자인 설정을 완료하지 않은 상태에서는 기본 디자인으로 표시됩니다. [**디자인 설정**](https://help.genser.ai/design/settings)을 완료하면 설정한 값이 미리보기에 반영됩니다.
# GEO 리포트
{% hint style="info" %}
**젠서 GEO 전용 기능**입니다.
{% endhint %}
GEO 리포트는 생성형 AI 답변에 브랜드가 얼마나 언급·추천되고 자사 사이트가 얼마나 인용되는지 측정한 리포트를 확인하고 다운로드하는 페이지입니다.
리포트는 담당자와 협의해 정한 질문과 측정 주기에 따라 측정 기간마다 생성됩니다. 변경이 필요한 경우 담당자에게 문의해 주세요.
# 상품 현황
수집된 상품과 검색 상품의 현황을 확인하는 페이지입니다.
{% hint style="info" %}
**\[검색 반영 프로세스]**
연동된 상품이 검색 결과에 바로 반영되지는 않습니다. 데이터 연동이 완료 후 매 정시에 시작되는 검색 반영 작업을 거쳐 '검색 가능 상품 수'에 최종 반영됩니다.
(예: 11:30에 연동된 상품은 12:00부터 순차적으로 검색에 반영되기 시작하며, 처리 완료까지 다소 시간이 소요될 수 있습니다.)
{% endhint %}
***
## **1. 상품 연동 현황**
연동된 상품 데이터의 수집 현황입니다.
지표
설명
전체 상품 수
현재까지 수집된 전체 상품 수입니다.
신규 상품 수
오늘(00:00 기준) 새로 등록된 상품 수입니다.
업데이트 상품 수
오늘(00:00 기준) 상품명, 재고, 가격 등 실제로 값이 변경된 상품 수입니다. 데이터 변동이 없는 상품은 포함되지 않습니다.
***
## **2. 검색 상품 현황**
실제 검색 결과에 노출 가능한 상품의 현황입니다.
{% hint style="info" %}
지표의 기준 시간은 직전 정시로 표시됩니다. (예: 22:21 진입 시 22:00 기준으로 표기)
{% endhint %}
지표
설명
검색 가능 상품 수
검색 결과에 노출 중인 상품 수입니다. 매 정시에 시작되는 검색 반영 작업이 완료된 후 갱신됩니다. 검색 노출 설정이 중지(OFF)인 동안에는 검색 대기 상품 수로 표시됩니다. 설정을 켜면 검색 결과에 노출되는 상품 수입니다.
검색 제외 상품 수
판매 대기, 판매 종료, 품절, 이미지 접근 불가 등의 사유로 검색에서 제외된 상품 수입니다.
### **2-1. 검색 노출 설정**
모든 상품의 검색 결과 노출 여부를 일괄로 제어하는 토글입니다. 변경 사항은 검색 결과에 즉시 반영됩니다. 기본값은 중지(OFF) 상태이며, 상품 수와 관계없이 언제든 변경할 수 있습니다.
동작
설명
노출 시작 (On)
검색 가능 상품이 검색 결과에 노출됩니다.
노출 중지 (Off)
모든 상품이 검색 결과에서 숨김 처리됩니다.
{% hint style="info" %}
**\[노출 중지(OFF) 시의 동작]**
* 검색 노출을 중지해도 상품 연동(데이터 수집)은 계속 진행되며, 이미 연동된 상품 데이터는 삭제되지 않습니다.
* 검색 노출 설정은 상품의 검색 노출만 제어합니다. 연동 자체를 중지하려면 [**상품 연동 관리**](/products/sync-management)에서 해당 연동 방식의 토글을 비활성화해 주세요.
{% endhint %}
***
## **3. 오늘 연동 내역**
당일 실행된 연동 내역을 연동 방식별로 확인할 수 있습니다. 데이터는 매일 00:00에 자동으로 초기화됩니다.
### **3-1. 네이버 EP**
컬럼
설명
실행 시간
연동이 실행된 시간입니다.
데이터 범위
수집된 데이터의 범위입니다. ('전체 EP' 또는 '요약 EP'로 구분)
SKU 연동 수
해당 연동에서 처리된 상품 수입니다.
### **3-2. GMC Feed**
컬럼
설명
실행 시간
연동이 실행된 시간입니다.
SKU 연동 수
해당 연동에서 처리된 상품 수입니다.
### **3-3. API**
컬럼
설명
시간대
데이터가 처리된 시간을 1시간 단위로 묶어 표시합니다.
SKU 연동 수
해당 시간대에 처리된 상품 수입니다. (SKU 연동 수가 0건인 시간대는 표시되지 않습니다.)
***
## **자주 묻는 질문**
Q. '전체 상품 수'와 '검색 가능 상품 수'가 다른 이유는 무엇인가요?
연동된 상품이 검색 결과에 반영되려면 매 정시에 시작되는 검색 반영 작업을 거쳐야 합니다. 최근 연동된 상품이 아직 정시 반영 작업을 거치지 않았다면 두 수치에 일시적인 차이가 발생할 수 있습니다.
Q. 검색 노출 설정을 Off했는데 검색 결과에 상품이 계속 노출됩니다.
검색 노출 설정은 변경하면 검색 결과에 즉시 반영되지만, 이미 진행 중인 대화에는 변경 전에 불러온 결과가 남아 있을 수 있습니다.
Q. 상품을 새로 연동했는데 검색 결과에 바로 보이지 않습니다.
신규·업데이트 상품은 검색에 1시간 주기로 순차 반영됩니다. 연동 직후에는 미리보기에서 확인되지 않을 수 있으며, 반영까지 다소 시간이 소요될 수 있습니다.
Q. 오늘 연동 내역에서 특정 연동 방식(예: 네이버 EP) 탭이 선택되지 않습니다.
해당 연동 방식의 최초 설정이 완료되지 않은 경우 탭이 비활성 상태로 표시됩니다. [**상품 연동 관리**](/products/sync-management)에서 사용할 연동 방식의 설정을 먼저 완료해 주세요.
# 상품 연동 관리
상품 데이터를 연동하는 방식을 설정하고 관리하는 페이지입니다.
## **1. 연동 방식 한눈에 보기**
연동 방식
설명
수집 방식
적합한 경우
네이버 EP
네이버 쇼핑에 사용 중인 EP URL을 통해 상품을 연동합니다.
스케줄 기반 자동 수집
네이버 쇼핑 파트너 센터 EP를 이미 운영 중인 경우
GMC Feed
구글·유튜브 쇼핑에 사용 중인 Feed URL을 통해 상품을 연동합니다.
스케줄 기반 자동 수집
구글 머천트 센터 피드를 이미 운영 중인 경우
API
젤라또·네이버 커머스·구글 머천트 API를 통해 상품 데이터를 실시간으로 연동합니다.
실시간 전송
상품 변경 시 즉시 반영이 필요하거나, 자체 시스템에서 직접 데이터를 전송하는 경우
{% hint style="info" %}
네이버 EP, GMC Feed, API 세 가지 방식을 동시에 사용할 수 있습니다. 동일한 상품이 여러 방식으로 연동되더라도 상품 코드를 기준으로 필드 단위로 자동 병합됩니다.
{% endhint %}
***
## **2. 네이버 EP**
네이버 쇼핑에 사용 중인 EP URL을 등록하면, 설정한 스케줄에 따라 상품 데이터를 자동으로 수집합니다.
{% hint style="info" %}
네이버 EP는 한국 리전에서만 사용할 수 있습니다. 일본 리전에서는 표시되지 않습니다.
{% endhint %}
### **2-1. 스케줄 연동**
#### **Step 1. URL 등록 및 스케줄 설정**
버튼을 클릭하여 EP URL과 연동 스케줄을 설정합니다.
* **전체 EP:** '전체 상품 데이터'를 수집하는 기본 EP입니다.
* **요약 EP:** 가격, 재고 등 '자주 변경되는 핵심 정보'를 빠르게 업데이트하기 위한 보조 EP입니다. 필요에 따라 우측의 토글을 켜서 사용할 수 있습니다.
항목
설명
URL*
[전체 EP / 요약 EP]
네이버 쇼핑에 사용 중인 전체 EP와 요약 EP 각각의 URL을 입력합니다.
http:// 또는 https://로 시작하는 완전한 형태여야 합니다.
외부에서 접근 가능한 공개 URL만 등록할 수 있습니다.
연동 스케줄
[전체 EP]
매일 선택한 시간에 1회 연동합니다.
00시~23시 중 선택할 수 있으며, 기본값은 01시입니다.
[요약 EP]
매일 08:00 ~ 22:00 사이, 선택한 간격으로 반복 연동합니다.
30분 / 1시간 / 2시간 중 선택할 수 있으며, 기본값은 1시간입니다.
{% hint style="info" %}
EP URL을 어디서 확인해야 하는지 모르거나, 아직 EP 파일이 준비되지 않은 경우 [**네이버 EP URL 설정 가이드**](/reference/naver-ep-url)를 참고해 주세요.
{% endhint %}
{% hint style="info" %}
**\[전체 EP 연동 스케줄 권장 사항]**
전체 상품을 한 번에 수집하므로 완료까지 다소 시간이 소요될 수 있습니다. 특히 연동 요청이 집중되는 시간대에는 지연이 발생할 수 있으니, 안정적인 수집을 위해 트래픽이 적은 **새벽 시간대**에 진행하시는 것을 권장합니다.
{% endhint %}
{% hint style="warning" %}
**\[스케줄 변경 시 적용 시점]**
* **전체 EP:** 오늘 설정된 연동이 이미 완료된 경우, 변경된 스케줄은 **다음 날 연동 일정**부터 적용됩니다.
* **요약 EP:** 스케줄 변경 시, 변경된 주기의 다음 **정각 또는 30분 시점**부터 반영됩니다. 단, 연동 동작 시간(08:00\~22:00) 외의 시간에 변경한 경우 설정은 즉시 저장되지만, **실제 실행은 다음 날 08:00부터 시작**됩니다.
{% endhint %}
#### **Step 2. 저장 및 활성화**
**\[저장] 버튼**을 클릭하여 설정을 완료합니다. 우측 상단의 **연동 토글을 ON(활성화)** 상태로 유지해야 설정한 스케줄에 따라 상품 데이터가 정상적으로 수집됩니다.
설정이 완료되면 네이버 EP 연동 정보에서 **다음 연동 예정 시각**을 확인할 수 있습니다.
{% hint style="info" %}
우측 상단의 토글을 끄면(OFF) 연동이 일시 중지됩니다. 단, 비활성화하더라도 **이미 수집된 상품 데이터는 삭제되지 않으며 검색 결과에도 그대로 노출**됩니다. URL, 스케줄 등 기존 설정 정보도 유지되므로 필요 시 언제든 다시 켤 수 있습니다.
{% endhint %}
### **2-2. 즉시 연동**
설정된 스케줄과 별개로, 데이터 최신화가 급히 필요할 때 상품을 바로 수집할 수 있는 기능입니다. 버튼을 클릭하여 실행합니다.
당일 즉시 연동 잔여 횟수는 연동 정보에서 확인할 수 있으며, 제공 횟수는 **매일 00시(자정)를 기준으로 자동 초기화**됩니다.
구분
1일 제공 횟수
전체 EP
3회
요약 EP
12회
***
## **3. GMC Feed**
구글·유튜브 쇼핑에 사용 중인 Feed URL을 등록하면, 설정한 스케줄에 따라 상품 데이터를 자동으로 수집합니다.
### **3-1. 스케줄 연동**
#### **Step 1. URL 등록 및 스케줄 설정**
버튼을 클릭하여 Feed URL과 연동 스케줄을 설정합니다.
항목
설명
URL*
구글·유튜브 쇼핑에 사용 중인 Feed URL을 입력합니다.
http:// 또는 https://로 시작하는 완전한 형태여야 합니다.
외부에서 접근 가능한 공개 URL만 등록할 수 있습니다.
지원 형식: .txt,.tsv, .xml (최대 4GB)
연동 스케줄
매일 선택한 시간에 1회 연동합니다.
00시~23시 중 선택할 수 있으며, 기본값은 01시입니다.
{% hint style="info" %}
Feed URL을 어디서 확인해야 하는지 모르거나, 아직 피드 파일이 준비되지 않은 경우 [**GMC Feed URL 설정 가이드**](/reference/gmc-feed-url)를 참고해 주세요.
{% endhint %}
{% hint style="info" %}
**\[스케줄 권장 사항]**
전체 상품을 한 번에 수집하므로 완료까지 다소 시간이 소요될 수 있습니다. 특히 연동 요청이 집중되는 시간대에는 지연이 발생할 수 있으니, 안정적인 수집을 위해 트래픽이 적은 **새벽 시간대**에 진행하시는 것을 권장합니다.
{% endhint %}
{% hint style="warning" %}
**\[스케줄 변경 시 적용 시점]**
오늘 설정된 연동이 이미 완료된 경우, 변경된 스케줄은 **다음 날 연동 일정**부터 적용됩니다.
{% endhint %}
#### **Step 2. 저장 및 활성화**
**\[저장] 버튼**을 클릭하여 설정을 완료합니다. 우측 상단의 **연동 토글을 ON(활성화)** 상태로 유지해야 설정한 스케줄에 따라 상품 데이터가 정상적으로 수집됩니다.
설정이 완료되면 GMC Feed 연동 정보에서 **다음 연동 예정 시각**을 확인할 수 있습니다.
{% hint style="info" %}
우측 상단의 토글을 끄면(OFF) 연동이 일시 중지됩니다. 단, 비활성화하더라도 **이미 수집된 상품 데이터는 삭제되지 않으며 검색 결과에도 그대로 노출**됩니다. URL, 스케줄 등 기존 설정 정보도 유지되므로 필요 시 언제든 다시 켤 수 있습니다.
{% endhint %}
### **3-2. 즉시 연동**
설정된 스케줄과 별개로, 데이터 최신화가 급히 필요할 때 상품을 바로 수집할 수 있는 기능입니다. 버튼을 클릭하여 실행합니다.
* **1일 제공 횟수:** 3회
* 당일 즉시 연동 잔여 횟수는 연동 정보에서 확인할 수 있으며, 제공 횟수는 **매일 00시(자정)를 기준으로 자동 초기화**됩니다.
***
## **4. API**
젤라또·네이버 커머스·구글 머천트 API를 통해 상품 데이터를 실시간으로 전송하는 방식입니다. 네이버 EP나 GMC Feed와 달리 별도의 스케줄이나 토글 설정 없이, **API 호출 시점에 즉시 데이터가 연동**됩니다.
### **4-1. 사전 준비**
#### **Step 1. API 키 발급**
최초 진입 시에는 API 키가 발급되지 않은 상태입니다. 버튼을 클릭하여 [**API 키 발급**](/settings/api-key) 페이지로 이동한 뒤, 새로운 API 키를 발급 받을 수 있습니다.
키 발급이 완료되면 카드 화면에 마스킹된 API 키와 버튼이 표시됩니다.
#### **Step 2. API 키 확인**
기능
설명
보기
클릭 시 마스킹 처리된 API 키 전체를 확인합니다.
복사
API 키를 클립보드에 복사합니다.
{% hint style="info" %}
발급된 API 키 하나로 젤라또, 네이버 커머스, GMC 등 **모든 API 연동에 공통으로 사용**할 수 있습니다.
{% endhint %}
{% hint style="warning" %}
API 키가 외부에 노출될 경우 무단으로 데이터가 전송되거나 훼손될 위험이 있습니다. 키가 유출되지 않도록 보안 관리에 주의해 주세요.
{% endhint %}
### **4-2. API 연동 가이드**
버튼을 클릭하면 상세 안내 페이지로 이동합니다. 해당 [**API 연동 가이드**](/developers/product-collection)에서 사용하려는 API 유형(젤라또 API, 네이버 커머스 API, 구글 머천트 API)별 **엔드포인트와 요청 규격** 등을 확인할 수 있습니다.
***
## **자주 묻는 질문**
Q. EP URL이나 Feed URL을 어디서 확인하나요?
네이버 EP URL은 네이버 쇼핑 파트너센터에서, GMC Feed URL은 Google Merchant Center에서 확인할 수 있습니다.
Q. 피드 파일(EP, GMC) 내용이 업데이트될 때마다 URL을 다시 등록해야 하나요?
**아닙니다. URL은 최초 한 번만 등록하시면 됩니다.**\
이후에는 기존과 동일한 URL 경로에 파일 내용만 갱신해 두시면, 설정하신 스케줄에 맞춰 시스템이 최신 데이터를 자동으로 수집합니다.
Q. 네이버 EP, GMC 피드, API 등 여러 연동 방식을 동시에 사용하면 상품이 중복 생성되나요?
**중복 생성되지 않습니다.**\
모든 연동 방식은 '상품 고유 식별 코드'를 기준으로 식별합니다. 동일한 상품 코드로 여러 방식의 데이터가 들어오더라도, 시스템에서 자동으로 항목(필드) 단위로 최신 정보를 안전하게 병합하여 업데이트합니다.
Q. 연동 토글을 비활성화(OFF)하면 이미 수집된 상품은 어떻게 되나요?
**기존 상품 데이터는 삭제되지 않으며, 검색 결과에도 정상적으로 노출됩니다.**\
토글 비활성화는 '새로운 데이터의 자동 수집'만 일시 중지하는 기능입니다. 만약 연동된 상품 전체를 쇼핑몰 검색 결과에서 즉시 숨기고 싶으시다면, 연동 비활성화가 아닌 상품 현황 페이지의 '검색 노출 설정' 토글을 OFF로 변경해 주세요.
# 상품 데이터 품질 평가
연동된 상품 데이터의 품질을 자동으로 점검하고, 보완이 필요한 상품을 확인하는 페이지입니다.
{% hint style="info" %}
**\[데이터 평가 기준 시점]**
연동된 상품 데이터를 1시간 주기(매시 정각 기준)로 자동 평가합니다. 기준 시각은 품질 평가 결과 우측 상단에 표시됩니다.
{% endhint %}
***
## **1. 품질 평가 결과**
연동한 상품의 데이터 품질을 요약하여 보여줍니다.
### **1-1. 데이터 완성도**
전체 상품 중 4개 평가 항목 모두에서 결함이 없는 상품의 비율입니다. 수치가 높을수록 검색 정확도가 향상되며, 미흡할 경우 검색 노출이 제한되거나 검색 결과 품질이 저하될 수 있습니다.
### **1-2. 기준 충족 상품 수 / 보완 필요 상품 수**
지표
설명
기준 충족 상품 수
4개 평가 항목(이미지 URL, 상품명, 카테고리, 상세 설명) 모두에서 기준을 충족한 상품 수입니다.
보완 필요 상품 수
1개 이상의 항목에서 보완이 필요한 상품 수입니다. 하나의 상품이 여러 항목에 해당할 수 있으며, 중복 없이 집계됩니다.
### **1-3. 평가 항목별 완성도**
각 평가 항목별로 기준을 충족한 상품의 비율을 막대 그래프로 표시합니다. 항목별 상세 기준은 페이지 우측 상단의 **\[평가 항목 안내]** 버튼을 클릭하여 확인할 수 있습니다.
***
## **2. 평가 항목 안내**
4개 평가 항목별 충족 기준은 다음과 같습니다.
평가 항목
충족 기준
이미지 URL
정상적으로 접근 및 노출이 가능한 URL / 이미지 사이즈 200×200px 이상
상품명
텍스트 길이 5자 이상 ~ 200자 이하 / HTML 태그 및 깨진 문자(특수기호 오류 등) 미포함
카테고리
대분류 외 세부 카테고리 매핑
상세 설명
이미지가 아닌 실제 텍스트 길이 30자 이상
{% hint style="warning" %}
이미지를 불러올 수 없거나 가로와 세로가 모두 10px 미만인 상품은 **검색 결과에서 제외**됩니다. 해당 상품은 검색 결과에 노출되지 않으므로 우선적으로 이미지를 교체해 주세요.
{% endhint %}
***
## **3. 보완 필요 상품**
평가 항목별로 보완이 필요한 상품을 확인하고 다운로드할 수 있습니다.
### **3-1. 항목별 보완 필요 상품 수**
각 평가 항목에 해당하는 보완 필요 상품 수를 표시합니다. 하나의 상품이 여러 항목에 해당할 수 있습니다.
항목
보완 필요 기준
이미지 URL
이미지를 불러올 수 없거나 가로 또는 세로가 200px 미만인 상품입니다. 기준에 맞는 이미지로 교체해 주세요.
상품명
상품명이 5자 미만 또는 200자 초과이거나, HTML 태그·깨진 문자가 포함된 상품입니다. 상품명을 수정해 주세요.
카테고리
대분류까지만 매핑된 상품입니다. 카테고리를 더 세분화해 주세요.
상세 설명
텍스트가 30자 미만인 상품입니다. 상세 설명을 보완해 주세요. (이미지 내 텍스트는 인식되지 않음)
### **3-2. 보완 필요 상품 리스트**
항목 탭을 선택하면 해당 항목의 보완 필요 상품 목록을 확인할 수 있습니다.
탭
표시 컬럼
이미지 URL
SKU, 상품명, 이미지 URL, 이미지 사이즈
상품명
SKU, 상품명
카테고리
SKU, 상품명, 카테고리 경로
상세 설명
SKU, 상품명, 상세 설명
### **3-3. 다운로드**
현재 선택된 탭의 보완 필요 상품 목록을 CSV 파일로 다운로드할 수 있습니다.
***
## **자주 묻는 질문**
Q. 데이터 완성도 수치는 어떻게 산출되나요?
(전체 보유 상품 수 − 보완 필요 상품 수) ÷ 전체 보유 상품 수 × 100으로 산출됩니다. 소수점 첫째 자리까지 표시되며, 둘째 자리 이하는 버림 처리됩니다.
Q. 보완 필요 상품 수와 항목별 상품 수의 합계가 다릅니다.
보완 필요 상품 수는 1개 이상의 항목에서 결함이 있는 상품을 **중복 없이 집계한 수치**입니다. 반면, 항목별 상품 수는 각 항목에 해당하는 상품을 개별적으로 집계하므로 하나의 상품이 여러 항목에 중복 포함될 수 있습니다.
Q. 평가 결과가 실시간으로 반영되나요?
평가는 매시 정각에 실행됩니다. 상품 데이터를 수정한 직후에는 반영되지 않으며, 다음 정시 평가 이후 결과가 갱신됩니다.
# CS 지식 관리
{% hint style="info" %}
**젠서 디스커버리 전용 기능**입니다.
{% endhint %}
CS 지식 관리는 에이전트가 고객 문의에 답변할 때 쓸 지식을 등록·관리하는 페이지입니다. 문서·웹페이지·링크로 등록하며, 에이전트는 등록한 지식을 바탕으로 답변합니다.
## **1. 지식 등록 방식**
지식은 세 가지 방식으로 등록하며, 각각 **문서**·**웹페이지**·**링크** 탭에서 관리합니다.
구분
무엇을 등록하나
답변에 어떻게 쓰이나
문서
파일을 등록
문서 내용을 답변에 반영합니다.
웹페이지
페이지 주소(URL)를 등록
페이지 내용을 가져와 답변에 반영합니다.
링크
페이지 주소(URL)와 이름·설명을 등록
관련 질문에 링크를 안내합니다. 페이지 내용은 가져오지 않습니다.
{% hint style="warning" %}
등록 한도(문서 300개 · 웹페이지 1,000개 · 링크 300개)는 상한일 뿐 권장값이 아닙니다. 답변에 반영되는 자료가 많을수록 에이전트가 골라야 할 후보가 늘어 답변 정확도가 떨어지고 느려질 수 있습니다. 한도 안에서도 답변에 **꼭 필요한 지식만** 등록해 주세요.
{% endhint %}
***
## **2. 문서**
### **2-1. 등록**
문서를 등록하면 내용을 처리(학습)한 뒤 답변에 반영됩니다. 처리에는 보통 수 분, 길어도 10분 안팎이 걸립니다.
항목
정책
파일 형식
TXT, Markdown, PDF, HTML, DOCX, PPTX, XLSX, XLSM
파일 용량
PDF는 파일당 최대 160MB, 그 외 형식은 10MB
파일 개수
한 번에 50개, 전체 300개까지
이미지
PDF만 이미지까지 학습합니다. 다른 형식은 이미지를 학습하지 않습니다.
{% hint style="info" %}
같은 파일명·확장자의 파일을 다시 등록하면 기존 문서를 교체할지 선택할 수 있습니다. (교체하면 중복으로 쌓이지 않습니다.)
{% endhint %}
### **2-2. 상태**
상태
의미
학습 중
내용을 처리하는 중입니다. 아직 답변에 반영되지 않습니다.
답변 반영
처리가 끝나 답변에 반영되고 있습니다.
답변 제외
답변에 반영하지 않습니다.
제외 중
답변에서 제외하는 처리 중입니다. 잠시 후 '답변 제외'로 바뀝니다.
반영 실패
처리에 실패했습니다. 다시 시도할 수 있습니다.
### **2-3. 답변 반영 관리**
문서별로 목록의 **답변 반영 스위치**나 **행 끝 관리 도구**에서 켜고 끌 수 있습니다.
* **답변에서 제외**: 답변에 반영하지 않습니다. 제외 처리에는 잠시 시간이 걸립니다.
* **답변에 반영**: 제외했던 문서를 다시 반영합니다. 다시 처리(학습)를 거칩니다.
* **다시 시도**: 반영에 실패한 문서를 다시 처리합니다.
### **2-4. 미리보기·다운로드·삭제**
* **미리보기**: 등록한 문서를 어드민에서 미리볼 수 있습니다. DOCX·PPTX·XLSX·XLSM 형식과 5MB가 넘는 텍스트 계열 파일(TXT·MD·HTML)은 미리볼 수 없으니 다운로드해서 확인해 주세요.
* **다운로드**: 등록한 파일을 내려받을 수 있습니다.
* **삭제**: 삭제하면 목록에서 바로 사라집니다. 답변에 쓰이던 내용이 지워지기까지 수 분이 걸릴 수 있으니, [**검색 미리보기**](https://help.genser.ai/overview/search-preview)에서 확인해 주세요. 삭제한 정보는 되돌릴 수 없습니다.
***
## **3. 웹페이지**
### **3-1. 등록**
#### **입력 항목**
항목
설명
URL
내용을 가져올 페이지 주소입니다. 한 줄에 하나씩 입력하며, URL마다 웹페이지가 하나씩 등록됩니다.
유효기간
한시적으로 운영하는 페이지의 답변 참조 기간입니다. 한 번에 등록한 URL에는 같은 기간이 적용됩니다. (선택)
#### **등록 정책**
항목
정책
URL 개수
한 번에 300개, 전체 1,000개까지
이름
수집한 페이지에서 자동으로 가져옵니다. 처음 수집할 때 한 번 가져오며, 학습이 끝난 뒤 수정할 수 있습니다.
등록할 수 없는 URL
http:// 또는 https://로 시작하지 않는 URL, 이미 등록된 URL, 한도를 넘는 URL이 하나라도 있으면 아무것도 등록되지 않습니다.
#### **유효기간**
* 설정하지 않으면 상시 답변에 반영됩니다.
* 설정하면 지정한 기간에만 답변에 반영되고, 종료일이 지나면 자동으로 답변에서 제외됩니다.
* 이벤트·시즌처럼 한시적으로 운영하는 페이지에 사용합니다.
* 기간이 지난 뒤 다시 반영하려면 **유효기간을 수정**해 주세요. 답변 반영 스위치로는 되돌릴 수 없습니다.
#### **수집 범위**
등록한 URL에서 **공개된 텍스트**를 가져옵니다. **화면에 보이는 내용과 실제로 가져온 내용이 다를 수 있으므로, 등록 후 미리보기에서 확인해 주세요.**
가져오는 범위는 **입력한 URL의 페이지까지**입니다. 그 아래 하위 페이지는 가져오지 않으므로, 필요한 페이지는 각각 등록해 주세요.
구분
해당하는 경우
가져오지 못하는 페이지
로그인이 필요한 페이지
사람 확인(캡차) 절차가 있는 페이지
없는 페이지(주소가 잘못됐거나 삭제된 페이지)
내용 없이 빈 화면만 나오는 페이지
가져오지 못하는 내용
이미지로 만든 내용(상세 이미지, 사이즈표 등)
스크롤하거나 더보기를 눌러야 불러오는 내용(무한 스크롤 등)
다른 서비스에서 불러와 넣은 영역(지도, 동영상 등)
페이지에 첨부된 파일의 내용
가져오지 못하는 페이지는 '반영 실패'로 표시됩니다. 가져오지 못하는 내용이 있는 페이지는 그 내용만 빠진 채 답변에 반영됩니다.
{% hint style="info" %}
이미지는 가져오지 않습니다. 필요한 내용이 빠져 있다면 해당 내용을 PDF로 만들어 **문서** 탭에 등록하거나, **링크** 탭에 링크로 등록해 주세요. PDF는 이미지도 학습합니다.
가져온 내용은 **수집한 시점으로 고정**됩니다. 페이지 내용이 바뀌면 **다시 수집**으로 최신 내용을 가져와 주세요.
{% endhint %}
{% hint style="warning" %}
개인정보가 포함된 페이지(실명 후기, 문의 게시판 등)는 등록하지 않는 것을 권장합니다.
사이트에 보안 솔루션이 적용되어 있거나 특정 지역의 접근이 제한된 경우 페이지 내용을 가져오지 못할 수 있습니다. 이때는 사이트가 봇(자동 수집 프로그램)의 접근을 허용하는지 사이트 담당자에게 확인해 주세요. 확인이 어렵다면 도입 담당자에게 문의해 주세요.
{% endhint %}
### **3-2. 상태**
상태
의미
답변 반영
답변에 반영되고 있습니다.
반영 예정
유효기간 시작일이 되면 자동으로 답변에 반영됩니다.
학습 중
내용을 처리하는 중입니다.
답변 제외
답변에 반영하지 않습니다.
제외 중
답변에서 제외하는 처리 중입니다. 잠시 후 '답변 제외'로 바뀝니다.
기간 만료
유효기간이 지나 자동으로 제외되었습니다.
반영 실패
처리에 실패했습니다. URL이 올바른지 확인 후 다시 시도해 주세요.
{% hint style="warning" %}
반영 실패가 반복되면 사이트가 봇 접근을 막고 있을 수 있습니다. 봇 접근을 허용하는지 사이트 담당자에게 확인해 주세요.
{% endhint %}
### **3-3. 답변 반영 관리**
웹페이지별로 목록의 **답변 반영 스위치**나 **행 끝 관리 도구**에서 켜고 끌 수 있습니다.
* **답변에서 제외**: 답변에 반영하지 않습니다. 제외 처리에는 잠시 시간이 걸립니다.
* **답변에 반영**: 제외했던 웹페이지를 다시 반영합니다. 내용을 다시 가져와 처리(학습)를 거칩니다.
* **다시 시도**: 반영에 실패한 웹페이지를 다시 처리합니다.
### **3-4. 미리보기·다시 수집·수정·삭제**
* **미리보기**: 가져온 내용을 어드민에서 미리볼 수 있습니다.
* **다시 수집**: 페이지 내용이 바뀌었을 때, 같은 URL에서 최신 내용을 다시 가져와 답변에 반영합니다. 목록의 **최근 수집 일시**에서 언제 가져온 내용인지 확인할 수 있습니다. 목록 상단의 **다시 수집**을 누르면 여러 웹페이지를 골라 한 번에 수집할 수 있습니다.
* **수정**: 이름·유효기간을 수정할 수 있습니다. URL은 바꿀 수 없으니 다른 URL은 새로 등록해 주세요.
* **삭제**: 삭제하면 목록에서 바로 사라집니다. 답변에 쓰이던 내용이 지워지기까지 수 분이 걸릴 수 있으니, [**검색 미리보기**](https://help.genser.ai/overview/search-preview)에서 확인해 주세요. 삭제한 정보는 되돌릴 수 없습니다.
***
## **4. 링크**
링크는 페이지 내용을 가져오지 않고 관련 질문에 페이지 링크를 안내합니다. 로그인이 필요한 페이지나 배송 조회·반품 신청처럼 고객이 직접 확인하거나 진행해야 하는 페이지에 씁니다. 등록하면 바로 답변에 반영됩니다.
### **4-1. 등록**
{% hint style="info" %}
링크는 입력한 **이름·설명**으로만 질문과 연결합니다. 실제 질문에 쓰이는 표현으로 적어 주세요.
{% endhint %}
* 최대 300개까지 등록할 수 있습니다.
* 이미 등록된 링크와 URL이나 이름이 같으면 등록할 수 없습니다.
### **4-2. 상태**
상태
의미
답변 반영
답변에 반영되고 있습니다.
반영 예정
유효기간 시작일이 되면 자동으로 답변에 반영됩니다.
답변 제외
답변에 반영하지 않습니다.
기간 만료
유효기간이 지나 자동으로 제외되었습니다.
### **4-3. 답변 반영 관리·수정·삭제**
* **답변에서 제외·답변에 반영**: 목록의 **답변 반영 스위치**나 **행 끝 관리 도구**에서 바꾸며, 바로 반영됩니다.
* **수정**: URL·이름·설명·유효기간을 수정할 수 있고 바로 반영됩니다.
* **삭제**: 삭제하면 목록과 답변에서 바로 빠집니다. 삭제한 정보는 되돌릴 수 없습니다.
***
## **5. 답변 확인**
등록한 지식이 실제 답변에 어떻게 반영되는지는 헤더의 [**검색 미리보기**](https://help.genser.ai/overview/search-preview)에서 확인할 수 있습니다.
***
## **자주 묻는 질문**
Q. 문서나 웹페이지를 등록했는데 답변에 언제 반영되나요?
문서와 웹페이지는 내용을 처리한 뒤 답변에 반영됩니다. 보통 수 분, 길어도 10분 안팎이 걸립니다. 다만 웹페이지를 여러 개 한 번에 등록하거나 다시 수집하면 사이트에서 접근을 제한하지 않도록 나눠서 차례로 가져오기 때문에 모두 반영되기까지 더 걸릴 수 있습니다. 그동안 차례를 기다리는 웹페이지도 '학습 중'으로 표시됩니다. 링크는 바로 반영됩니다.
Q. 웹페이지와 링크는 무엇이 다른가요?
웹페이지는 페이지 내용을 가져와 답변에 반영합니다. 링크는 페이지 내용을 가져오지 않고 관련 질문에 페이지 링크를 안내합니다. 로그인이 필요해 내용을 가져올 수 없는 페이지나 고객이 직접 확인하거나 진행해야 하는 페이지는 링크로 등록해 주세요.
Q. 특정 문서·웹페이지·링크를 답변에서 빼고 싶습니다.
목록의 **답변 반영 스위치**를 끄거나 **관리 도구**에서 답변에서 제외하면 됩니다. 다시 반영하려면 같은 자리에서 되돌릴 수 있습니다.
Q. 반영 실패로 표시됩니다.
처리에 실패한 상태입니다. 다시 시도해 주세요. 문서는 같은 문제가 반복되면 다른 파일로, 웹페이지는 URL이 올바른지 확인 후 다시 시도해 주세요.
Q. 등록한 웹페이지 내용이 바뀌면 자동으로 업데이트되나요?
자동으로 업데이트되지 않습니다. 페이지 내용이 바뀌면 **다시 수집**으로 새로 가져와 주세요.
Q. 웹페이지를 등록했는데 답변에 그 내용이 나오지 않습니다.
**미리보기**에서 가져온 내용을 확인해 주세요. 필요한 내용이 이미지나 스크롤·더보기로 불러오는 내용, 다른 서비스에서 불러온 영역에 있으면 가져오지 못합니다. 이 경우 해당 내용을 PDF로 만들어 **문서** 탭에 등록해 주세요. PDF는 이미지도 학습합니다.
# 답변 설정-작성중
{% hint style="info" %}
**젠서 디스커버리 전용 기능**입니다.
{% endhint %}
답변 설정은 [**답변 지식 관리**](/knowledge/cs)에 등록한 지식으로 만든 답변 아래에 무엇을 함께 보여 줄지 정하는 페이지입니다. **후속 질문**과 **답변 출처 표시**를 각각 켜고 끌 수 있습니다.
## **1. 설정 항목**
{% hint style="danger" %}
**\[캡처 자리]** 어드민 › 지식 관리 › 답변 설정 화면. 병합 전에 실제 화면 캡처로 바꿔 주세요.
{% endhint %}
화면의 **지식 답변** 영역에서 설정합니다. 지식 답변은 답변 지식 관리에 등록한 지식으로 만든 답변입니다.
항목
설명
후속 질문
답변 아래에 고객이 이어서 물어볼 만한 질문을 버튼으로 제안합니다.
답변 출처 표시
답변 지식 관리 › 웹페이지에 등록한 페이지 중 답변에 활용된 링크를 출처로 표시합니다.
* 처음에는 두 항목 모두 꺼져 있습니다. 이미 후속 질문을 쓰고 있던 계정은 켜진 상태로 시작합니다.
* 젠서 디스커버리의 **채팅뷰**(PC·모바일)와 **디스커버리 미니**에 적용됩니다.
* 상품 추천 답변에는 적용되지 않습니다.
{% hint style="info" %}
**스플릿뷰에는 후속 질문 설정과 답변 출처가 적용되지 않습니다.** 채팅뷰와 디스커버리 미니에서만 바뀝니다.
{% endhint %}
***
## **2. 후속 질문**
{% hint style="danger" %}
**\[캡처 자리]** 채팅뷰 답변 아래에 후속 질문 버튼이 보이는 화면. 병합 전에 실제 화면 캡처로 바꿔 주세요.
{% endhint %}
후속 질문은 답변 내용에 맞춰 자동으로 만들어지므로 답변마다 다릅니다.
* 답변 하나에 최대 4개까지 표시됩니다.
* 고객이 질문 버튼을 누르면 그 문구가 다음 질문으로 바로 전송됩니다.
* 답을 찾지 못한 답변에도 표시됩니다.
{% hint style="info" %}
디자인 설정의 [**제안 질문**](/design/settings)과는 다른 기능입니다. 제안 질문은 처음 화면에 미리 정해 둔 질문이고, 후속 질문은 답변마다 자동으로 만들어져 답변 아래에 표시됩니다.
{% endhint %}
***
## **3. 답변 출처 표시**
{% hint style="danger" %}
**\[캡처 자리]** 채팅뷰 답변 아래 출처 줄과 「+N」을 눌러 연 전체 목록(PC·모바일). 병합 전에 실제 화면 캡처로 바꿔 주세요.
{% endhint %}
답변을 만들 때 참고한 웹페이지를 답변 아래에 출처로 보여 줍니다. 고객은 출처를 눌러 원래 페이지에서 내용을 직접 확인할 수 있습니다.
### **3-1. 표시 방식**
구분
설명
출처 줄
답변 아래 👍👎 버튼 밑에 「출처」와 함께 관련도가 가장 높은 페이지 2개가 표시됩니다.
+N
출처 줄에 보이지 않는 나머지 페이지 수입니다. 누르면 전체 목록이 열립니다.
전체 목록
「참고한 페이지 N」 목록에 관련도가 높은 순으로 최대 20개까지 표시됩니다. PC에서는 「+N」 옆에 작은 창으로, 모바일과 디스커버리 미니에서는 화면 아래에서 올라오는 창으로 열립니다.
* 출처는 페이지 제목과 사이트 아이콘(파비콘)으로 표시됩니다. 제목을 가져오지 못한 페이지는 도메인으로, 아이콘이 없는 페이지는 제목만 표시됩니다.
* 출처를 누르면 해당 페이지가 새 탭으로 열립니다. 고객이 보던 대화창은 그대로 유지됩니다.
* 같은 페이지는 한 번만 표시됩니다.
### **3-2. 출처가 표시되지 않는 경우**
출처는 답변 지식 관리의 **웹페이지** 탭에 등록한 페이지만 표시됩니다. 다음과 같은 답변에는 출처가 표시되지 않습니다.
* 답변을 만들 때 참고한 웹페이지가 없는 답변(문서만 참고한 답변 등)
* 답을 찾지 못한 답변
* 상품 추천 답변
{% hint style="info" %}
웹페이지를 등록하지 않았다면 답변 출처 표시를 켜도 출처가 표시되지 않습니다. 웹페이지 등록 방법은 [**답변 지식 관리**](/knowledge/cs)를 참고해 주세요.
{% endhint %}
***
## **4. 저장과 적용 시점**
* 스위치를 바꾼 뒤 **저장**을 누르면 두 항목이 함께 저장되고 「저장되었습니다. 새로운 답변부터 적용됩니다.」 안내가 표시됩니다.
* 저장 후 1분 정도 안에 새로 받는 답변부터 적용됩니다. 이미 열려 있는 대화창도 다음 질문부터 적용됩니다.
* 이미 받은 답변은 바뀌지 않습니다.
* 읽기 권한 계정은 설정을 볼 수만 있고 바꿀 수 없습니다.
***
## **자주 묻는 질문**
Q. 설정을 저장했는데 답변이 바뀌지 않습니다.
저장 후 1분 정도 안에 새로 받는 답변부터 적용됩니다. 이미 받은 답변은 바뀌지 않으니, 잠시 뒤 새 질문을 보내 확인해 주세요.
Q. 답변 출처 표시를 켰는데 출처가 보이지 않습니다.
출처는 **웹페이지** 탭에 등록한 페이지를 참고해 답을 찾은 답변에만 표시됩니다. 문서만 참고한 답변, 답을 찾지 못한 답변, 상품 추천 답변에는 표시되지 않습니다. 스플릿뷰에도 표시되지 않습니다.
Q. 후속 질문을 껐는데 답변 아래에 질문 버튼이 보입니다.
상품 추천 답변 아래의 질문 버튼은 이 설정과 관계없이 표시됩니다. 후속 질문 설정은 답변 지식 관리에 등록한 지식으로 만든 답변에만 적용됩니다.
Q. 후속 질문과 제안 질문은 무엇이 다른가요?
제안 질문은 디자인 설정에서 직접 정해 처음 화면에 표시하는 질문입니다. 후속 질문은 답변 내용에 맞춰 자동으로 만들어져 답변마다 표시됩니다.
# 디자인 설정
젠서 디스커버리 사이트와 젤라또 채널의 디자인 요소를 설정하는 페이지입니다. 보유한 권한에 따라 표시되는 항목이 다를 수 있습니다.
{% hint style="warning" %}
디자인 설정을 저장하면 변경 사항이 즉시 사이트에 반영됩니다. 사이트가 공개 상태일 경우 주의해 주세요.
{% endhint %}
{% hint style="info" %}
**젠서 디스커버리는 사이트마다 화면 모드가 하나입니다.** 같은 설정값이 스플릿뷰와 채팅뷰에서 서로 다른 자리에 표시되므로, 아래 예시 화면은 모드별 탭으로 나누어 두었습니다.
우리 사이트가 어느 모드인지는 화면 하단의 **\[미리보기]** 를 눌러 **Chat** 화면에서 확인할 수 있습니다. (4장 참고)
{% endhint %}
***
## **1. 브랜드 정보**
### **1-1. 브랜드명**
브랜드를 식별하는 이름으로, 젤라또 채널의 대화 목록 태그와 상품 상세 페이지 상단 채널명에 사용됩니다.
반영 위치
예시 화면
대화 목록
상품 상세 페이지
{% hint style="warning" %}
브랜드명은 최초 저장 후 최대 **3회**까지만 변경할 수 있습니다. 3회를 모두 소진하면 이후 수정이 불가능합니다. 신중하게 설정해 주세요.
{% endhint %}
* **중복 여부:** 브랜드명은 다른 채널과 중복될 수 없습니다. 입력 후 반드시 **\[중복 확인]** 을 눌러 확인해 주세요
* **입력 규칙:** `_`와 이모지를 제외하고 최대 20자까지 입력할 수 있습니다.
{% hint style="info" %}
**젠서 디스커버리(채팅뷰)에는 브랜드명이 그대로 표시되는 자리가 없습니다.** 진입 화면과 답변 위에는 **에이전트명**이 표시됩니다. 에이전트명을 「브랜드명과 동일」로 두면 브랜드명이 그 자리에 표시됩니다. (3-1 참고)
{% endhint %}
***
### **1-2. 로고 이미지**
사이트 전반에 표시되는 브랜드 로고입니다.
{% tabs %}
{% tab title="젤라또 채널" %}
반영 위치
예시 화면
메인 페이지
대화 창
상품 상세 페이지
{% endtab %}
{% tab title="젠서 디스커버리 (스플릿뷰)" %}
반영 위치
예시 화면
헤더
{% endtab %}
{% tab title="젠서 디스커버리 (채팅뷰)" %}
반영 위치
예시 화면
헤더
{% endtab %}
{% endtabs %}
#### **업로드 규격**
항목
설명
이미지 구성
디자인 최적화를 위해 배경이 없는 투명 로고 이미지를 권장합니다.
파일 형식
PNG, SVG 형식의 파일만 업로드할 수 있습니다.
파일 용량
최대 30KB까지 업로드할 수 있습니다.
파일 개수
최대 1개까지 파일을 업로드할 수 있습니다.
이미지 비율
가로:세로 비율이 1:1인 경우에만 업로드할 수 있습니다.
이미지 사이즈
가로, 세로 52px 이상인 경우에만 업로드할 수 있으며, 권장 사이즈는 120x120px입니다.
***
### **1-3. 메인 컬러**
사이트 전체 색상 톤을 결정하는 기준 컬러입니다. 선택한 컬러를 기준으로 밝고 어두운 10단계 색상인 컬러 스케일이 자동으로 생성되어 사이트 전반에 적용됩니다.
{% hint style="info" %}
메인 컬러는 HEX 코드를 직접 입력하거나 팔레트에서 선택할 수 있으며, **6자리 HEX 코드만 지원합니다.**
{% endhint %}
{% tabs %}
{% tab title="젤라또 채널" %}
반영 위치
예시 화면
메인 페이지
대화 목록
대화 창
검색 로딩 인터랙션
{% endtab %}
{% tab title="젠서 디스커버리 (스플릿뷰)" %}
반영 위치
예시 화면
메인 페이지
대화 창
검색 로딩 인터랙션
상품 카드
{% endtab %}
{% tab title="젠서 디스커버리 (채팅뷰)" %}
반영 위치
예시 화면
대화 창
검색 로딩 인터랙션
상품 카드
채팅뷰 진입 화면에는 메인 컬러가 적용되는 요소가 없습니다.
{% endtab %}
{% endtabs %}
***
## **2. 메인 검색 영역**
채널 메인·디스커버리 메인 페이지의 검색 영역에 표시되는 요소입니다.
### **2-1. 타이틀**
검색 영역 상단에 표시되는 메인 문구로, 최대 25자까지 설정할 수 있습니다. 젠서 디스커버리(채팅뷰)에서는 진입 화면에서 **가장 큰 글자**로 표시됩니다.
{% tabs %}
{% tab title="젤라또 채널" %}
{% endtab %}
{% tab title="젠서 디스커버리 (스플릿뷰)" %}
{% endtab %}
{% tab title="젠서 디스커버리 (채팅뷰)" %}
{% endtab %}
{% endtabs %}
***
### **2-2. 플레이스홀더**
검색창에 아무것도 입력하지 않은 상태에서 표시되는 안내 문구로, 최대 25자까지 설정할 수 있습니다.
{% tabs %}
{% tab title="젤라또 채널" %}
반영 위치
예시 화면
메인 페이지
대화 창
{% endtab %}
{% tab title="젠서 디스커버리 (스플릿뷰)" %}
반영 위치
예시 화면
메인 페이지
대화 창
{% endtab %}
{% tab title="젠서 디스커버리 (채팅뷰)" %}
반영 위치
예시 화면
대화 입력 영역
{% endtab %}
{% endtabs %}
***
### **2-3. 제안 질문**
검색 영역 하단에 표시되는 추천 질문 버튼이며, 무엇을 검색해야 할지 모르는 사용자가 클릭해서 바로 검색을 시작할 수 있습니다. 제안 질문은 최대 5개까지 추가할 수 있습니다.
{% tabs %}
{% tab title="젤라또 채널" %}
{% endtab %}
{% tab title="젠서 디스커버리 (스플릿뷰)" %}
{% endtab %}
{% tab title="젠서 디스커버리 (채팅뷰)" %}
{% endtab %}
{% endtabs %}
***
## **3. 에이전트**
대화 창에 표시되는 챗봇의 이름, 프로필 이미지, 첫 인사말을 설정합니다.
### **3-1. 에이전트명**
대화 창에서 챗봇이 자신을 칭하는 이름입니다.
{% tabs %}
{% tab title="젠서 디스커버리 (스플릿뷰) | 젤라또 채널" %}
{% endtab %}
{% tab title="젠서 디스커버리 (채팅뷰)" %}
반영 위치
예시 화면
메인 페이지
채팅 페이지
{% endtab %}
{% endtabs %}
* **브랜드명과 동일:** 위에서 입력한 브랜드명을 그대로 사용합니다. 이후 브랜드명을 변경하면 에이전트명도 자동으로 변경됩니다.
* **직접 설정:** 별도로 에이전트명을 설정할 수 있습니다. (최대 20자, 이모지 불가)
***
### **3-2. 프로필 이미지**
대화 창에서 챗봇 답변 옆에 표시되는 이미지입니다.
{% tabs %}
{% tab title="젠서 디스커버리 (스플릿뷰) | 젤라또 채널" %}
{% endtab %}
{% tab title="젠서 디스커버리 (채팅뷰)" %}
{% endtab %}
{% endtabs %}
* **로고 이미지와 동일:** 위에서 업로드한 로고 이미지를 그대로 사용합니다. 이후 로고 이미지를 변경하면 프로필 이미지도 자동으로 변경됩니다.
* **직접 설정:** 별도로 에이전트 이미지를 설정할 수 있습니다.\
(**형식:** JPG, PNG / **용량:** 최대 30KB / **비율:** 1:1 / **사이즈:** 52px 이상, 권장 120×120px)
***
### **3-3. 첫 인사**
대화 창에 처음 진입했을 때 챗봇이 사용자에게 보내는 인사말로, 최대 500자까지 설정할 수 있습니다.
{% tabs %}
{% tab title="젠서 디스커버리 (스플릿뷰) | 젤라또 채널" %}
{% endtab %}
{% tab title="젠서 디스커버리 (채팅뷰)" %}
{% endtab %}
{% endtabs %}
{% hint style="warning" %}
**젠서 디스커버리(채팅뷰)에서는 첫 인사가 2줄까지만 표시됩니다.** 3줄 이상은 잘려서 보이지 않습니다. 500자까지 입력할 수 있지만, 채팅뷰를 쓰는 사이트라면 **2줄 안에 들어가는 길이**로 작성해 주세요.
{% endhint %}
***
## **4. 미리보기**
디자인 설정을 저장하기 전에 지금까지 입력한 설정이 실제 사이트에 어떻게 반영되는지 미리 확인할 수 있습니다. 화면 하단의 \[미리보기] 버튼을 누르면 새 창에서 열립니다.
미리보기 화면 좌측 상단에는 **미리보기 툴 바**가 있습니다. 툴 바의 버튼을 눌러 화면을 전환하면 각 화면에 설정이 어떻게 적용되는지 확인할 수 있습니다. 미리보기에서는 실제 검색·클릭이 동작하지 않습니다. 화면을 바꿀 때는 이 툴 바를 이용해 주세요.
젠서 디스커버리(채팅뷰) 사이트의 미리보기 화면입니다.
* **Main:** 메인 페이지
* **Chat:** 대화 창 화면
* **PDP:** 상품 상세 페이지
{% hint style="info" %}
미리보기는 디자인 설정의 **필수 값을 모두 입력해야** 사용할 수 있습니다. 필수 값이 하나라도 비어 있으면 \[미리보기] 버튼이 비활성화됩니다.
{% endhint %}
***
## **자주 묻는 질문** Q. 브랜드명을 변경하려는데 입력 필드가 잠겨 있습니다.
브랜드명은 최초 저장 후 최대 3회까지만 변경할 수 있습니다. 3회를 모두 소진하면 이후 수정이 불가능합니다. 변경이 필요한 경우 담당자에게 문의해 주세요.
Q. 로고 이미지가 가로형인데 어떻게 업로드해야 하나요?
정사각형 캔버스(권장 120×120px) 중앙에 로고를 배치한 이미지를 만들어 업로드해 주세요. 배경이 투명한 PNG 형식을 사용하면 사이트 디자인과 자연스럽게 어울립니다.
Q. 메인 컬러를 입력했는데 기본값으로 되돌아갑니다.
메인 컬러 입력 필드는 6자리 HEX 코드만 지원합니다.
예를 들어, `#001689ff`처럼 투명도(알파값)가 포함된 8자리 코드를 입력하면 자동으로 기본값(`#B043FF`)으로 복원됩니다. 끝의 `ff`를 제외한 6자리(`#001689`)로 입력해 주세요.
Q. 파비콘과 링크 썸네일 항목이 보이지 않습니다.
파비콘과 링크 썸네일은 젠서 디스커버리 권한이 있는 경우에만 표시됩니다.
Q. 저장 전에 설정 내용을 미리 볼 수 있나요?
네, '미리보기' 기능으로 저장 전에 확인할 수 있습니다. 필수 값을 모두 채운 뒤 미리보기 버튼을 누르면 새 창(탭)에서 설정이 적용된 화면을 확인할 수 있습니다. 자세한 내용은 '4. 미리보기'를 참고해 주세요.
Q. 에이전트명을 '브랜드명과 동일'로 설정한 후 브랜드명을 변경하면 에이전트명도 바뀌나요?
네, 자동으로 변경됩니다. 프로필 이미지를 '로고 이미지와 동일'로 설정한 경우도 마찬가지로, 로고 이미지 변경 시 프로필 이미지도 자동으로 반영됩니다.
# 디스커버리 미니 설정
디스커버리 미니는 브랜드 자사몰에 AI 대화형 검색을 바로 시작할 수 있도록 사이트에 띄우는 작은 위젯입니다. 위젯 디자인과 오버레이 화면을 직접 설정하고, 준비가 되면 공개로 전환해 사이트에 노출할 수 있습니다.
***
## **1. 공개/비공개**
페이지 상단의 토글로 젠서 디스커버리 미니의 노출 여부를 설정합니다.
* **비공개(기본값):** 사이트에 젠서 디스커버리 미니가 노출되지 않습니다. 디자인을 자유롭게 설정하고 미리보기로 확인할 수 있습니다.
* **공개:** 스크립트가 설치된 사이트에 젠서 디스커버리 미니가 노출됩니다.
공개로 전환하려면 **\[디자인 설정]**이 완료되어야 합니다. 공개 후 젠서 디스커버리 미니가 정상적으로 노출되려면 젠서 디스커버리 스크립트가 설치되어 있어야 합니다. 설치 여부는 자동으로 확인되지 않으므로, [**\[스크립트 가이드\]**](https://help.genser.ai/developers/script-guide/genser-discovery-mini)를 참고해 직접 확인해 주세요.
{% hint style="warning" %}
공개 상태일 경우 디자인 변경 사항이 즉시 반영되므로 유의해 주세요.
{% endhint %}
***
## **2. 위젯 디자인 설정**
방문자 화면에 표시되는 위젯의 외형과 위치를 설정합니다. 위젯 유형을 먼저 선택한 후 세부 항목을 설정하세요.
디자인 설정 영역 상단의 **\[기본값으로 초기화]** 버튼을 클릭하면 위젯과 오버레이의 모든 설정이 기본값으로 되돌아갑니다. 기본값으로 초기화 후에 이전 설정 값은 복구할 수 없으니 주의해 주세요.
### **2-1. 위젯 유형**
오른쪽 드롭다운에서 **기본** 또는 **커스텀**을 선택합니다.
* **기본(기본값):** 젠서에서 제공하는 위젯(원형/드로어형/하단 바형)을 사용합니다. 유형을 선택하고 세부 항목을 설정하세요.
* **커스텀:** 자사몰에 직접 설정한 위젯 요소에 오버레이를 연결합니다. [**\[스크립트 가이드\]**](/developers/script-guide/genser-discovery-mini) 를 확인하여 위젯 요소에 오버레이를 연결해 주세요.
{% hint style="warning" %}
커스텀 위젯을 사용할 경우 위젯 미리보기는 지원되지 않습니다.
{% endhint %}
{% tabs %}
{% tab title="원형" %}
화면 모서리에 원형 버튼으로 표시됩니다. 클릭하면 오버레이가 열립니다.
#### **아이콘**
* **로고 이미지와 동일:** \[디자인 설정 > 로고 이미지]에 업로드된 이미지가 자동으로 적용됩니다. 이후 로고 이미지를 변경하면 위젯 아이콘도 함께 변경됩니다.
* **직접 설정:** 별도 이미지를 업로드할 수 있습니다.
* **업로드 규격**
| 항목 | 설명 |
| ------- | ------------------------------------------------------ |
| 이미지 구성 | 디자인 최적화를 위해 배경이 없는 이미지를 권장합니다. |
| 파일 형식 | PNG, SVG 형식의 파일만 업로드할 수 있습니다. |
| 파일 용량 | 최대 30KB까지 업로드할 수 있습니다. |
| 파일 개수 | 최대 1개까지 파일을 업로드할 수 있습니다. |
| 이미지 비율 | 가로:세로 비율이 1:1인 경우에만 업로드할 수 있습니다. |
| 이미지 사이즈 | 가로, 세로 96px 이상인 경우에만 업로드할 수 있으며, 권장 사이즈는 200×200px입니다. |
#### **배경색**
배경 색상을 설정합니다. HEX 코드를 직접 입력하거나 팔레트에서 선택할 수 있습니다.
{% hint style="info" %}
잘못된 HEX 코드를 입력하거나 입력값을 모두 지운 뒤 클릭을 해제하면 기본값으로 자동 복원됩니다.
* **잘못된 코드 예시:** `123456` (# 없음), `12#3456` (# 위치 오류), `#12G45Z` (16진수 외 문자 포함)
{% endhint %}
#### **사이즈**
위젯 크기를 32\~96px로 설정할 수 있습니다.
#### **노출 위치**
* **기준 위치:** 위젯을 화면 어느 위치에 고정할지 선택합니다. 기본값은 BR(우하단)이며, 선택한 위치에 따라 오프셋 측정 기준과 설정 범위가 달라집니다.
| 기준 위치 | 오프셋 측정 기준 | 기본값 | 설정 범위 |
| ----------------- | ----------------------- | ------------------------ | ---------------------------------------------- |
| 모서리 (TL/TR/BL/BR) | 선택한 모서리 가장자리에서 위젯까지의 거리 |
X: 24
Y: 24
| 0\~100px |
| 상단/하단 (T/B) | 화면 가로 중심점에서 위젯까지의 거리 |
X: 0
Y: 24
|
X: -100100px
Y: 0100px
|
| 좌측/우측 (L/R) | 화면 세로 중심점에서 위젯까지의 거리 |
X: 24
Y: 0
|
X: 0100px
Y: -100100px
|
* **오프셋:** 기준 위치에서 위젯이 얼마나 떨어져 있는지를 나타내는 거리 값입니다. X는 좌우, Y는 상하 방향 이동을 의미합니다. 예를 들어 BR(우하단)에서 X: 24, Y: 24로 설정하면 화면 우측 하단 모서리에서 좌쪽으로 24px, 위로 24px 떨어진 위치에 위젯이 표시됩니다.
* **Z-Index:** 웹 페이지에서 요소들이 겹칠 때 어느 것이 위에 표시될지를 결정하는 순서 값입니다. 숫자가 클수록 다른 요소 위에 표시됩니다. 위젯이 사이트의 다른 요소에 가려진다면 Z-Index를 더 높은 값으로 설정해 보세요.
#### **스타일**
* **둥근 모서리:** 0\~99% 범위에서 버튼 모서리의 둥글기를 설정합니다.
* **그림자:** On/Off 설정이 가능합니다. 기본값은 Off이며, On으로 설정하면 아래 항목을 조정할 수 있습니다.
| 항목 | 설명 | 기본값 | 범위 |
| --- | ------------------------------- | ---------------------- | ----------- |
| 색상 | 그림자 색상(HEX)과 불투명도(%)를 설정합니다. | #000000, 20% | — |
| 오프셋 | 위젯으로부터 그림자가 떨어지는 X·Y 방향 거리입니다. |
X: 0
Y: 0
| -100\~100px |
| 흐림 | 그림자 경계가 얼마나 번지는지를 조정합니다. | 16px | 0\~50px |
| 확산 | 그림자가 위젯보다 얼마나 더 넓게 퍼지는지를 조정합니다. | 0px | 0\~30px |
{% endtab %}
{% tab title="드로어형" %}
화면 가장자리에 세로 방향의 탭 형태로 표시됩니다. 기본 위치는 화면 우측 중앙입니다.
#### **아이콘**
* **로고 이미지와 동일:** \[디자인 설정 > 로고 이미지]에 업로드된 이미지가 자동으로 적용됩니다. 이후 로고 이미지를 변경하면 위젯 아이콘도 함께 변경됩니다.
* **직접 설정:** 별도 이미지를 업로드할 수 있습니다.
* **업로드 규격**
| 항목 | 설명 |
| ------- | ------------------------------------------------------ |
| 이미지 구성 | 디자인 최적화를 위해 배경이 없는 이미지를 권장합니다. |
| 파일 형식 | PNG, SVG 형식의 파일만 업로드할 수 있습니다. |
| 파일 용량 | 최대 30KB까지 업로드할 수 있습니다. |
| 파일 개수 | 최대 1개까지 파일을 업로드할 수 있습니다. |
| 이미지 비율 | 가로:세로 비율이 1:1인 경우에만 업로드할 수 있습니다. |
| 이미지 사이즈 | 가로, 세로 96px 이상인 경우에만 업로드할 수 있으며, 권장 사이즈는 200×200px입니다. |
#### **타이틀**
위젯에 표시할 텍스트를 On/Off합니다. On으로 설정하면 텍스트 입력 필드가 나타납니다.
{% hint style="info" %}
아이콘과 타이틀 중 **하나는 반드시 켜져 있어야** 합니다. 둘 다 끄려고 하면 안내 메시지가 표시됩니다.
{% endhint %}
#### **배경색**
배경 색상을 설정합니다. HEX 코드를 직접 입력하거나 팔레트에서 선택할 수 있습니다.
{% hint style="info" %}
잘못된 HEX 코드를 입력하거나 입력값을 모두 지운 뒤 클릭을 해제하면 기본값으로 자동 복원됩니다.
* **잘못된 코드 예시:** `123456` (# 없음), `12#3456` (# 위치 오류), `#12G45Z` (16진수 외 문자 포함)
{% endhint %}
#### **사이즈**
* **너비:** 32\~80px로 설정할 수 있습니다. (기본값: 40px)
* **높이:** 자동/고정으로 전환할 수 있습니다.
* **자동:** 아이콘·타이틀 설정에 따라 자동으로 조정됩니다.
* **고정:** 32\~320px로 직접 설정할 수 있습니다. (기본값: 96px)
#### **노출 위치**
* **기준 위치:** 위젯을 화면 좌(L) 또는 우(R)에 고정할 위치를 선택합니다. 기본값은 R(우측)입니다.
* **오프셋:** Y축 오프셋으로 위아래 위치만 조정할 수 있습니다.
| 오프셋 측정 기준 | 기본값 | 설정 범위 |
| -------------------- | ---- | ----------- |
| 화면 세로 중심점에서 위젯까지의 거리 | Y: 0 | -100\~100px |
* **Z-Index:** 웹 페이지에서 요소들이 겹칠 때 어느 것이 위에 표시될지를 결정하는 순서 값입니다. 숫자가 클수록 다른 요소 위에 표시됩니다. 위젯이 사이트의 다른 요소에 가려진다면 Z-Index를 더 높은 값으로 설정해 보세요.
#### **스타일**
* **둥근 모서리:** 0\~32px 범위에서 버튼 모서리의 둥글기를 설정합니다.
* **그림자:** On/Off 설정이 가능합니다. 기본값은 Off이며, On으로 설정하면 아래 항목을 조정할 수 있습니다.
| 항목 | 설명 | 기본값 | 범위 |
| --- | ------------------------------- | ---------------------- | ----------- |
| 색상 | 그림자 색상(HEX)과 불투명도(%)를 설정합니다. | #000000, 20% | — |
| 오프셋 | 위젯으로부터 그림자가 떨어지는 X·Y 방향 거리입니다. |
X: 0
Y: 0
| -100\~100px |
| 흐림 | 그림자 경계가 얼마나 번지는지를 조정합니다. | 16px | 0\~50px |
| 확산 | 그림자가 위젯보다 얼마나 더 넓게 퍼지는지를 조정합니다. | 0px | 0\~30px |
{% endtab %}
{% tab title="하단 바형" %}
화면 하단에 가로 방향의 버튼 형태로 표시됩니다. 아이콘, 텍스트, 화살표를 조합해 CTA(Call to Action)처럼 활용할 수 있습니다.
#### **아이콘**
* **로고 이미지와 동일:** \[디자인 설정 > 로고 이미지]에 업로드된 이미지가 자동으로 적용됩니다. 이후 로고 이미지를 변경하면 위젯 아이콘도 함께 변경됩니다.
* **직접 설정:** 별도 이미지를 업로드할 수 있습니다.
* **업로드 규격**
| 항목 | 설명 |
| ------- | ------------------------------------------------------ |
| 이미지 구성 | 디자인 최적화를 위해 배경이 없는 이미지를 권장합니다. |
| 파일 형식 | PNG, SVG 형식의 파일만 업로드할 수 있습니다. |
| 파일 용량 | 최대 30KB까지 업로드할 수 있습니다. |
| 파일 개수 | 최대 1개까지 파일을 업로드할 수 있습니다. |
| 이미지 비율 | 가로:세로 비율이 1:1인 경우에만 업로드할 수 있습니다. |
| 이미지 사이즈 | 가로, 세로 96px 이상인 경우에만 업로드할 수 있으며, 권장 사이즈는 200×200px입니다. |
#### **타이틀**
버튼에 표시할 텍스트를 On/Off합니다. On으로 설정하면 아래 항목이 나타납니다.
* **텍스트:** 최대 8자까지 입력할 수 있습니다.
* **텍스트 색상:** HEX 코드를 직접 입력하거나 팔레트에서 선택합니다.
#### **화살표**
버튼 우측에 표시할 화살표를 On/Off합니다. On으로 설정하면 아래 항목이 나타납니다.
* **아이콘:** 기본 제공 아이콘을 사용하거나 직접 이미지를 업로드할 수 있습니다.
* **색상:** HEX 코드를 직접 입력하거나 팔레트에서 선택합니다.
* **직접 설정 업로드 규격**
| 항목 | 설명 |
| ------- | ------------------------------------------------------ |
| 이미지 구성 | 디자인 최적화를 위해 배경이 없는 이미지를 권장합니다. |
| 파일 형식 | PNG, SVG 형식의 파일만 업로드할 수 있습니다. |
| 파일 용량 | 최대 30KB까지 업로드할 수 있습니다. |
| 파일 개수 | 최대 1개까지 파일을 업로드할 수 있습니다. |
| 이미지 비율 | 가로:세로 비율이 1:1인 경우에만 업로드할 수 있습니다. |
| 이미지 사이즈 | 가로, 세로 96px 이상인 경우에만 업로드할 수 있으며, 권장 사이즈는 200×200px입니다. |
{% hint style="info" %}
아이콘, 타이틀, 화살표 중 **하나는 반드시 켜져 있어야** 합니다. 셋 다 끄려고 하면 안내 메시지가 표시됩니다.
{% endhint %}
#### **배경색**
배경 색상을 설정합니다. HEX 코드를 직접 입력하거나 팔레트에서 선택할 수 있습니다.
{% hint style="info" %}
잘못된 HEX 코드를 입력하거나 입력값을 모두 지운 뒤 클릭을 해제하면 기본값으로 자동 복원됩니다.
* **잘못된 코드 예시:** `123456` (# 없음), `12#3456` (# 위치 오류), `#12G45Z` (16진수 외 문자 포함)
{% endhint %}
#### **사이즈**
* **너비:** 자동/고정으로 전환할 수 있습니다.
* **자동:** 아이콘·타이틀·화살표 설정에 따라 자동으로 조정됩니다.
* **고정:** 48\~640px로 직접 설정할 수 있습니다. (기본값: 320px)
* **높이:** 40\~64px로 설정할 수 있습니다. (기본값: 48px)
#### **노출 위치**
* **기준 위치:** 화면 하단 중앙에 고정됩니다.
* **오프셋:** X/Y 오프셋으로 위치를 미세 조정할 수 있습니다.
| 오프셋 측정 기준 | 기본값 | 설정 범위 |
| ------------------------- | --- | ----------- |
| 화면 가로 중심점에서 위젯까지의 거리 (X) | 0 | -100\~100px |
| 화면 하단 가장자리에서 위젯까지의 거리 (Y) | 0 | -100\~100px |
* **Z-Index:** 웹 페이지에서 요소들이 겹칠 때 어느 것이 위에 표시될지를 결정하는 순서 값입니다. 숫자가 클수록 다른 요소 위에 표시됩니다. 위젯이 사이트의 다른 요소에 가려진다면 Z-Index를 더 높은 값으로 설정해 보세요.
#### **스타일**
* **둥근 모서리:** 0\~32px 범위에서 버튼 모서리의 둥글기를 설정합니다. 좌우를 독립적으로 설정할 수도 있습니다.
* **그림자:** On/Off 설정이 가능합니다. 기본값은 Off이며, On으로 설정하면 아래 항목을 조정할 수 있습니다.
| 항목 | 설명 | 기본값 | 범위 |
| --- | ------------------------------- | ---------------------- | ----------- |
| 색상 | 그림자 색상(HEX)과 불투명도(%)를 설정합니다. | #000000, 20% | — |
| 오프셋 | 위젯으로부터 그림자가 떨어지는 X·Y 방향 거리입니다. |
X: 0
Y: 0
| -100\~100px |
| 흐림 | 그림자 경계가 얼마나 번지는지를 조정합니다. | 16px | 0\~50px |
| 확산 | 그림자가 위젯보다 얼마나 더 넓게 퍼지는지를 조정합니다. | 0px | 0\~30px |
{% endtab %}
{% endtabs %}
***
## **3. 오버레이 디자인 설정**
위젯을 클릭했을 때 열리는 오버레이 화면의 디자인을 설정합니다.
### **3-1. 오버레이 유형**
오버레이가 열리는 방식을 선택합니다. 팝 오버·드로어·풀 뷰를 각각 On/Off로 활성화할 수 있으며, 최소 하나는 반드시 활성화되어 있어야 합니다.
{% tabs %}
{% tab title="팝 오버" %}
화면 위에 창 형태로 오버레이가 나타납니다. 9방향 기준점을 선택해 화면 어디서든 띄울 수 있습니다.
#### **사이즈**
숫자를 직접 입력하고 단위를 선택할 수 있습니다.
{% hint style="info" %}
**px / dvw / dvh 단위 안내**
* **px**: 고정 픽셀 크기입니다. 화면 크기에 관계없이 항상 동일한 크기로 표시됩니다.
* **dvw**: 현재 화면 너비의 %입니다. 예를 들어 90dvw는 화면 너비의 90%를 의미합니다.
* **dvh**: 현재 화면 높이의 %입니다. 예를 들어 90dvh는 화면 높이의 90%를 의미합니다.
dvw/dvh를 사용하면 모바일·태블릿·데스크탑 등 다양한 화면 크기에 자동으로 맞춰집니다.
{% endhint %}
* **PC**
| 항목 | 기본값 (단위별) | 선택 가능 단위 | 설정 범위 |
| -- | ---------------------------- | ------------------- | ---------------------------------- |
| 너비 |
px: 760
dvw: 90
|
px
dvw
|
px: 제한 없음
dvw: 0\~100
|
| 높이 |
px: 600
dvh: 90
|
px
dvh
|
px: 제한 없음
dvh: 0\~100
|
* **모바일**
| 항목 | 기본값 (단위별) | 선택 가능 단위 | 설정 범위 |
| -- | ---------------------------- | ------------------- | ---------------------------------- |
| 너비 |
dvw: 90
px: 360
|
dvw
px
|
dvw: 0\~100
px: 제한 없음
|
| 높이 |
dvh: 90
px: 540
|
dvh
px
|
dvh: 0\~100
px: 제한 없음
|
#### **노출 위치**
* **기준 위치:** 기본값은 BR(우하단)이며, 선택한 위치에 따라 오프셋 측정 기준과 설정 범위가 달라집니다.
| 기준 위치 | 오프셋 측정 기준 | 기본값 | 설정 범위 |
| ----------------- | ------------------------- | ------------------------ | --------------------------------------------------------- |
| 모서리 (TL/TR/BL/BR) | 선택한 모서리 가장자리에서 오버레이까지의 거리 |
X: 24
Y: 24
|
X: 0100px Y: 0100px
|
| 중앙 (C) | 화면 중심점에서 오버레이까지의 거리 |
X: 0
Y: 0
|
X: -100100px Y: -100100px
|
| 상단/하단 (T/B) | 화면 가로 중심점에서 오버레이까지의 거리 |
X: 0
Y: 24
|
X: -100100px
Y: 0100px
|
| 좌측/우측 (L/R) | 화면 세로 중심점에서 오버레이까지의 거리 |
X: 24
Y: 0
|
X: 0100px
Y: -100100px
|
* **오프셋:** 기준 위치에서 오버레이가 얼마나 떨어져 있는지를 나타내는 거리 값입니다. 슬라이더 또는 숫자 직접 입력으로 설정할 수 있습니다.
#### **스타일**
* **둥근 모서리:** 오버레이 창의 모서리 둥글기를 설정합니다. (기본값: 16px, 범위: 0\~32px)
* **그림자:** On/Off 설정이 가능합니다. 기본값은 ON이며, On으로 설정하면 아래 항목을 조정할 수 있습니다.
| 항목 | 설명 | 기본값 | 범위 |
| --- | --------------------------------- | ---------------------- | ----------- |
| 색상 | 그림자 색상(HEX)과 불투명도(%)를 설정합니다. | #000000, 20% | — |
| 오프셋 | 오버레이로부터 그림자가 떨어지는 X·Y 방향 거리입니다. |
X: 0
Y: 0
| -100\~100px |
| 흐림 | 그림자 경계가 얼마나 번지는지를 조정합니다. | 16px | 0\~50px |
| 확산 | 그림자가 오버레이보다 얼마나 더 넓게 퍼지는지를 조정합니다. | 0px | 0\~30px |
{% endtab %}
{% tab title="드로어" %}
화면 좌측 또는 우측에서 슬라이드하여 오버레이가 나타납니다.
#### **사이즈**
너비는 직접 입력하고 단위를 선택할 수 있습니다. 높이는 항상 화면 전체 높이(100dvh)로 자동 고정되어 변경할 수 없습니다.
{% hint style="info" %}
**px / dvw / dvh 단위 안내**
* **px**: 고정 픽셀 크기입니다. 화면 크기에 관계없이 항상 동일한 크기로 표시됩니다.
* **dvw**: 현재 화면 너비의 %입니다. 예를 들어 80dvw는 화면 너비의 80%를 의미합니다.
* **dvh**: 현재 화면 높이의 %입니다. 100dvh는 화면 전체 높이를 의미합니다.
{% endhint %}
* **PC**
| 항목 | 기본값 (단위별) | 선택 가능 단위 | 설정 범위 |
| -- | ---------------------------- | ------------------- | ---------------------------------- |
| 너비 |
px: 420
dvw: 80
|
px
dvw
|
px: 제한 없음
dvw: 0\~100
|
| 높이 | 100dvh | — | 자동 고정 (변경 불가) |
* **모바일**
| 항목 | 기본값 (단위별) | 선택 가능 단위 | 설정 범위 |
| -- | ---------------------------- | ------------------- | ---------------------------------- |
| 너비 |
dvw: 80
px: 360
|
dvw
px
|
dvw: 0\~100
px: 제한 없음
|
| 높이 | 100dvh | — | 자동 고정 (변경 불가) |
#### **노출 위치**
* **기준 위치:** 오버레이를 화면 좌(L) 또는 우(R)에 고정할 위치를 선택합니다. 기본값은 R(우측)입니다.
| 기준 위치 | 설명 |
| ----- | ---------------- |
| L (좌) | 화면 좌측에 슬라이드하여 열림 |
| R (우) | 화면 우측에 슬라이드하여 열림 |
* **오프셋:** 드로어는 오프셋 설정 없이 선택한 기준 위치에 고정됩니다.
#### **스타일**
* **둥근 모서리:** 드로어가 슬라이드하는 반대쪽 모서리에만 둥글기가 적용됩니다. (범위: 0\~32px, 기본값: 0px)
* **기준 위치 R:** 좌상단·좌하단 모서리에 적용
* **기준 위치 L:** 우상단·우하단 모서리에 적용
* **그림자:** On/Off 설정이 가능합니다. 기본값은 ON입니다. 세부 항목 설정은 \[팝 오버 > 스타일 > 그림자]와 동일합니다.
{% endtab %}
{% tab title="풀 뷰" %}
화면 전체를 덮는 형태로 오버레이가 나타납니다.
#### **사이즈**
단위는 dvw/dvh로 고정되며 변경할 수 없습니다.
{% hint style="info" %}
**dvw / dvh 단위 안내**
* **dvw**: 현재 화면 너비의 %입니다. 예를 들어 90dvw는 화면 너비의 90%를 의미합니다.
* **dvh**: 현재 화면 높이의 %입니다. 예를 들어 90dvh는 화면 높이의 90%를 의미합니다.
풀 뷰는 다양한 화면 크기에 자동으로 맞춰지도록 dvw/dvh 단위만 사용합니다.
{% endhint %}
* **PC**
| 항목 | 기본값 | 단위 | 설정 범위 |
| -- | --- | --- | ------ |
| 너비 | 90 | dvw | 0\~100 |
| 높이 | 90 | dvh | 0\~100 |
* **모바일**
| 항목 | 기본값 | 단위 | 설정 범위 |
| -- | --- | --- | ------ |
| 너비 | 100 | dvw | 0\~100 |
| 높이 | 100 | dvh | 0\~100 |
#### **노출 위치**
* **기준 위치:** 화면 중앙으로 고정됩니다.
* **오프셋:** 중앙에서의 이동 거리를 미세 조정할 수 있습니다. 슬라이더 또는 숫자 직접 입력으로 설정할 수 있습니다.
| 오프셋 | 기본값 | 설정 범위 |
| --- | --- | ----------- |
| X | 0px | -100\~100px |
| Y | 0px | -100\~100px |
#### **스타일**
* **둥근 모서리:** 오버레이 창 네 모서리의 둥글기를 설정합니다. (기본값: 16px, 범위: 0\~32px)
* **그림자:** On/Off 설정이 가능합니다. 기본값은 ON입니다. 세부 항목 설정은 \[팝 오버 > 스타일 > 그림자]와 동일합니다.
{% endtab %}
{% endtabs %}
### **3-2. 상단바**
팝 오버·드로어·풀 뷰 세 가지 유형에 공통으로 적용되는 상단바를 설정합니다.
#### **배경색**
상단바의 배경 색상과 불투명도를 설정합니다. HEX 코드를 직접 입력하거나 팔레트에서 선택할 수 있으며, 투명도(%)도 함께 조정할 수 있습니다. (기본값: #FFFFFF / 100%)
#### **닫기 버튼**
오버레이를 닫는 버튼의 아이콘과 스타일을 설정합니다.
* **아이콘:** 기본 제공 아이콘 또는 직접 업로드한 이미지를 선택합니다. 직접 설정 선택 시 아래 규격에 맞는 이미지를 업로드할 수 있습니다.
| 항목 | 설명 |
| ------- | ------------------------------------------------------ |
| 이미지 구성 | 디자인 최적화를 위해 배경이 없는 이미지를 권장합니다. |
| 파일 형식 | PNG, SVG 형식의 파일만 업로드할 수 있습니다. |
| 파일 용량 | 최대 30KB까지 업로드할 수 있습니다. |
| 파일 개수 | 최대 1개까지 파일을 업로드할 수 있습니다. |
| 이미지 비율 | 가로:세로 비율이 1:1인 경우에만 업로드할 수 있습니다. |
| 이미지 사이즈 | 가로, 세로 96px 이상인 경우에만 업로드할 수 있으며, 권장 사이즈는 200×200px입니다. |
* **아이콘색:** 닫기 버튼 아이콘의 색상을 설정합니다. (기본값: #616161)
* **테두리색:** 닫기 버튼 테두리 표시 여부를 On/Off합니다. (기본값: Off)
* On으로 설정하면 색상 설정이 나타납니다. (기본값: #E0E0E0)
#### **유형 전환 버튼**
오버레이 안에서 팝 오버·드로어·풀 뷰 간에 전환할 수 있는 버튼입니다. 오버레이 유형이 2개 이상 활성화된 경우에만 설정할 수 있습니다.
팝 오버·드로어·풀 뷰 순서로 고정되며, 활성화된 유형만 선택할 수 있습니다. 기본값은 활성화된 유형 중 첫 번째 항목이 자동으로 선택됩니다.
* **아이콘색:** 유형 전환 버튼 아이콘의 색상을 설정합니다. (기본값: #616161)
* **테두리색:** 유형 전환 버튼 테두리의 색상을 설정합니다. (기본값: #E0E0E0)
* **강조색:** 현재 선택된 오버레이 유형 탭의 배경 강조 색상을 설정합니다. (기본값: #EBDFFF)
* **기본 오버레이:** 위젯 클릭 시 처음으로 열릴 오버레이 유형을 선택합니다.
***
## **4. 미리보기**
설정 화면 우측에서 현재 설정된 위젯과 오버레이 디자인을 실시간으로 확인할 수 있습니다.
* **PC / 모바일 전환:** 상단 버튼으로 PC와 모바일 화면을 전환해 각 환경에서의 모습을 확인할 수 있습니다.
* **오버레이 탭:** 오버레이 탭을 선택하면 팝 오버·드로어·풀 뷰 탭이 미리보기 상단에 표시됩니다. 탭을 선택하면 해당 유형의 오버레이 미리보기를 확인할 수 있습니다.
{% hint style="info" %}
미리보기에서는 오버레이 내 유형 전환 버튼, 닫기 버튼 등의 인터렉션은 동작하지 않습니다.
모바일 환경에서 설정 시 미리보기 영역은 숨겨지므로 PC 환경에서 설정하시는 것을 권장합니다.
{% endhint %}
***
## **자주 묻는 질문**
Q. 공개로 전환했는데 젠서 디스커버리 미니가 노출되지 않습니다.
사이트에 젠서 디스커버리 스크립트가 설치되어 있는지 확인해 주세요. 스크립트가 설치되지 않으면 공개 상태여도 위젯이 노출되지 않습니다. 설치 방법은 **스크립트 가이드**를 참고해 주세요.
Q. 드로어형/하단 바형에서 모든 요소를 끄려고 하는데 안 됩니다.
드로어형은 아이콘과 타이틀 중 하나, 하단 바형은 아이콘·타이틀·화살표 중 하나가 반드시 켜져 있어야 합니다. 위젯이 화면에 표시되려면 최소 하나의 요소가 필요하기 때문입니다.
Q. 드로어형 높이, 하단 바형 너비가 자동으로 바뀌는 이유가 무엇인가요?
켜져 있는 요소(아이콘, 타이틀, 화살표)에 따라 너비와 높이가 자동으로 계산됩니다. 예를 들어 타이틀을 끄면 너비가 줄어들고, 켜면 텍스트 길이에 맞게 자동으로 늘어납니다.
Q. 색상을 입력했는데 기본값으로 되돌아갑니다.
색상 입력 필드는 `#` 기호를 포함한 6자리 HEX 코드만 지원합니다. 예를 들어 `#1F1D1B` 형식으로 입력해야 합니다. `#` 없이 입력하거나 16진수 외 문자가 포함된 경우 기본값으로 자동 복원됩니다.
Q. 기본값으로 초기화 후 이전 설정으로 되돌리고 싶습니다.
기본값으로 초기화는 되돌릴 수 없습니다. 기본값으로 초기화 전에 현재 설정값을 별도로 기록해 두는 것을 권장합니다.
# 부가 옵션
젠서 디스커버리와 젤라또 채널의 사이트 표시, 상품 카드, 디스클레이머 등 세부 옵션을 설정하는 페이지입니다. 보유한 권한에 따라 표시되는 항목이 다를 수 있습니다.
***
## **1. 사이트 표시 정보**
{% hint style="info" %} **젠서 디스커버리** 전용 기능입니다.
{% endhint %}
브라우저와 메신저에서 사이트가 표시되는 방식을 설정합니다.
### **1-1. 파비콘 이미지**
브라우저 탭에 표시되는 아이콘입니다. 미설정 시 브라우저 기본 파비콘이 표시됩니다.
#### **업로드 규격**
항목
설명
파일 형식
JPG, PNG 형식의 파일만 업로드할 수 있습니다.
파일 용량
최대 1MB까지 업로드할 수 있습니다.
파일 개수
최대 1개까지 파일을 업로드할 수 있습니다.
이미지 사이즈
가로, 세로 512px인 경우에만 업로드할 수 있습니다.
{% hint style="info" %}
512×512px 이미지 1개만 업로드하면 다양한 환경에 맞는 크기로 자동 변환됩니다.
{% endhint %}
***
### **1-2. 링크 썸네일 이미지**
사이트 URL을 메신저나 SNS에 공유할 때 링크와 함께 표시되는 미리보기 이미지입니다. 미설정 시 URL 텍스트만 표시됩니다.
#### **업로드 규격**
항목
설명
파일 형식
JPG, PNG 형식의 파일만 업로드할 수 있습니다.
파일 용량
최대 1MB까지 업로드할 수 있으며, 권장 용량은 300KB입니다.
파일 개수
최대 1개까지 파일을 업로드할 수 있습니다.
이미지 사이즈
1200×630px인 경우에만 업로드할 수 있습니다.
***
## **2. 상품 카드**
검색 결과에 표시되는 상품 카드의 노출 정보와 클릭 동작 등을 설정합니다.
### **2-1. 부가 정보 표기**
{% hint style="info" %} **젠서 디스커버리** 전용 기능입니다.
{% endhint %}
상품 카드에 칩 형태로 표시되는 부가 정보를 설정합니다. 선택한 항목이 상품 카드에 부가 정보로 노출됩니다.
항목
설명
원산지
상품의 생산 국가 또는 지역
내용량
상품의 용량·수량 정보
소재
상품 소재
판매자
상품을 판매하는 판매자명
판매 단위
낱개·세트 등 판매 단위 정보
{% hint style="info" %}
부가 정보가 카드에 표시되려면 연동된 상품 데이터에 해당 필드 값이 있어야 합니다.
{% endhint %}
***
### **2-2. PDP 오픈 방식**
{% hint style="info" %} **젠서 디스커버리** 전용 기능입니다.
{% endhint %}
상품 카드를 클릭했을 때 상품 상세 페이지(PDP)가 열리는 방식을 설정합니다. **젠서 디스커버리**와 **젠서 디스커버리 미니**는 설정 옵션이 각각 다릅니다.
{% tabs %}
{% tab title="젠서 디스커버리" %}
옵션
동작 방식
팝업 (기본값)
상품 카드 클릭 시 현재 페이지 위에 팝업(모달)이 열립니다. 팝업 내 [자사몰 이동] 버튼을 누르면 상품 상세 페이지가 새 창으로 열립니다.
직접 연결
상품 카드 클릭 시 상품 상세 페이지가 새 창으로 바로 열립니다.
{% endtab %}
{% tab title="젠서 디스커버리 미니" %}
옵션
동작 방식
팝업
상품 카드 클릭 시 팝업(모달)이 열립니다. 팝업 내 [자사몰 이동] 버튼을 누르면 상품 상세 페이지로 이동하며, 창 열기 방식을 선택할 수 있습니다.
직접 연결 (기본값)
상품 카드 클릭 시 상품 상세 페이지로 바로 이동하며, 창 열기 방식을 선택할 수 있습니다.
* **창 열기 방식**: 모달 또는 직접 연결 선택 후 상품 페이지가 열리는 창을 선택합니다.
옵션
동작
현재 창 (기본값)
현재 탭에서 상품 상세 페이지로 이동합니다.
새 창
새 창(또는 새 탭)으로 상품 상세 페이지가 열립니다.
{% hint style="info" %}
젠서 디스커버리 미니는 자사몰 페이지 내에 삽입되는 형태이므로, 사용자 경험과 자사몰의 네비게이션 구조에 맞게 창 열기 방식을 설정해 주세요.
{% endhint %}
{% endtab %}
{% endtabs %}
***
### **2-3. 자사몰 이동 버튼명**
상품 상세 페이지(PDP) 팝업 내 **\[자사몰 이동]** 버튼에 표시되는 이름을 설정합니다.
| 옵션 | 설명 |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **기본값** |
상품 상세 페이지 URL 중 자사몰의 기본 도메인 주소가 기본값으로 적용됩니다.
모바일 상품 상세 페이지 URL이 별도로 등록된 상품의 경우, 고객의 접속 환경(PC/모바일)에 맞춰 각각 설정된 기본 도메인 주소가 버튼명으로 노출됩니다.
|
| **직접 입력** | 자사 브랜드에 맞는 버튼명을 직접 입력할 수 있습니다. |
{% hint style="warning" %}
젤라또 및 젤라또 채널의 경우, 광고성 문구, 허위·과장 표현, 경쟁사 언급 등이 포함된 버튼명은 사전 안내 후 운영 정책에 따라 기본값으로 변경될 수 있습니다.
{% endhint %}
***
### **2-4. 대표 URL**
상품 상세 페이지 팝업 내 자사몰 이동 버튼 또는 상품 카드 클릭(직접 연결) 시 해당 상품의 개별 URL이 없는 경우 대신 연결되는 URL입니다.
* 상품에 **개별 URL이 등록된 경우 대표 URL보다 우선 적용**됩니다.
* 쇼핑몰 **메인 페이지** 또는 **카테고리 페이지** URL을 설정하는 것을 권장합니다.
***
## **3. 디스클레이머**
{% hint style="info" %} **젠서 디스커버리** 전용 기능입니다.
{% endhint %}
AI가 생성한 답변임을 사용자에게 안내하는 문구를 설정합니다.
### **3-1. 문구**
AI 답변 하단에 노출되는 디스클레이머 문구를 설정합니다. 기본 제공 문구를 사용하거나, 직접 작성한 문구로 대체할 수 있습니다.
#### **기본값**
아래 문구가 자동으로 적용됩니다.
> 이 답변은 AI가 생성한 결과로, 실제 쇼핑몰의 상품 정보(가격, 혜택 등) 및 운영 정책과 다를 수 있습니다.
{% hint style="info" %}
별도로 수정할 필요가 없다면 기본값을 사용하는 것을 권장합니다.
{% endhint %}
#### **직접 입력**
기본 문구 대신 자사 서비스에 맞는 디스클레이머 문구를 직접 작성할 수 있습니다. 브랜드 톤에 맞게 표현을 바꾸거나, 추가로 고지할 내용이 있을 때 활용하세요.
{% hint style="warning" %}
사용자에게 AI 서비스임을 명확히 인지시키기 위해 **'AI'**, **'정보 불일치 가능성'** 키워드 포함을 권장합니다. 법적 고지 미비 시 해당 국가의 인공지능법 또는 전자상거래법에 따라 불이익을 받을 수 있습니다.
{% endhint %}
***
## **자주 묻는 질문**
Q. 파비콘이 변경되지 않고 이전 이미지가 계속 표시됩니다.
브라우저가 이전 파비콘을 캐시에 저장하고 있을 수 있습니다. 브라우저 캐시를 삭제하거나 시크릿 모드로 접속해 확인해 주세요.
Q. 링크 썸네일 이미지를 업로드했는데 메신저에서 반영되지 않습니다.
카카오톡, 슬랙 등 메신저는 링크 미리보기를 캐시로 저장합니다. 이미지 변경 후 즉시 반영되지 않을 수 있으며, 수 시간에서 최대 수일 이내에 자동으로 갱신됩니다.
Q. 상품 카드에 부가 정보가 표시되지 않습니다.
부가 정보 표기를 활성화해도 상품 데이터에 해당 항목 값이 없으면 카드에 표시되지 않습니다. 상품 연동 데이터에 해당 필드가 포함되어 있는지 확인해 주세요.
Q. 젠서 디스커버리 또는 젠서 디스커버리 미니의 PDP 오픈 방식을 '직접 연결'로 설정하면 팝업(모달)이 완전히 사라지나요?
네, 직접 연결 선택 시 팝업(모달) 없이 상품 상세 페이지로 바로 이동합니다. 젠서 디스커버리 미니의 경우, 창 열기 방식 설정에 따라 현재 창 또는 새 창으로 열립니다.
Q. 대표 URL에는 어떤 URL을 입력해야 하나요?
상품 개별 URL이 없는 경우 대신 연결할 페이지의 URL을 입력합니다. 반드시 `http://` 또는 `https://`로 시작하는 완전한 URL 형식이어야 하며, 최대 1,000자까지 입력할 수 있습니다.
Q. 디스클레이머 문구를 직접 입력할 때 꼭 'AI'라는 단어를 포함해야 하나요?
법적 의무는 아니지만, 인공지능법 및 전자상거래법에 따라 AI 서비스임을 명확히 고지하지 않으면 불이익이 발생할 수 있습니다. 'AI', '정보 불일치 가능성' 키워드 포함을 강력히 권장합니다.
# 사이트
# 기본 설정
젠서 디스커버리 사이트 및 젤라또 채널의 주소와 공개 여부를 설정하는 페이지입니다.
## **1. 젤라또 채널**
{% stepper %}
{% step %}
### **사이트 ID 등록**
사이트를 식별하는 고유 ID입니다. **\[등록]** 클릭 시 사이트 ID를 입력하는 화면이 노출되며, 등록 완료 시 젤라또 채널 주소가 자동으로 설정됩니다.
* **입력 규칙:** 공백을 제외한 영문 소문자, 숫자, 하이픈(`-`)만 최대 20자까지 입력할 수 있습니다.
{% hint style="warning" %}
사이트 ID는 최초 등록 후 변경할 수 없습니다. 등록 전에 다시 한번 확인해 주세요.
{% endhint %}
{% endstep %}
{% step %}
### **사이트 공개**
사이트 ID 등록 직후에는 비공개 상태로 시작되며, 디자인 설정이 완료되어야 사이트를 공개할 수 있습니다.
비공개 상태에서는 방문자가 사이트 접속 시 **준비중 화면**이 표시됩니다.
{% endstep %}
{% endstepper %}
***
## **2. 젠서 디스커버리**
{% stepper %}
{% step %}
### **사이트 ID 등록**
사이트 ID는 젠서 디스커버리·젤라또 채널 공통 선행 조건입니다. 등록 방법은 [**\[젤라또 채널 > 사이트 ID 등록\]**](#id-1-1)을 참고해 주세요.
{% endstep %}
{% step %}
### **도메인 설정**
도메인 설정에는 아래 조건이 필요합니다.
조건
설명
도메인 소유
입력한 도메인을 소유하고 있어야 합니다.
DNS 설정 권한
도메인을 구매한 서비스에서 DNS를 설정할 수 있어야 합니다.
#### **Step 1. 도메인 입력**
**\[도메인 설정]**을 클릭하면 설정 화면이 열립니다. 젠서 디스커버리에 연결할 커스텀 도메인을 입력해 주세요.
{% hint style="info" %}
서브도메인이 포함된 도메인을 입력해 주세요. (예: `discovery.myshop.com`) 루트 도메인만으로는 설정할 수 없습니다. (예: `myshop.com` 입력 불가)
{% endhint %}
{% hint style="warning" %}
도메인은 연결이 완료되면 변경할 수 없습니다. 입력한 도메인을 다시 한번 확인해 주세요.
{% endhint %}
#### **Step 2. DNS 설정**
DNS 설정을 위한 CNAME 레코드 값을 확인 후 저장해 주세요. DNS 설정은 도메인을 구매한 서비스(AWS Route 53, Cloudflare 등)에서 진행할 수 있습니다.
설정 항목
참고 사항
Type
반드시 CNAME 레코드 타입으로 설정해 주세요.
Name
일부 서비스에서는 서브도메인만 입력하고(예: discovery), 일부 서비스에서는 전체 도메인을 입력(예: discovery.mydomain.com)하는 등 서비스마다 입력 형식이 다를 수 있습니다. 해당 서비스의 안내를 따라 주세요.
Target
edge.genser.ai를 정확히 입력해 주세요.
{% endstep %}
{% step %}
### **연결 상태 확인**
저장이 완료되면 연결 상태 확인 영역이 나타납니다. **\[연결 상태 확인]** 을 클릭해 연결을 완료해 주세요. DNS 설정 확인과 SSL 인증서 발급이 순차적으로 검증됩니다. 두 항목이 모두 통과되면 도메인 연결이 완료됩니다.
항목
설명
DNS 설정 확인
CNAME 레코드가 정상적으로 등록되었는지 확인합니다.
SSL 인증서 발급
SSL 인증서가 발급되었는지 확인합니다.
{% hint style="info" %}
연결이 완료되지 않은 상태에서 페이지를 새로고침하거나 다시 진입하면 연결 상태를 자동으로 확인합니다.
{% endhint %}
#### **연결 오류 시 해결 방법** DNS 설정이 확인되지 않는 경우
* CNAME이 아닌 다른 레코드 타입(A 레코드 등)으로 설정되어 있다면, 기존 레코드를 삭제하고 CNAME 레코드로 다시 등록해 주세요.
* CNAME의 Name이 DNS 설정 서비스의 안내에 따라 올바르게 입력되어 있는지 확인해 주세요.
* CNAME의 Target이 edge.genser.ai가 아닌 다른 값으로 되어 있다면, 올바른 값으로 수정해 주세요.
SSL 인증서가 발급되지 않는 경우
* 도메인 설정 저장 후 **SSL 인증서 발급은 일반적으로 최대 1시간**이 소요됩니다. 이후에도 오류가 지속될 경우 로 문의해 주세요.
{% endstep %}
{% step %}
### **사이트 공개**
도메인이 정상 연결되고 디자인 설정이 완료되어야 사이트를 공개할 수 있습니다.
비공개 상태에서는 방문자가 사이트 접속 시 **준비중 화면**이 표시됩니다.
{% endstep %}
{% endstepper %}
***
## **자주 묻는 질문** Q. 사이트 ID를 등록한 후 변경할 수 있나요?
사이트 ID는 최초 등록 후 변경할 수 없습니다. 등록 전에 신중하게 확인해 주세요.
Q. 디자인 설정이 완료되지 않으면 공개 전환이 안 되나요?
네, 공개로 전환하려면 디자인 설정이 완료되어 있어야 합니다.
Q. 공개 상태에서 다시 비공개로 전환할 수 있나요?
네, 공개와 비공개는 언제든지 전환할 수 있습니다. 비공개로 전환하면 방문자가 사이트에 접속할 수 없습니다.
Q. CNAME 설정이란 무엇인가요?
CNAME은 하나의 도메인을 다른 도메인으로 연결하는 DNS 설정입니다. 소유한 도메인(예: `myshop.com`)의 서브도메인(예: `discovery.myshop.com`)에 CNAME을 설정하면, 해당 주소로 접속했을 때 디스커버리 화면이 표시됩니다.
Q. 서브도메인이 무엇인가요?
서브도메인은 도메인 앞에 붙는 단어를 말합니다. 예를 들어 `discovery.mydomain.com`에서 `discovery`가 서브도메인입니다.
커스텀 도메인은 반드시 서브도메인이 포함된 형태로 입력해야 하며, 루트 도메인(`mydomain.com`)만으로는 설정할 수 없습니다.
Q. DNS 설정은 어디서 하나요?
도메인을 구매한 서비스에서 설정합니다. AWS Route 53, Cloudflare 등 DNS 서비스 제공업체의 관리 화면에서 CNAME 레코드를 추가할 수 있습니다. 각 서비스마다 설정 방법이 다르므로, 해당 서비스의 도움말을 참고해 주세요.
Q. SSL 인증서를 별도로 구매해야 하나요?
아닙니다. DNS 설정이 완료되면 SSL 인증서가 자동으로 발급됩니다. 별도로 인증서를 구매하거나 설치할 필요가 없습니다.
Q. 도메인 연결 완료 후 도메인을 변경할 수 있나요?
도메인은 연결이 완료되면 변경할 수 없습니다. 변경이 필요한 경우 으로 문의해 주세요.
# 파라미터 설정
젠서 디스커버리 및 젤라또에 유입되는 방문자의 출처를 추적할 수 있도록, URL에 UTM 파라미터와 커스텀 파라미터를 설정하는 페이지입니다. 보유한 권한에 따라 표시되는 항목이 다를 수 있습니다.
{% hint style="info" %}
설정한 값이 실제 URL에 어떻게 적용되고 Google Analytics에서 어떻게 확인하는지는 [유입 트래픽 추적 (UTM)](https://help.genser.ai/reference/utm-tracking)에서 확인할 수 있습니다.
{% endhint %}
***
## **1. 젤라또**
### **1-1. UTM 파라미터**
웹 분석 도구에서 범용으로 인식되는 표준 파라미터입니다. 기본값을 사용하거나, 직접 값을 설정할 수 있습니다.
#### **사용 여부 선택**
Switch가 켜진 상태로 시작하며 기본값이 적용됩니다. UTM 파라미터를 사용하지 않으려면 Switch를 끕니다.
* 기본값: 젤라또에서 자동으로 생성한 UTM 값을 사용합니다.
* 직접 설정: UTM 파라미터 값을 직접 등록합니다.
#### **기본값**
자동으로 생성된 UTM 값이 읽기 전용으로 표시되며, 별도로 등록하거나 수정할 필요가 없습니다.
Key
Value
utm_source
gelatto.ai로 고정됩니다.
utm_medium
referral로 고정됩니다.
#### **직접 설정 > 파라미터 등록**
**\[등록]** 클릭 시 **\[UTM 파라미터 등록]** 모달이 열립니다.
항목
설명
Key
파라미터 항목당 1개만 등록 가능하며, 선택 가능한 Key는 다음과 같습니다.
utm_source
utm_medium
utm_campaign
utm_term
utm_content
Value (필수)
공백 포함 최대 200자 입력 가능합니다. 한글, 공백, 특수문자 등은 URL 인코딩되어 적용됩니다.
상세 설명
공백 포함 최대 45자 입력 가능하며, 맨 앞에는 공백을 입력할 수 없습니다.
{% hint style="warning" %}
UTM 파라미터는 최대 5개까지 등록할 수 있습니다.
{% endhint %}
UTM 파라미터 설정을 변경한 후에는 **\[저장]** 버튼을 클릭해야 반영됩니다.
***
## **2. 젠서 디스커버리**
### **2-1. UTM 파라미터**
웹 분석 도구에서 범용으로 인식되는 표준 파라미터입니다. 기본값을 사용하거나, 직접 값을 설정할 수 있습니다.
#### **사용 여부 선택**
Switch를 켜면 파라미터 적용 방식을 선택할 수 있습니다. Switch는 꺼진 상태로 시작합니다.
* 기본값: 자동으로 생성한 UTM 값을 사용합니다.
* 직접 설정: UTM 파라미터 값을 직접 등록합니다.
#### **기본값**
자동으로 생성된 UTM 값이 읽기 전용으로 표시되며, 별도로 등록하거나 수정할 필요가 없습니다.
{% hint style="info" %}
도메인 연결이 완료되기 전에는 `utm_source` 값이 대시(`-`)로 표시됩니다. 이 상태에서도 설정을 저장할 수 있으며, `[기본 설정 > 젠서 디스커버리]`에서 도메인 연결을 완료하면 값이 자동으로 표시됩니다.
{% endhint %}
#### **직접 설정 > 파라미터 등록**
**\[등록]** 클릭 시 **\[UTM 파라미터 등록]** 모달이 열립니다.
항목
설명
Key
파라미터 항목당 1개만 등록 가능하며, 선택 가능한 Key는 다음과 같습니다.
utm_source
utm_medium
utm_campaign
utm_term
utm_content
Value (필수)
공백 포함 최대 200자 입력 가능합니다. 한글, 공백, 특수문자 등은 URL 인코딩되어 적용됩니다.
상세 설명
공백 포함 최대 45자 입력 가능하며, 맨 앞에는 공백을 입력할 수 없습니다.
{% hint style="warning" %}
UTM 파라미터는 최대 5개까지 등록할 수 있습니다.
{% endhint %}
### **2-2. 커스텀 파라미터**
UTM 외에 필요한 파라미터를 key와 value 형태로 등록할 수 있습니다. Switch를 켜면 파라미터를 등록할 수 있습니다.
#### **파라미터 등록**
**\[등록]** 클릭 시 **\[커스텀 파라미터 등록]** 모달이 열립니다.
항목
설명
Key (필수)
텍스트 직접 입력 방식입니다. 영문, 숫자, 하이픈(-), 언더스코어(_)만 입력 가능하며 최대 50자입니다. 한글, 공백, 그 외 특수문자·이모지는 입력할 수 없습니다.
Value (필수)
공백 포함 최대 200자 입력 가능합니다. 한글, 공백, 특수문자 등은 URL 인코딩되어 적용됩니다.
상세 설명
공백 포함 최대 45자 입력 가능하며, 맨 앞에는 공백을 입력할 수 없습니다.
{% hint style="warning" %}
커스텀 파라미터는 최대 10개까지 등록할 수 있습니다.
{% endhint %}
UTM 파라미터와 커스텀 파라미터는 하나의 **\[저장]** 버튼으로 함께 저장됩니다.
***
## **자주 묻는 질문**
Q. UTM 파라미터와 커스텀 파라미터는 몇 개까지 등록할 수 있나요?
UTM 파라미터는 최대 5개(`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`), 커스텀 파라미터는 최대 10개까지 등록할 수 있습니다.
Q. 커스텀 파라미터 Key에 한글이나 특수문자를 사용할 수 있나요?
아니요. 커스텀 파라미터 Key는 영문, 숫자, 하이픈(-), 언더스코어(\_)만 입력할 수 있습니다. 한글, 공백, 그 외 특수문자와 이모지는 입력되지 않습니다.
Q. 커스텀 파라미터 Key로 utm_source 같은 이름을 등록할 수 있나요?
등록할 수 없습니다. UTM 파라미터 전용 Key(utm\_source, utm\_medium, utm\_campaign, utm\_term, utm\_content)와 대소문자 구분 없이 일치하는 값은 예약어로 간주되어 에러 처리됩니다.
Q. 젠서 디스커버리 utm_source 값이 대시(-)로 표시됩니다.
기본값의 `utm_source`에는 연결한 커스텀 도메인이 들어갑니다. `[기본 설정 > 젠서 디스커버리]`에서 도메인 연결을 완료하면 값이 자동으로 표시됩니다. 도메인 연결 전에도 파라미터 설정을 저장할 수 있습니다.
Q. 설정한 파라미터가 실제 URL에 어떻게 적용되나요?
자사몰로 이동하는 링크에 추가됩니다. 적용 규칙과 Google Analytics에서 확인하는 방법은 [유입 트래픽 추적 (UTM)](https://help.genser.ai/reference/utm-tracking)을 참고해 주세요.
Q. Value에 한글이나 공백을 입력하면 어떻게 되나요?
입력 자체는 가능하지만, 실제 URL에는 자동으로 인코딩되어 반영됩니다. 예를 들어 공백은 `%20`으로, 한글은 UTF-8 기준 퍼센트 인코딩 값으로 변환됩니다.
# 앱 설정
앱에서 젠서 디스커버리를 열 때 적용할 동작을 설정하는 페이지입니다. 웹 브라우저로 열 때와 다르게 동작해야 하는 경우에 사용합니다. 앱이 보내는 User-Agent로 앱을 구분한 뒤 그 앱에 적용할 동작을 선택합니다. 저장하면 해당 앱에 바로 적용됩니다.
***
## **1. 식별 키워드**
앱을 구분하는 값입니다. 앱이 보내는 User-Agent에 이 값이 들어 있으면 해당 앱으로 인식합니다.
{% stepper %}
{% step %}
### **값 정하기**
앱 담당자와 상의해 값을 정합니다. 앱에 이미 들어 있는 값이 있으면 그 값을 확인합니다.
앱 상황
진행 방법
앱에 값이 아직 없음
등록할 값을 정한 뒤 앱 담당자에게 전달합니다.
앱에 값이 이미 있음
앱 담당자에게 값을 확인합니다.
정해진 형식은 없습니다. 앱을 알아볼 수 있는 값이면 됩니다. `Mobile`처럼 짧고 흔한 값은 앱이 아닌 일반 모바일 웹에도 걸릴 수 있으므로, 앱을 특정할 수 있을 만큼 고유한 값을 사용해 주세요.
{% endstep %}
{% step %}
### **앱에 값 넣기**
앱이 보내는 User-Agent에 정한 값을 넣어 달라고 앱 담당자에게 요청합니다.
{% hint style="warning" %}
**\[앱 설정]**에 등록하는 것만으로는 동작하지 않습니다. 앱이 보내는 User-Agent에도 같은 값이 들어 있어야 합니다.
{% endhint %}
앱을 무엇으로 만들었는지는 관계없습니다. 자체 개발한 앱이든 앱 구축 솔루션으로 만든 앱이든 User-Agent에 값이 들어 있으면 동작이 적용됩니다.
{% endstep %}
{% step %}
### **\[앱 설정]에 등록하기**
정한 값을 그대로 등록합니다.
항목
설명
길이
1자 이상 50자 이하로 입력할 수 있습니다.
등록 건수
최대 10건까지 등록할 수 있습니다.
대소문자
MyApp과 myapp은 서로 다른 값으로 인식합니다.
중복
이미 등록한 값과 같은 값은 등록할 수 없습니다.
앱 버전이나 OS에 따라 앱이 보내는 값이 다르면 여러 개 등록할 수 있습니다. 등록한 값 중 하나만 User-Agent에 들어 있어도 동작이 적용됩니다.
{% endstep %}
{% endstepper %}
***
## **2. 적용할 동작**
식별 키워드로 인식한 앱에서 젠서 디스커버리를 열 때 적용할 동작을 선택합니다. 선택한 동작은 등록한 식별 키워드 전체에 적용됩니다. 값마다 다른 동작을 지정할 수는 없습니다.
동작
설명
헤더 숨기기
사이트 최상단 영역을 숨깁니다. 앱에 자체 헤더가 있으면 선택해 주세요.
앱에 자체 헤더가 있는데 젠서 디스커버리도 헤더를 그리면 화면 위쪽에 헤더가 두 겹으로 보입니다. 헤더 숨기기를 선택하면 젠서 디스커버리 쪽 헤더가 표시되지 않습니다.
***
## **자주 묻는 질문**
Q. 식별 키워드에 앱 버전을 넣어도 되나요?
넣을 수 있지만 권장하지 않습니다. 앱을 업데이트하면 버전이 바뀌면서 등록한 값이 더 이상 걸리지 않습니다. 업데이트할 때마다 값을 다시 등록해야 합니다.
버전을 제외하고 앱을 알아볼 수 있는 부분만 등록하면 업데이트 후에도 그대로 적용됩니다.
Q. 저장했는데 앱에서 동작이 적용되지 않습니다.
앱이 보내는 User-Agent에 등록한 값이 들어 있는지 앱 담당자에게 확인해 주세요. **\[앱 설정]**에 등록하는 것만으로는 동작하지 않습니다.
값을 확인했는데도 적용되지 않으면 으로 문의해 주세요.
Q. 동작을 선택하지 않고 저장할 수 있나요?
네, 저장할 수 있습니다. 식별 키워드는 그대로 두고 동작만 해제하면 등록한 값을 지우지 않고도 적용을 멈출 수 있습니다.
# API 키
최초 진입 시에는 API 키가 발급되지 않은 상태입니다. **\[발급]** 버튼 클릭 시새로운 API 키를 발급 받을 수 있습니다.
키 발급이 완료되면 카드 화면에 마스킹된 API 키가 표시됩니다.
기능
설명
보기
클릭 시 마스킹 처리된 API 키 전체를 확인합니다.
복사
API 키를 클립보드에 복사합니다.
{% hint style="info" %}
발급된 API 키 하나로 젤라또, 네이버 커머스, GMC 등 **모든 API 연동에 공통으로 사용**할 수 있습니다.
{% endhint %}
{% hint style="warning" %}
API 키가 외부에 노출될 경우 무단으로 데이터가 전송되거나 훼손될 위험이 있습니다. 키가 유출되지 않도록 보안 관리에 주의해 주세요.
{% endhint %}
# 계정
계정 정보·보안 설정을 관리하는 페이지입니다. 보유한 권한에 따라 표시 항목이 다를 수 있으며, 개인정보 보호를 위해 진입 시마다 비밀번호 재확인이 요청됩니다.
## **1. 내 정보**
내 정보 탭에서는 계정의 기본 정보를 확인하고 수정할 수 있습니다.
### **1-1. 기본 정보**
항목
설명
ID
현재 로그인된 계정의 ID가 표시됩니다. 주관리자 계정의 경우, ID 우측에 라벨이 표시됩니다.
성명
최대 60자 이내로 수정할 수 있습니다.
***
## **2. 계정 관리**
{% hint style="info" %} **주관리자**만 제어할 수 있는 기능입니다.
{% endhint %}
계정 관리 탭에서는 주관리자 계정 정보와 생성된 계정 목록을 확인하고, 권한 변경·상태 관리·2단계 인증 초기화·주관리자 권한 이관 등 계정 운영에 필요한 기능을 설정 및 관리할 수 있습니다.
### **2-1. 계정 생성** 버튼을 클릭하여 새로운 계정을 생성할 수 있습니다.
* **ID:** 로그인 계정으로 사용할 이메일 주소를 입력해 주세요. 해당 이메일로 계정의 임시 비밀번호가 발송됩니다.
* **성명:** 계정에 사용할 성명을 입력해 주세요. 계정 생성 후에는 해당 계정의 사용자만 수정할 수 있습니다.
* **권한 설정:** 기본으로 제공되는 권한 중 하나를 선택해 주세요.
권한
접근 범위
운영 관리자
사용 서비스에 따른 모든 기능의 설정 및 제어 가능
뷰어(Viewer)
사용 서비스에 따른 모든 기능의 조회만 가능
{% hint style="warning" %}
계정 ID는 생성 후 수정할 수 없으며, 이미 사용 중인 이메일은 ID로 등록할 수 없습니다. 계정은 주관리자 계정을 포함해 최대 30개까지 생성할 수 있습니다.
{% endhint %}
***
### **2-2. 계정 목록**
헤더
설명
ID
계정 생성 시 설정한 ID(이메일)입니다. 생성 이후 수정은 불가합니다.
성명
계정 생성 시 설정한 성명입니다. 생성 이후 해당 계정의 사용자만 수정 가능합니다.
권한
계정 생성 시 설정한 권한입니다.
계정 상태
계정의 현재 상태입니다. (정상, 차단)
2단계 인증 상태
계정의 현재 2단계 인증 상태입니다. (2단계 인증 사용 설정 시 표시됩니다.)
생성일
계정이 생성된 날짜입니다.
최종 수정일
계정 정보를 마지막으로 수정한 날짜입니다.
계정 상태
상태
설명
정상
계정 생성 시 기본 상태입니다.
차단
계정을 차단하여 서비스 접근을 제한한 상태입니다.
***
### **2-3. 관리 도구**
행(Row) 우측의 아이콘을 클릭하면, 해당 계정을 관리할 수 있는 메뉴가 나타납니다.
관리 도구
설명
수정
선택한 계정의 권한을 수정합니다.
차단
선택한 계정을 차단하여 로그인을 제한합니다.
차단 해제
차단된 계정 상태를 해제합니다. 차단 해제된 계정은 정상적으로 로그인할 수 있습니다.
2단계 인증 초기화
2단계 인증이완료된 계정의 인증 상태를 초기화합니다.
이 기능은 계정의 인증 문제를 해결하거나 새로운 기기에서 인증을 재설정해야 할 때 유용합니다.
주관리자 권한 이관
현재 주관리자 권한을 선택한 계정으로 이관합니다.
이관이 완료되면 선택한 계정이 새로운 주관리자가 되며, 기존 주관리자 계정은 운영 관리자로 전환됩니다.
삭제
계정을 영구적으로 삭제합니다. 삭제 시 해당 계정의 작업 내용은 유지되지만 삭제된 계정은 복구할 수 없습니다.
[주관리자 권한 이관 가이드]
주관리자 권한을 다른 계정으로 이관합니다. 이관이 완료되면 기존 주관리자는 즉시 자동 로그아웃되며, 재로그인 시 '운영 관리자' 권한으로 전환됩니다.
**1. 이관 실행**
* 계정 목록에서 이관할 계정의 관리 도구 아이콘을 클릭한 후 **주관리자 권한 이관**을 선택합니다.
***
**2. 비밀번호 확인**
* 안전한 권한 이관을 위해 현재 로그인된 주관리자 계정의 **비밀번호를 입력 후 확인**을 클릭합니다.
***
**3. 최종 확인**
* **이관 대상 계정 정보를 확인**하고 **동의 항목에 체크**합니다.
* 기존 주관리자 계정 정보: 기존 주관리자 ID / 성명
* 이관 대상 계정 정보: 대상 계정 ID / 성명
* 활성화된 완료 버튼을 클릭하면 이관이 완료됩니다.
***
## **3. 보안**
### **3-1. 비밀번호**
#### **현재 비밀번호**
계정의 비밀번호를 변경할 수 있습니다.
{% hint style="success" %}
새 비밀번호는 영문, 숫자, 특수 문자를 포함해 8\~16자로 설정해야 합니다. 직전 비밀번호는 재사용할 수 없습니다.
{% endhint %}
* 최근 변경 일시가 함께 표시되어 보안 관리에 참고할 수 있습니다.
* 비밀번호 분실 시에는 로그인 화면에서 **\[비밀번호 찾기]**를 통해 비밀번호를 재설정 할 수 있습니다.
#### **비밀번호 변경 주기**
{% hint style="info" %} **주관리자**만 제어할 수 있는 기능입니다.
{% endhint %}
주관리자는 계정 보안 강화를 위해 **비밀번호 변경 주기**를 설정할 수 있습니다. 사용 설정 시 모든 계정에 적용되며, 최근 비밀번호 변경 일시를 기준으로 설정된 주기가 지나면 다음 로그인 시 비밀번호를 변경해야 로그인할 수 있습니다.
* **변경 주기:** 90일 / 180일 / 365일
{% hint style="warning" %}
**설정 해제 시 유의사항**
설정을 해제하면 모든 계정의 비밀번호 변경 주기가 해제되며, 변경 주기 경과 여부와 관계없이 기존 비밀번호로 로그인할 수 있습니다.
{% endhint %}
***
### **3-2. 2단계 인증**
{% hint style="info" %} **주관리자**만 제어할 수 있는 기능입니다.
{% endhint %}
주관리자는 계정 보안 강화를 위한 **2단계 인증(2FA)**을 설정할 수 있습니다. 사용 설정 시 **모든 계정**에 **Google Authenticator 앱 인증을 일괄 요청**합니다. 이후 2단계 인증을 완료한 계정은 로그인 시 인증코드를 입력해야만 로그인 할 수 있습니다.
{% hint style="success" %}
* 보안 강화를 위해 **2단계 인증 사용을 권장**합니다.
* 계정 당 모바일 기기 1대만 인증에 사용할 수 있습니다.
{% endhint %}
#### **2단계 인증 설정 가이드**
**사용 설정하기**
* 주관리자 계정으로 로그인해 주세요.
* 2단계 인증을 활성화 후 \[저장] 버튼을 클릭합니다.
* 이후 노출된 창에서 \[확인] 버튼을 클릭하여 **2단계 인증 사용 설정을 완료**합니다.
**인증 설정 완료하기**
* 재로그인하여 아래 절차에 따라 **2단계 인증 설정을 완료**해 주세요.
{% tabs %}
{% tab title="QR 코드 스캔" %}
1. 모바일 기기에 **Google Authenticator(OTP) 앱** 다운로드
2. 앱 실행 후 **\[+]** 버튼 또는 **\[시작하기]** 버튼 클릭
3. **\[QR 코드 스캔]** 선택 후 화면에 표시된 **QR 코드 스캔**
4. 화면에서 **\[다음]** 버튼 클릭 후, **앱에 표시된 인증코드 6자리 입력**하여 **2단계 인증 설정 완료**
{% endtab %}
{% tab title="설정 키 입력" %}
1. 모바일 기기에 **Google Authenticator(OTP) 앱** 다운로드
2. 앱 실행 후 **\[+]** 버튼 또는 **\[시작하기]** 버튼 클릭
3. **\[설정 키 입력]** 선택 후 **계정 이름(코드명)**과 화면에 표시된 **키 값**을 공백 없이 입력
4. **키 유형**을 **시간 기준**으로 **설정 후 추가**
5. 화면에서 **\[다음]** 버튼 클릭 후, **앱에 표시된 인증코드 6자리 입력**하여 **2단계 인증 설정 완료**
{% endtab %}
{% endtabs %}
{% hint style="success" %}
인증 설정 완료 후 로그인 시, ID와 비밀번호 외에 **Google Authenticator 앱의 일회용 인증코드(OTP)**가 필요합니다. 비밀번호가 유출되더라도 OTP 없이는 접속할 수 없어 보안이 강화됩니다.
{% endhint %}
***
### **3-3. 접속 허용 IP**
{% hint style="info" %} **주관리자**만 제어할 수 있는 기능입니다.
{% endhint %}
**접속 허용 IP**는 등록된 IP 주소 또는 IP 대역대에서만 서비스 접속을 허용하는 보안 기능입니다. 허용 목록에 없는 외부 네트워크의 접근은 전면 차단되므로, 허용된 네트워크 환경에서만 서비스를 사용할 수 있도록 제어할 수 있습니다.
#### **허용 IP 등록** 버튼을 클릭하여 허용 IP를 등록해 주세요. 현재 접속 IP는 우측에서 확인할 수 있으며, 본인 계정의 접근 차단(Self-Lockout) 방지를 위해 설정 저장 시 현재 접속 IP가 허용 목록에 포함되어 있어야 합니다.
{% tabs %}
{% tab title="단일 IP" %}
* **IP 주소:** 특정 IP 주소 하나를 등록합니다. IPv4 형식(예: 192.168.0.1)으로 입력해 주세요.
* **상세 설명:** 해당 IP의 허용 사유 또는 관련 정보를 최대 45자까지 입력할 수 있습니다.
{% endtab %}
{% tab title="IP 대역대" %}
* **IP 대역대:** 시작 IP와 종료 IP를 입력해 범위를 등록합니다. IPv4 형식(예: 192.168.0.1)으로 입력해 주세요.
* 시작/종료 IP를 모두 올바른 형식으로 입력하면 허용되는 총 IP 개수가 표시됩니다.
* **상세 설명:** 해당 IP의 허용 사유 또는 관련 정보를 최대 45자까지 입력할 수 있습니다.
{% hint style="warning" %}
총 1,000개 이상의 IP를 허용하는 범위는 보안에 취약할 수 있으므로 주의해 주세요.
{% endhint %}
{% endtab %}
{% tab title="현재 접속 IP 바로 등록" %}
* 허용 IP 목록 하단 알럿의 **\[바로 등록하기]** 버튼을 클릭하여 현재 사용 중인 네트워크 IP를 빠르게 추가할 수 있습니다.
* 등록된 현재 접속 IP 우측에 라벨이 표시됩니다.
{% hint style="warning" %}
주관리자 계정에 한해, 제한된 네트워크 환경에서 이메일 인증으로 로그인할 수 있습니다. 단, 보안상 이 방법은 권장하지 않으며 불가피한 경우에만 사용해 주세요.
{% endhint %}
{% endtab %}
{% endtabs %}
#### **허용 IP 목록**
등록된 허용 IP를 테이블에서 확인할 수 있습니다.
헤더
설명
IP주소/IP 대역대
등록된 IP 또는 IP 대역 범위입니다.
상세 설명
허용 IP 등록 시 입력된 상세 설명입니다.
등록 일시
허용 IP가 등록된 날짜입니다.
삭제
해당 IP 또는 IP 대역 범위를 영구적으로 삭제합니다.
{% hint style="warning" %}
**설정 해제 시 유의사항**
설정 해제 후 저장하면 등록된 허용 IP 목록은 모두 초기화됩니다. 이 작업은 되돌릴 수 없으므로 주의하세요.
{% endhint %}
# 상품 데이터 수집 API
{% hint style="info" %}
이 가이드는 **젠서 디스커버리와 젤라또 모두에 적용**됩니다.
{% endhint %}
## **상품 데이터 수집 개요**
상품 데이터 수집 API는 파트너사 시스템의 상품 데이터를 실시간으로 수집하는 연동 방식입니다. 상품 등록·수정·삭제 이벤트를 전달하며, 이미 운영 중인 커머스 환경에 따라 적합한 방식을 선택할 수 있습니다.
***
### **상품 데이터 수집 API**
상품 데이터 수집 API는 상품 데이터를 젤라또 플랫폼으로 전송하기 위한 인터페이스입니다.\
상품 등록, 수정, 삭제 이벤트를 실시간으로 수집합니다.
* **문서:** [상품 데이터 수집 API](/developers/product-collection/api)
* **서버 ・ 엔드포인트:** `https://api.gelatto.ai`
메서드
경로
설명
POST
/collector/products
상품 등록
PUT
/collector/products
상품 수정
PUT
/collector/products-delete
상품 삭제
* **인증:** 모든 요청에는 아래 헤더가 필수로 포함되어야 합니다.
헤더명
설명
필수
Content-Type
application/json 고정
O
Api-Key
발급받은 API 키
O
{% hint style="info" %}
API 키는 어드민에서 발급 후 사용할 수 있습니다.
{% endhint %}
***
### **Google Merchant API**
GMC Merchant API 규격의 요청 body를 그대로 전용 엔드포인트로 전송하면 됩니다. 별도의 데이터 변환 없이 GMC API 표준 방식 그대로 사용할 수 있습니다.
* **문서:** [Google Merchant API](/developers/product-collection/google-merchant-api)
{% hint style="info" %}
GMC Merchant API 규격은 [Google 공식 문서](https://developers.google.com/merchant/api/reference/rest/products_v1/accounts.productInputs?_gl=1*uzno6q*_up*MQ..*_ga*MTE4OTkwOTY4NC4xNzcyNzEyNzM0*_ga_SM8HXJ53K2*czE3NzI3MTI3MzQkbzEkZzAkdDE3NzI3MTI3NTckajM3JGwwJGgw#ProductInput)를 참고해 주세요.
{% endhint %}
***
**ⓘ Naver Commerce API**
더 나은 서비스 경험을 제공하기 위해 네이버 커머스 API를 이용한 데이터 연동을 준비 중입니다.\
기능 준비 완료 후 본 가이드 문서도 상세히 업데이트될 예정입니다.
# 요청 파라미터 설명
{% hint style="info" %}
**요청 데이터를 설명합니다. 자세한 API 요청 방식은**[ **상품 수집 API** ](/developers/product-collection/api)**를 참고해 주세요.**\
**상품 수집 API 관련 요청 파라미터 설명입니다. Google Merchant API 는 Google 공식 문서를 참고해 주세요.**
{% endhint %}
## **공통 데이터 구조**
### **다국어 텍스트 필드**
상품명, 브랜드명, 카테고리명 등의 텍스트 필드는 3가지 형식을 지원합니다.
**형식 1. 단순 문자열**
```json
"name": "클래식 티셔츠"
```
**형식 2. 언어 지정 객체**
```json
"name": {
"@value": "클래식 티셔츠",
"@language": "ko"
}
```
**형식 3. 다국어 배열**
지원 언어 코드（ISO 639-1）：`ko`、`en`、`ja`
```json
"name": [
{ "@value": "클래식 티셔츠", "@language": "ko" },
{ "@value": "Classic T-Shirt", "@language": "en" },
{ "@value": "クラシックTシャツ", "@language": "ja" }
]
```
{% hint style="info" %}
언어 지정 객체(형식 2, 3)를 사용하는 경우, `@value`와 `@language`는 모두 필수입니다. `@language`를 생략하면 `400` 에러가 반환됩니다. 모든 언어를 반드시 제공할 필요는 없으며, 필요한 언어만 전송할 수 있습니다.
{% endhint %}
### **데이터 입력 규칙**
* **필수 필드와 null**：필드 사양표에서 필수(O)로 표기된 필드에는 반드시 유효한 값을 포함해야 합니다. API 사양서에 기재된 모든 필드는 `null`을 허용하지 않습니다. 선택(X) 필드는 생략할 수 있지만, `null`은 전송하지 마세요.
* **빈 문자열**：필수 필드에 빈 문자열(`""`)을 전송하면 `400` 에러가 반환됩니다.
* **문자열(string)**：시스템상의 고정 `maxLength` 제약은 없지만, 운영상의 권장 길이에 맞춰 전송해 주세요.
* **숫자(number)**：통화·수량·중량 등 용도에 맞는 일반적인 소수점 정밀도를 사용해 주세요.
* **enum**：허용되는 값이 지정된 필드는 Enum 값 레퍼런스 섹션에 정리되어 있습니다. 명시된 값 이외를 전송하면 `400` 에러가 반환됩니다.
* **필드 간 의존 관계**：특정 필드의 값에 따라 다른 필드의 필수 여부가 변경되는 조건부 필수 규칙은 적용되지 않습니다. 필드 사양표의 필수 여부만을 기준으로 데이터를 구성합니다.
* `@graph` 배열에는 최소 1건, 최대 1,000건의 상품을 포함할 수 있습니다.
* API 명세서에 기재된 모든 필드는 null을 허용하지 않습니다.
**문자열·숫자의 권장 제약값:** 당사 시스템에서는 아래 제약으로 수신·저장됩니다. 설계 시 참고하세요.
이 값은 권장값이며 실제 값에 제한은 없습니다.
필드
타입
제약
sku
string
최대 64자, 반각 영숫자·하이픈·언더스코어
name
string
최대 200자
description.text
string
최대 5,000자
brand.name
string
최대 100자
category.name
string
최대 100자
url / mobileUrl
string
최대 2,048자, http(s) 스킴만 허용
price
number
소수점 이하 4자리까지(JPY/KRW는 정수 권장)
inventoryLevel.value
number
0 이상의 정수
shippingDetails.weight.value
number
소수점 이하 3자리까지
gtin
string
GTIN-8 / 12 / 13 / 14(숫자만)
priceCurrency
string
ISO 4217(예: JPY, KRW, USD)
availabilityStarts / Ends
string
ISO 8601 UTC(끝에 "Z" 필수)
{% hint style="info" %}
Starts와 Ends를 모두 지정하는 경우, Starts < Ends여야 합니다.
{% endhint %}
#### **권장 maxLength**
아래는 운영상의 권장값입니다. 시스템상의 고정 상한은 아니지만, 검색·표시·매칭 품질을 안정시키기 위해 가능한 한 이 범위 내로 전송해 주세요.
대상 필드
권장 maxLength
비고
sku、offers.sku
100
상품·옵션을 고유하게 식별할 수 있는 안정적인 코드
gtin
14
GTIN-8, GTIN-12, GTIN-13, GTIN-14 대응
mpn
100
제조사 품번
name、brand.name、category.name
200
표시명으로 읽기 쉬운 길이
description.text
5000
HTML이 아닌 설명 본문 권장
url、mobileUrl、image.contentUrl
2048
https:// URL 권장
color、size、material
100
옵션·소재명
additionalProperty.propertyID
100
속성을 식별하는 키
#### 권장 숫자 정밀도
| 대상 필드 | 권장 정밀도 | 비고 |
| ---------------------------------- | ------------ | ------------------------------- |
| `price`、`priceSpecification.price` | 통화 기준 | JPY·KRW는 정수, USD는 소수점 이하 2자리 권장 |
| `inventoryLevel.value` | 정수 | 재고 수량 |
| `shippingDetails.weight.value` | 소수점 이하 3자리까지 | kg·g 등의 중량 표현 |
| `additionalProperty.platform_rate` | 소수점 이하 4자리까지 | 예: `0.15` |
| `unit.unit_quantity` | 소수점 이하 3자리까지 | 포장 수량 |
| `unit.weight_quantity` | 소수점 이하 3자리까지 | 중량·용량 값. 숫자 타입으로 전송 |
#### 운영상의 기대 포맷
| 대상 필드 | 기대 포맷 | 비고 |
| ---------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------- |
| `sku`、`offers.sku` | 영숫자, 하이픈, 언더스코어 권장 | 예: `PROD-001-WH-M`. 등록 후 동일 상품의 식별자로 계속 사용해 주세요. |
| `gtin` | 숫자만, 8\~14자리 |
{% hint style="info" %}
`{productInputsName}` 은 다음 [문서 내용](https://developers.google.com/merchant/api/reference/rest/products_v1/accounts.productInputs/patch?_gl=1*5oc6ws*_up*MQ..*_ga*MTg0NTgzMDY3Mi4xNzczNzE1MDgw*_ga_SM8HXJ53K2*czE3NzM3MTUwODAkbzEkZzAkdDE3NzM3MTUwODAkajYwJGwwJGgw#path-parameters)을 참고해 주세요.
{% endhint %}
# 스크립트 가이드
{% content-ref url="/pages/X4fewwTnH4WBatT2TnH2" %}
[젠서 디스커버리 미니](/developers/script-guide/genser-discovery-mini)
{% endcontent-ref %}
# 젠서 디스커버리 미니
## **1. 개요**
* 젠서 디스커버리 미니는 고객사 사이트에 코드 한 줄만 넣으면 자동으로 나타나는 연동 방식입니다.
* 젠서 디스커버리 미니 안에서 사용자가 상품을 클릭해 상세 페이지로 이동하려 할 때, 그 동작을 고객사가 원하는 방식(자체 페이지 이동 로직 등)으로 직접 연결할 수 있도록 "이벤트가 발생하면 자동으로 실행되는 함수(콜백)"를 제공합니다.
***
## **2. 연동 방식**
### 2-1. Quick Start
* 아래 코드 조각(스니펫)을 페이지에 붙여 넣으면, 이 코드가 실제 위젯 프로그램(메인 스크립트)을 자동으로 불러와(로더) 초기화까지 진행합니다.
```html
```
### 2-2. init(config)
* 역할: 이 함수를 호출해야 위젯이 실제로 화면에 나타나고 동작을 시작합니다.
* 함수명: `window.genserDiscovery.init`
* 반환: 실행 결과를 비동기로 알려주는 값(`Promise`)
* 파라미터
| 옵션 | 타입 | 필수 | 설명 |
| ----------- | ------------------ | -- | ----------------------------- |
| vendorId | string | 필수 | 고객사 식별 ID |
| onUrlOpen | function | 권장 | 상품 상세/외부 이동 이벤트 처리 콜백 (3장 참고) |
| environment | 'web' \| 'webview' | - | 실행 환경. 미지정 시 자동 감지 |
| onReady | function | - | UI 렌더링 완료 후 1회 호출 |
| onError | function | - | 초기화/로드 실패 시 에러 객체와 함께 호출 |
### 2-3. 콜백 이름 (alias)
이동 처리 콜백은 아래 이름 중 하나로 지정할 수 있으며, 여러 개를 넣으면 위에서부터 우선 적용됩니다.
```
onOpen > openCallback > onUrlOpen > onProductOpenDetail > onProductDetail > productDetailCallback
```
`onUrlOpen`을 표준으로 사용하는 것을 권장합니다.
### 2-4. environment 자동 감지
`environment`를 지정하지 않으면 SDK가 실행 환경을 자동 감지합니다. 네이티브 WebView(브릿지 존재) 환경이면 `webview`, 그 외에는 `web`으로 동작합니다. 일반 웹 연동 시에는 `environment: 'web'` 명시를 권장합니다.
### 2-5. 위젯 유형 (기본 / 커스텀)
위젯 유형은 어드민에서 설정하며, 두 가지 방식이 있습니다.
* **기본**: 별도 스크립트 작업 없이, SDK가 제공하는 오버레이 트리거를 그대로 사용합니다.
* **커스텀**: SDK가 제공하는 기본 위젯 요소 대신 고객사가 직접 만든 요소(버튼 등)를 트리거로 사용합니다. 이 경우 해당 요소의 클릭 이벤트에 `open()`을, 닫는 동작이 필요한 지점에는 `close()`를 직접 연결해줘야 합니다.
```js
document.querySelector('#my-custom-trigger').addEventListener('click', function () {
window.genserDiscovery.open();
});
document.querySelector('#my-custom-close-button').addEventListener('click', function () {
window.genserDiscovery.close();
});
```
{% hint style="info" %}
위젯 유형을 커스텀으로 설정한 경우, `open()`/`close()`를 연결하지 않으면 오버레이가 열리거나 닫히지 않습니다. `open()`/`close()`의 상세 스펙은 [**\[6. API 레퍼런스\]**](#id-6.-api)를 참고해 주세요.
{% endhint %}
***
## **3. 이벤트 처리 방식**
사용자가 위젯에서 상품을 클릭했을 때, 그 클릭을 우리 사이트가 알아채고 반응하도록 만드는 방법은 두 가지입니다: **콜백 방식**(이벤트가 발생하면 자동 실행되는 함수를 `init()`에 미리 등록하는 `onUrlOpen`)과 **구독 방식**(원하는 이벤트만 따로 등록해서 듣는 `on`/`off`).
{% hint style="info" %}
`product.openDetail` 이벤트가 팝업(모달)을 거쳐 발생할지, 클릭 즉시 발생할지는 어드민의 [**\[부가 옵션 > 상품 카드 > PDP 오픈 방식\]**](https://help.genser.ai/~/changes/356/design/additional-options#id-2-2.-pdp) 설정에 따라 달라집니다.
{% endhint %}
| 이벤트명 | 설명 |
| ------------------ | --------------- |
| product.openDetail | 상품 상세 페이지 이동 요청 |
### 3-1. onUrlOpen (콜백 방식)
```
onUrlOpen(payload, context)
```
{% hint style="warning" %}
**콜백 인자는 payload, context 2개입니다.**\
이벤트 타입이 필요하면 `context.message.type`으로 확인합니다.
{% endhint %}
| 인자 | 설명 |
| ------- | ------------------------------------------------------------------------------------ |
| payload | 클릭된 상품의 정보와 이동할 URL이 담긴 데이터 |
| context | 이 이벤트에 대해 응답(회신)할 수 있는 통로가 되는 객체 (원본 메시지는 `context.message`, 응답 함수는 `context.reply`) |
**payload 필드**
| 필드 | 타입 | 설명 |
| ----------- | -------------- | --------------------------- |
| productSku | string | 상품 SKU |
| pcUrl | string | PC 이동 URL |
| mobileUrl | string \| null | Mobile 이동 URL |
| fallbackUrl | string | 기본 fallback URL |
| source | string | 이벤트 발생 위치 (예: product-card) |
| utmParams | object | (선택) URL 쿼리로 병합할 UTM 파라미터 |
**예시**
```json
{
"productSku": "3370616",
"pcUrl": "https://shop.example.com/product/3370616",
"mobileUrl": null,
"fallbackUrl": "https://shop.example.com/product/3370616",
"source": "product-card"
}
```
**URL 우선순위**
이동 URL은 아래 순서로 선택하는 것을 권장합니다. (SDK 기본 처리도 동일한 순서를 사용합니다.)
| 우선순위 | 필드 |
| ---- | ------------------- |
| 1 | payload.pcUrl |
| 2 | payload.mobileUrl |
| 3 | payload.fallbackUrl |
**권장 예시**
```js
function handleUrlOpen(payload, context) {
var url = payload.pcUrl || payload.mobileUrl || payload.fallbackUrl;
if (!url) {
return { ok: false, reason: 'url_not_found' };
}
window.location.href = url;
return { ok: true, url: url };
}
window.genserDiscovery.init({
vendorId: 'YOUR_VENDOR_ID',
environment: 'web',
onUrlOpen: handleUrlOpen,
});
```
### 3-2. on / off (구독 방식)
`init()`에 콜백을 등록하는 대신, 원하는 이벤트가 발생할 때마다 실행할 동작을 별도로 미리 등록(구독)해둘 수도 있습니다.
```js
window.genserDiscovery.on('product.openDetail', function (payload, context) {
var url = payload.pcUrl || payload.mobileUrl || payload.fallbackUrl;
if (!url) {
context.reply('product.openDetail.result', { ok: false, reason: 'url_not_found' });
return;
}
window.location.href = url;
context.reply('product.openDetail.result', { ok: true, url: url });
});
```
{% hint style="warning" %}
**on()은 반환값이 자동 회신되지 않습니다.**
`on()`으로 구독한 핸들러는 반환값이 자동으로 회신되지 않으므로, 반드시 `context.reply('<이벤트명>.result', { … })`로 직접 결과를 회신해야 합니다. (반면 `init`의 `onUrlOpen`은 반환값이 자동 회신됩니다.([**3-1 참고**](#id-3-1.-onurlopen))
{% endhint %}
**구독 해제**
```js
window.genserDiscovery.off('product.openDetail', handler); // 특정 핸들러만 해제
window.genserDiscovery.off('product.openDetail'); // 해당 타입 전체 해제
```
***
## **4. 로그인 연동 (선택)**
고객사 사이트에서 로그인한 방문자를 젠서에 알려주면, 지난 대화가 회원 계정에 저장되어 기기를 바꿔도 이어집니다. 연동 여부는 선택이며, 연동하지 않아도 채팅·상품검색 등 모든 기능은 그대로 동작합니다.
### 4-1. 동작 방식
젠서 디스커버리는 로그인 화면을 제공하지 않습니다. 로그인은 고객사 사이트에서 처리하고, 젠서는 「지금 이 방문자가 로그인한 사람인지」만 전달받습니다.
이름·이메일 등 계정 정보는 전달받지 않으므로 화면에 표시되지도 않습니다.
쓰는 함수는 2개입니다.
| 함수 | 언제 호출하나 |
| ----------------- | ------------- |
| `login(memberId)` | 방문자가 로그인했을 때 |
| `logout()` | 방문자가 로그아웃했을 때 |
값을 전달할 때와 전달하지 않을 때의 차이입니다.
| 항목 | 전달하지 않을 때 | 전달할 때 |
| -------- | -------------------------------- | ----------------------------------- |
| 지난 대화 | 이 브라우저에서는 보입니다. 다만 기기를 바꾸면 사라집니다 | 회원 계정에 저장됩니다. 기기를 바꿔도 이어집니다 |
| 로그인 전 대화 | — | 넘어오지 않습니다. 비로그인 대화와 계정 대화는 따로 관리됩니다 |
| 화면 표시 | — | 이름은 표시되지 않습니다. 젠서는 이름을 전달받지 않습니다 |
### 4-2. memberId 규칙
`memberId`는 방문자를 구별하는 값입니다. 같은 값이면 같은 사람으로 봅니다.
{% hint style="warning" %}
**계정 정보를 그대로 넣지 말아 주세요.** 이메일·로그인 아이디·이름·전화번호를 넣으면 그 개인정보가 젠서에 저장됩니다. 권장 사항이 아니라 연동 시 반드시 지켜 주셔야 하는 조건입니다.
{% endhint %}
| 항목 | 내용 |
| --------------- | -------------------------------------------------------- |
| 넣을 값 | UUID v4(36자) 또는 고객사 내부 관리번호. 빈 문자열이 아닌 문자열이어야 합니다 |
| 예 | `550e8400-e29b-41d4-a716-446655440000` |
| 넣지 말 것 | 이메일 · 로그인 아이디 · 이름 · 전화번호 등 계정 정보 |
| 같은 사람은 같은 값 | 회원 1명은 언제나 같은 값이어야 합니다. 값이 바뀌면 다른 사람으로 보고 지난 대화가 끊깁니다 |
| 형식 검사 | 하지 않습니다. 빈 문자열이 아닌 문자열이면 그대로 받으므로 위 규칙은 고객사에서 지켜 주셔야 합니다 |
| 다른 값으로 호출할 때 | 다른 사람으로 봅니다. 대화가 섞이지 않습니다 |
| 다른 고객사와 값이 겹칠 때 | 값은 고객사 단위로 관리되어 섞이지 않습니다 |
UUID v4는 `8-4-4-4-12` 자리 16진수를 하이픈으로 이은 36자 형식입니다(RFC 4122).
### 4-3. login(memberId)
로그인 처리가 끝난 시점에 호출합니다.
```js
var ok = window.genserDiscovery.login('550e8400-e29b-41d4-a716-446655440000');
// ok === true 정상
// ok === false 실패
```
호출하면 바로 반영됩니다. 그때부터 대화가 계정에 저장되고, 로그인 전에 하던 대화는 계정으로 넘어오지 않습니다.
SPA·JSP 등 사이트 구성 방식과 관계없이 로그인 처리에서 호출하면 됩니다.
### 4-4. logout()
로그아웃 처리에서 호출합니다.
```js
var ok = window.genserDiscovery.logout();
// ok === true 정상
// ok === false 실패
```
회원 연결이 끊기고 새 비로그인 상태로 시작합니다. 로그인 전에 하던 대화로 돌아가지 않습니다.
{% hint style="warning" %}
**연동 시 `logout()`은 반드시 호출해 주세요.** 오버레이는 고객사 페이지 위에 얹혀 있어, 방문자가 사이트에서 로그아웃해도 그 사실이 젠서에 전달되지 않습니다. `logout()`을 호출하지 않으면 공용 PC·매장 단말에서 다음 사람이 앞사람의 지난 대화를 볼 수 있습니다.
{% endhint %}
### 4-5. 호출 시점과 화면 갱신
`login()`·`logout()`이 상태를 실제로 바꾸면 화면이 갱신되어 home으로 이동합니다. 방문자가 대화 중이었다면 그 화면이 home으로 바뀝니다.
바뀌는 것이 없는 호출은 화면도 그대로입니다.
| 호출 | 반환 | 화면 |
| ----------------------- | ------ | --------- |
| 새 값으로 `login()` | `true` | home으로 이동 |
| 같은 값으로 `login()` 다시 | `true` | 그대로 |
| 로그인 상태에서 `logout()` | `true` | home으로 이동 |
| 이미 로그아웃 상태에서 `logout()` | `true` | 그대로 |
* 호출 시점을 로그인·로그아웃 처리에 맞춰 주세요. 그 외 시점에 호출하면 방문자가 보던 대화가 home으로 바뀝니다.
* 페이지마다 넣어도 됩니다. 이미 같은 값으로 로그인된 상태라면 화면이 바뀌지 않으므로, 공통 스크립트에 `login()`을 두어도 됩니다.
### 4-6. 상태 구분
| 상태 | 어떤 경우 | 젠서가 받는 값 | 지난 대화가 저장되는 곳 |
| --------- | ------------------- | -------- | ------------- |
| 미연동 | 로그인 연동을 하지 않은 사이트 | 없음 | 이 브라우저 |
| 연동 · 비로그인 | 연동했지만 방문자가 로그인 안 함 | 없음 | 이 브라우저 |
| 연동 · 로그인 | `login()`으로 값을 전달받음 | 값 1개 | 회원 계정 |
앞의 두 상태는 젠서가 받는 값이 같습니다. 비로그인 방문자도 이 브라우저의 지난 대화는 볼 수 있습니다.
### 4-7. 연동 전 확인
| 확인할 것 | 지키지 않으면 | 어떻게 |
| ------------------------ | ------------------------------------------------- | ----------------------------------- |
| 로그아웃 처리에 `logout()`을 넣었나 | 로그인 상태가 그대로 남습니다. 공용 PC에서 다음 사람이 앞사람 대화를 볼 수 있습니다 | 로그아웃 처리에 한 줄 추가해 주세요 (4-4 참고) |
| 로그인·로그아웃 처리 시점에만 호출하나 | 화면이 home으로 이동해 방문자가 보던 대화가 사라집니다 | 호출 시점을 확인해 주세요 (4-5 참고) |
| 반환값을 확인하나 | 실패해도(`false`) 모른 채 넘어가 로그인이 반영되지 않습니다 | `true`/`false`를 확인해 실패 시 로그를 남겨 주세요 |
| 계정 정보를 그대로 넣지 않았나 | 개인정보가 젠서에 저장됩니다. 연동 조건에 어긋나고, 형식 검사도 없어 그대로 저장됩니다 | 관리번호나 UUID로 바꿔 주세요 (4-2 참고) |
| 회원 1명에 값 1개를 고정했나 | 매번 다른 사람으로 보여 지난 대화가 매번 사라집니다 | 회원마다 고정값 1개를 저장해 두고 써 주세요 |
***
## **5. 환경별 주의 사항**
### 5-1. SPA
SPA(페이지를 이동해도 새로고침 없이 화면 일부만 바뀌는 방식)에서는 앱 최초 진입 시 1회만 스니펫을 로드하고 `init()`을 호출합니다. 이후 라우팅(페이지 이동) 시에는 `init()`을 반복 호출하지 마세요.
### 5-2. JSP
JSP(페이지를 이동할 때마다 화면이 통째로 새로고침되는 방식)는 페이지 이동 시마다 전체 페이지가 새로고침되므로, 페이지 템플릿에 스니펫과 `init()`을 함께 넣습니다.
```html
```
***
## **6. API 레퍼런스**
`window.genserDiscovery`에서 제공하는 주요 메서드입니다.
메서드
반환
설명
init(config)
Promise
초기화. 옵션은 2장 참고
on(type, handler)
-
이벤트 구독 (3-2 참고)
off(type, handler?)
-
이벤트 구독 해제
open()
-
미니 오버레이 열기. active 상태에서만 동작하며, 열려있는 상태에서 재호출 시 동작 없음
close()
-
미니 오버레이 닫기. 닫혀있는 상태에서 재호출 시 동작 없음
toggle()
-
Discovery 오버레이 열기/닫기 토글
changeLanguage(lang)
boolean
iframe 재로드 없이 앱 언어 변경. 지원 lang 값(ko, en, ja)
login(memberId)
boolean
로그인 상태 전달. 정상 true / 실패 false. memberId는 빈 문자열이 아닌 문자열. 상태가 바뀌면 화면이 갱신되어 home으로 이동 (4장 참고)
logout()
boolean
회원 연결 해제 후 새 비로그인 상태로 시작. 정상 true / 실패 false. 상태가 바뀌면 화면이 갱신되어 home으로 이동 (4장 참고)
`toggle`, `changeLanguage` 등은 메인 스크립트 로드 및 렌더링 완료 이후에 동작합니다.\
`open()`/`close()`는 파라미터와 반환값이 없으며, 위젯 유형(기본/커스텀)과 무관하게 모두 사용할 수 있습니다.
***
## **7. 작성 예시**
코드 작성 예시를 보여줍니다.
```html
```
***
## **8. 유의 사항**
1. 로더 파일명은 `genser-discovery-loader-kr.min.js`를 사용해 주세요.
2. `vendorId`는 고객사 식별 값으로, 임의 변경 시 데이터 집계에 영향을 줄 수 있습니다.
3. SPA 환경에서는 `init()` 중복 호출을 피해 주세요.
4. `on()` 구독 방식을 사용할 경우 반드시 `context.reply(...)`로 결과를 회신해 주세요.
회신하지 않으면 응답 대기 상태로 남을 수 있습니다.
5. `login()`·`logout()`은 로그인·로그아웃 처리 시점에만 호출해 주세요. 상태가 바뀌면 화면이 갱신되어 home으로 이동하고, 이미 같은 상태라면 화면은 바뀌지 않습니다. (4-5 참고)
6. `memberId`에 이메일·아이디 등 계정 정보를 넣지 말아 주세요. 형식을 검사하지 않아 넣은 값이 그대로 저장됩니다. (4-2 참고)
# 앱 임베드 가이드
{% hint style="info" %}
**젠서 디스커버리 전용 기능**입니다.
{% endhint %}
앱 임베드는 고객사 앱 안에 젠서 디스커버리를 WebView 또는 iframe으로 넣는 기능입니다. 임베드된 화면에서는 젠서 헤더가 숨겨지고 상품 상세가 오버레이로 표시됩니다.
고객사가 할 일은 **"앱에서 열렸다"는 신호를 보내는 것**뿐입니다. 헤더 숨김과 상품 상세 오버레이는 **젠서가 자동으로 처리**합니다.
***
## **1. 연동 방식**
"앱에서 열렸다"는 신호를 전달하는 방법입니다. 신호에 쓰는 값(토큰·파라미터)은 **젠서와 협의해 정합니다.**
{% tabs %}
{% tab title="iOS (WKWebView)" %}
WebView의 UserAgent에 협의한 토큰을 추가합니다.
```swift
let config = WKWebViewConfiguration()
// UA 끝에 "앱이름/버전 + 협의 토큰" 형식으로 추가 (GenserApp은 예시)
config.applicationNameForUserAgent = "MyApp/1.0.0 GenserApp"
let webView = WKWebView(frame: .zero, configuration: config)
```
{% endtab %}
{% tab title="Android (WebView)" %}
WebView의 UserAgent에 협의한 토큰을 추가합니다.
```kotlin
val defaultUA = webView.settings.userAgentString
// 중복 추가 방지: 이미 포함돼 있지 않을 때만 추가
if (!defaultUA.contains("GenserApp")) {
webView.settings.userAgentString = "$defaultUA MyApp/1.0.0 GenserApp"
}
```
{% endtab %}
{% tab title="웹앱 / iframe" %}
임베드 URL에 협의한 파라미터를 추가합니다.
```
https://<젠서 디스커버리 주소>?embed=1 // 예시 파라미터, 실제 값은 젠서와 협의
```
{% endtab %}
{% endtabs %}
***
## **2. 적용 화면**
신호가 전달되면 아래처럼 동작합니다. **◇ 자동 적용** 은 genser가 자동으로 처리하는 부분, **◇ 적용 가이드** 는 고객사 앱에서 살짝 구현해 주시면 되는 부분입니다.
{% tabs %}
{% tab title="헤더 숨김 (자동)" %}
고객사(파트너) 앱의 헤더는 **그대로 유지**되고, genser 화면 자체의 헤더만 **자동으로 사라집니다.** 덕분에 로고가 중복되지 않고 genser 화면이 앱에 자연스럽게 이어집니다. 고객사에서 따로 하실 일은 없습니다.
{% endtab %}
{% tab title="상품 상세 오버레이 (구현)" %}
여기 뜨는 상품 상세는 **고객사의 상품 상세 페이지(PDP)** 입니다. 상품을 선택하면 고객사 PDP가 새 화면으로 열리는데, 이때 **전체 화면 전환 대신 오버레이(레이어)로 띄워 주시면** 위 이미지처럼 앱을 벗어나지 않고 매끄럽게 이어집니다.
아래처럼 고객사 PDP를 오버레이로 열도록 구현해 주시면 됩니다.
**iOS** — 모달 시트로 present
```swift
let vc = UIViewController()
let web = WKWebView(frame: vc.view.bounds)
web.load(URLRequest(url: pdpURL)) // 고객사 PDP 주소
vc.view.addSubview(web)
vc.modalPresentationStyle = .pageSheet // 시트로 떠오르는 오버레이
present(vc, animated: true)
```
**Android** — BottomSheet로 표시
```kotlin
val dialog = BottomSheetDialog(context)
val web = WebView(context).apply { loadUrl(pdpUrl) } // 고객사 PDP 주소
dialog.setContentView(web)
dialog.show()
```
**웹앱 / iframe** — 고정 오버레이 레이어
```html
```
{% endtab %}
{% endtabs %}
***
## **3. 진입 버튼 배치**
AI 검색으로 들어가는 버튼은 고객사가 앱에 직접 배치합니다. 아래 두 가지 배치를 권장하니 서비스에 맞는 쪽을 선택해 주세요. 이미지의 **◇ 적용 가이드**는 고객사가 앱에서 설정하는 부분입니다.
{% tabs %}
{% tab title="옵션 A · 별도 버튼" %}
검색창 아래에 별도의 AI 진입 버튼을 배치합니다.
{% endtab %}
{% tab title="옵션 B · 검색창 우측 버튼" %}
검색창 우측에 컴팩트한 AI 버튼을 배치합니다.
{% endtab %}
{% endtabs %}
***
## **자주 묻는 질문**
Q. 네이티브 앱에서만 되나요? 웹앱에서도 되나요?
웹을 렌더하는 환경(WebView 또는 iframe)이면 모두 됩니다. 신호 전달 방식만 환경에 맞게(UA 토큰 또는 URL 파라미터) 선택하면 됩니다.
Q. 일반 웹 브라우저 접속에서도 헤더가 숨겨지나요?
아니요. 협의한 임베드 신호가 있는 경우에만 숨겨집니다. 신호 없는 일반 접속에서는 헤더가 정상 노출됩니다.
Q. 식별 값이 다른 서비스와 겹치지 않나요?
토큰·파라미터 값은 고객사마다 젠서와 협의해 고유하게 정하므로 다른 서비스와 겹치지 않습니다.
Q. 상품 상세가 오버레이로 뜨지 않고 전체 화면으로 떠요.
오버레이는 앱이 상품 상세를 모달 시트(iOS) 또는 BottomSheet(Android)로 열 때 나타납니다. 전체 화면으로 열면 일반 화면 전환으로 표시됩니다.
Q. iframe으로도 임베드할 수 있나요?
가능합니다. 다만 iframe은 크로스도메인 쿠키·스토리지 제약(특히 iOS)이 있어 로그인 세션이 필요한 화면은 별도 검토가 필요합니다. UserAgent를 지정할 수 있는 WebView 방식이 더 안정적입니다.
***
# 사용자 행동 데이터 수집
검색 이후 발생하는 사용자의 다양한 행동(클릭, 장바구니, 구매 등)을 genser로 전송하는 절차를 안내합니다. 수집된 데이터는 AI 모델의 고도화 학습에 사용되며, CVR(전환율) 및 CTR(클릭률) 등 주요 서비스 성과를 측정하고 평가하는 데 활용됩니다.
{% hint style="info" %}
**왜 행동 데이터를 연동해야 하나요?**
genser의 AI는 사용자가 어떤 상품을 클릭하고 구매했는지 학습하여, **검색 결과의 정확도를 높이고 개인화된 상품을 추천**합니다. 특히 **'구매 완료'** 데이터는 AI 학습에 가장 큰 가중치를 가지므로 반드시 연동되어야 합니다.
{% endhint %}
#### **✅ 수집 대상 이벤트 체크리스트**
개발 연동 전, 아래 표를 참고하여 우리 사이트에서 수집할 이벤트를 정의해 주세요.
{% endstep %}
{% step %}
## 연동 결과 확인하기 (Verify) - 추후 제공 예정
API 연동 후 데이터가 정상적으로 쌓이고 있는지 어드민에서 확인할 수 있습니다.
{% endstep %}
{% endstepper %}
# API 레퍼런스
#### genser 이벤트 수집 API 규격
genser의 이벤트 수집 API는 시스템 간 호환성과 명확한 데이터 의미 전달을 위해 글로벌 표준 기술을 기반으로 설계되었습니다. 이벤트의 최상위 전송 규격은 **CNCF의 CloudEvents 1.0을 준수**하여 다양한 클라우드 환경에서의 표준화된 처리를 보장합니다.
또한, 실제 사용자 행동 데이터는 **Schema.org의 Action 모델**을 채택하여 '행위자(Agent)-대상(Object)-목표(Target)'의 문맥을 구조적으로 정의합니다. 이러한 표준화된 설계를 통해 개발자는 예측 가능한 구조로 손쉽게 연동할 수 있으며, 비즈니스 환경에 맞는 데이터의 투명성과 확장성을 확보할 수 있습니다.
**주요 준수 규격:**
* 전송 포맷: CloudEvents 1.0 (이벤트 라우팅 및 메타데이터 식별)
* 데이터 모델: Schema.org Actions (사용자 행동의 구조적 표현)
# 검색 (Search)
검색 관련 사용자 행동 수집 API
## 검색 제출
> 검색 제출 수집 API
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"tags":[{"name":"검색 (Search)","description":"검색 관련 사용자 행동 수집 API"}],"servers":[{"url":"https://api.gelatto.ai","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Api-Key","description":"API 키"}},"schemas":{"ActionsSearchSubmittedEvent":{"title":"검색 제출","description":"사용자가 검색어를 제출하는 행동을 수집합니다","type":"object","required":["time","source","data"],"properties":{"specversion":{"type":"string","description":"스펙 버전","enum":["1.0.0"]},"id":{"type":"string","description":"이벤트 고유 식별자","enum":["EVT-SEARCH-SUBMITTED"]},"type":{"type":"string","description":"이벤트 유형","enum":["search_submitted"]},"time":{"type":"string","description":"ISO 8601 UTC 이벤트 생성시간","format":"date-time"},"source":{"type":"string","description":"이벤트 발생 출처"},"datacontenttype":{"type":"string","description":"데이터 콘텐츠 타입","enum":["application/ld+json"]},"dataschema":{"type":"string","description":"데이터 스키마 경로","enum":["https://api.gelatto.ai/schema/actions/search_submitted.json"]},"data":{"type":"object","description":"이벤트 데이터 객체","required":["agent","query"],"properties":{"@context":{"type":"string","description":"스키마 context","enum":["https://schema.org/"]},"@type":{"type":"string","description":"액션 유형","enum":["SearchAction"]},"agent":{"type":"object","description":"행위자 (Person)","required":["identifier"],"properties":{"@type":{"type":"string","enum":["Person"]},"identifier":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"type":"string","description":"값"}}},"type":"array","description":"행위자 식별자 목록 (userId, memberId, cookieId는 필수로 추가해야 함, 속성의 추가가 필요할 경우 협의)"},"gender":{"type":"string","enum":["Female","Male","https://schema.org/Female","https://schema.org/Male"]},"additionalProperty":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"값"}}},"type":"array","description":"추가 속성"}}},"query":{"type":"string","description":"검색어"},"object":{"type":"object","description":"대상 객체","required":["actionOption"],"properties":{"@type":{"type":"string","enum":["Thing"]},"actionOption":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"값"}}},"type":"array","description":"액션 옵션"}}},"target":{"type":"object","description":"엔드포인트 정보","required":["urlTemplate"],"properties":{"@type":{"type":"string","enum":["EntryPoint"]},"urlTemplate":{"type":"string","description":"URL"}}}}}}}}},"paths":{"/actions/search/submitted":{"post":{"summary":"검색 제출","description":"검색 제출 수집 API","operationId":"collectSearchSubmitted","tags":["검색 (Search)"],"parameters":[{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string","enum":["application/json"]},"description":"콘텐츠 타입"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"멱등성 키 - 클라이언트가 호출 시 전달해야 함 (UUID)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionsSearchSubmittedEvent"}}}},"responses":{"200":{"description":"수집 성공"},"400":{"description":"잘못된 요청"},"503":{"description":"서비스 일시 이용 불가"}}}}}}
```
## 검색 결과 노출
> 검색 결과 수집 API
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"tags":[{"name":"검색 (Search)","description":"검색 관련 사용자 행동 수집 API"}],"servers":[{"url":"https://api.gelatto.ai","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Api-Key","description":"API 키"}},"schemas":{"ActionsSearchResultEvent":{"title":"검색 결과 노출","description":"사용자에게 검색 결과가 노출되는 행동을 수집합니다","type":"object","required":["time","source","data"],"properties":{"specversion":{"type":"string","description":"스펙 버전","enum":["1.0.0"]},"id":{"type":"string","description":"이벤트 고유 식별자","enum":["EVT-VIEW-SEARCH-RESULT"]},"type":{"type":"string","description":"이벤트 유형","enum":["view_search_result"]},"time":{"type":"string","description":"ISO 8601 UTC 이벤트 생성시간","format":"date-time"},"source":{"type":"string","description":"이벤트 발생 출처"},"datacontenttype":{"type":"string","description":"데이터 콘텐츠 타입","enum":["application/ld+json"]},"dataschema":{"type":"string","description":"데이터 스키마 경로","enum":["https://api.gelatto.ai/schema/actions/search_result.json"]},"data":{"type":"object","description":"이벤트 데이터 객체","required":["agent","object"],"properties":{"@context":{"type":"string","description":"스키마 context","enum":["https://schema.org/"]},"@type":{"type":"string","description":"액션 유형","enum":["ViewAction"]},"agent":{"type":"object","description":"행위자 (Person)","required":["identifier"],"properties":{"@type":{"type":"string","enum":["Person"]},"identifier":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"type":"string","description":"값"}}},"type":"array","description":"행위자 식별자 목록 (userId, memberId, cookieId는 필수로 추가해야 함, 속성의 추가가 필요할 경우 협의)"},"gender":{"type":"string","enum":["Female","Male","https://schema.org/Female","https://schema.org/Male"]},"additionalProperty":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"값"}}},"type":"array","description":"추가 속성"}}},"object":{"$ref":"#/components/schemas/ActionsSearchResultItemList"},"target":{"type":"object","description":"엔드포인트 정보","required":["urlTemplate"],"properties":{"@type":{"type":"string","enum":["EntryPoint"]},"urlTemplate":{"type":"string","description":"URL"}}}}}}},"ActionsSearchResultItemList":{"description":"상품 목록 객체","type":"object","required":["numberOfItems","itemListElement"],"properties":{"@type":{"type":"string","enum":["ItemList"]},"numberOfItems":{"type":"number","description":"검색 결과 총 건수"},"itemListElement":{"oneOf":[{"$ref":"#/components/schemas/ActionsSearchResultListItem"},{"type":"array","items":{"$ref":"#/components/schemas/ActionsSearchResultListItem"}}]}}},"ActionsSearchResultListItem":{"description":"상품 목록 항목","type":"object","required":["position","item"],"properties":{"@type":{"type":"string","enum":["ListItem"]},"item":{"$ref":"#/components/schemas/ActionsSearchResultProduct"},"position":{"type":"number","description":"목록 내 노출 순서"}}},"ActionsSearchResultProduct":{"description":"상품 객체","type":"object","required":["sku"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]}}}}},"paths":{"/actions/search/result":{"post":{"summary":"검색 결과 노출","description":"검색 결과 수집 API","operationId":"collectSearchResult","tags":["검색 (Search)"],"parameters":[{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string","enum":["application/json"]},"description":"콘텐츠 타입"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"멱등성 키 - 클라이언트가 호출 시 전달해야 함 (UUID)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionsSearchResultEvent"}}}},"responses":{"200":{"description":"수집 성공"},"400":{"description":"잘못된 요청"},"503":{"description":"서비스 일시 이용 불가"}}}}}}
```
# 상품 (Product)
상품 관련 사용자 행동 수집 API
## 상품 클릭
> 상품 클릭 수집 API
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"tags":[{"name":"상품 (Product)","description":"상품 관련 사용자 행동 수집 API"}],"servers":[{"url":"https://api.gelatto.ai","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Api-Key","description":"API 키"}},"schemas":{"ActionsClickProductEvent":{"title":"상품 클릭","description":"사용자가 상품을 클릭하는 행동을 수집합니다","type":"object","required":["time","source","data"],"properties":{"specversion":{"type":"string","description":"스펙 버전","enum":["1.0.0"]},"id":{"type":"string","description":"이벤트 고유 식별자","enum":["EVT-CLICK-PRODUCT"]},"type":{"type":"string","description":"이벤트 유형","enum":["click_product"]},"time":{"type":"string","description":"ISO 8601 UTC 이벤트 생성시간","format":"date-time"},"source":{"type":"string","description":"이벤트 발생 출처"},"datacontenttype":{"type":"string","description":"데이터 콘텐츠 타입","enum":["application/ld+json"]},"dataschema":{"type":"string","description":"데이터 스키마 경로","enum":["https://api.gelatto.ai/schema/actions/click_product.json"]},"data":{"type":"object","description":"이벤트 데이터 객체","required":["agent","object"],"properties":{"@context":{"type":"string","description":"스키마 context","enum":["https://schema.org/"]},"@type":{"type":"string","description":"액션 유형","enum":["ChooseAction"]},"agent":{"type":"object","description":"행위자 (Person)","required":["identifier"],"properties":{"@type":{"type":"string","enum":["Person"]},"identifier":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"type":"string","description":"값"}}},"type":"array","description":"행위자 식별자 목록 (userId, memberId, cookieId는 필수로 추가해야 함, 속성의 추가가 필요할 경우 협의)"},"gender":{"type":"string","enum":["Female","Male","https://schema.org/Female","https://schema.org/Male"]},"additionalProperty":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"값"}}},"type":"array","description":"추가 속성"}}},"object":{"oneOf":[{"$ref":"#/components/schemas/ActionsClickProductItemList"},{"type":"array","items":{"$ref":"#/components/schemas/ActionsClickProductItemList"}}]},"target":{"type":"object","description":"엔드포인트 정보","required":["urlTemplate"],"properties":{"@type":{"type":"string","enum":["EntryPoint"]},"urlTemplate":{"type":"string","description":"URL"}}}}}}},"ActionsClickProductItemList":{"description":"상품 목록 객체","type":"object","required":["itemListElement"],"properties":{"@type":{"type":"string","enum":["ItemList"]},"itemListElement":{"$ref":"#/components/schemas/ActionsClickProductListItem"}}},"ActionsClickProductListItem":{"description":"상품 목록 항목","type":"object","required":["position","item"],"properties":{"@type":{"type":"string","enum":["ListItem"]},"item":{"$ref":"#/components/schemas/ActionsClickProductProduct"},"position":{"type":"number","description":"목록 내 노출 순서"}}},"ActionsClickProductProduct":{"description":"상품 객체","type":"object","required":["sku"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]}}}}},"paths":{"/actions/click/product":{"post":{"summary":"상품 클릭","description":"상품 클릭 수집 API","operationId":"collectClickProduct","tags":["상품 (Product)"],"parameters":[{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string","enum":["application/json"]},"description":"콘텐츠 타입"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"멱등성 키 - 클라이언트가 호출 시 전달해야 함 (UUID)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionsClickProductEvent"}}}},"responses":{"200":{"description":"수집 성공"},"400":{"description":"잘못된 요청"},"503":{"description":"서비스 일시 이용 불가"}}}}}}
```
# 조회 (View)
상품 조회 관련 사용자 행동 수집 API
## 상품 상세조회
> 상품 상세조회 수집 API
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"tags":[{"name":"조회 (View)","description":"상품 조회 관련 사용자 행동 수집 API"}],"servers":[{"url":"https://api.gelatto.ai","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Api-Key","description":"API 키"}},"schemas":{"ActionsViewProductEvent":{"title":"상품 상세조회","description":"사용자가 상품 상세 페이지에 진입하는 행동을 수집합니다","type":"object","required":["time","source","data"],"properties":{"specversion":{"type":"string","description":"스펙 버전","enum":["1.0.0"]},"id":{"type":"string","description":"이벤트 고유 식별자","enum":["EVT-VIEW-PRODUCT"]},"type":{"type":"string","description":"이벤트 유형","enum":["view_product"]},"time":{"type":"string","description":"ISO 8601 UTC 이벤트 생성시간","format":"date-time"},"source":{"type":"string","description":"이벤트 발생 출처"},"datacontenttype":{"type":"string","description":"데이터 콘텐츠 타입","enum":["application/ld+json"]},"dataschema":{"type":"string","description":"데이터 스키마 경로","enum":["https://api.gelatto.ai/schema/actions/view_product.json"]},"data":{"type":"object","description":"이벤트 데이터 객체","required":["agent","object"],"properties":{"@context":{"type":"string","description":"스키마 context","enum":["https://schema.org/"]},"@type":{"type":"string","description":"액션 유형","enum":["ViewAction"]},"agent":{"type":"object","description":"행위자 (Person)","required":["identifier"],"properties":{"@type":{"type":"string","enum":["Person"]},"identifier":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"type":"string","description":"값"}}},"type":"array","description":"행위자 식별자 목록 (userId, memberId, cookieId는 필수로 추가해야 함, 속성의 추가가 필요할 경우 협의)"},"gender":{"type":"string","enum":["Female","Male","https://schema.org/Female","https://schema.org/Male"]},"additionalProperty":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"값"}}},"type":"array","description":"추가 속성"}}},"object":{"$ref":"#/components/schemas/ActionsViewProductProduct"},"target":{"type":"object","description":"엔드포인트 정보","required":["urlTemplate"],"properties":{"@type":{"type":"string","enum":["EntryPoint"]},"urlTemplate":{"type":"string","description":"URL"}}}}}}},"ActionsViewProductProduct":{"description":"상품 객체","type":"object","required":["sku"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]}}}}},"paths":{"/actions/view/product":{"post":{"summary":"상품 상세조회","description":"상품 상세조회 수집 API","operationId":"collectViewProduct","tags":["조회 (View)"],"parameters":[{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string","enum":["application/json"]},"description":"콘텐츠 타입"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"멱등성 키 - 클라이언트가 호출 시 전달해야 함 (UUID)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionsViewProductEvent"}}}},"responses":{"200":{"description":"수집 성공"},"400":{"description":"잘못된 요청"},"503":{"description":"서비스 일시 이용 불가"}}}}}}
```
# 장바구니 (Cart)
장바구니 관련 사용자 행동 수집 API
## 장바구니 추가
> 장바구니 추가 수집 API
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"tags":[{"name":"장바구니 (Cart)","description":"장바구니 관련 사용자 행동 수집 API"}],"servers":[{"url":"https://api.gelatto.ai","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Api-Key","description":"API 키"}},"schemas":{"ActionsCartAddEvent":{"title":"장바구니 추가","description":"사용자가 상품을 장바구니에 추가하는 행동을 수집합니다","type":"object","required":["time","source","data"],"properties":{"specversion":{"type":"string","description":"스펙 버전","enum":["1.0.0"]},"id":{"type":"string","description":"이벤트 고유 식별자","enum":["EVT-ADD-TO-CART"]},"type":{"type":"string","description":"이벤트 유형","enum":["add_to_cart"]},"time":{"type":"string","description":"ISO 8601 UTC 이벤트 생성시간","format":"date-time"},"source":{"type":"string","description":"이벤트 발생 출처"},"datacontenttype":{"type":"string","description":"데이터 콘텐츠 타입","enum":["application/ld+json"]},"dataschema":{"type":"string","description":"데이터 스키마 경로","enum":["https://api.gelatto.ai/schema/actions/cart_add.json"]},"data":{"type":"object","description":"이벤트 데이터 객체","required":["agent","object"],"properties":{"@context":{"type":"string","description":"스키마 context","enum":["https://schema.org/"]},"@type":{"type":"string","description":"액션 유형","enum":["AddAction"]},"agent":{"type":"object","description":"행위자 (Person)","required":["identifier"],"properties":{"@type":{"type":"string","enum":["Person"]},"identifier":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"type":"string","description":"값"}}},"type":"array","description":"행위자 식별자 목록 (userId, memberId, cookieId는 필수로 추가해야 함, 속성의 추가가 필요할 경우 협의)"},"gender":{"type":"string","enum":["Female","Male","https://schema.org/Female","https://schema.org/Male"]},"additionalProperty":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"값"}}},"type":"array","description":"추가 속성"}}},"object":{"oneOf":[{"$ref":"#/components/schemas/ActionsCartAddOrderItem"},{"type":"array","items":{"$ref":"#/components/schemas/ActionsCartAddOrderItem"}}]},"target":{"type":"object","description":"엔드포인트 정보","required":["urlTemplate"],"properties":{"@type":{"type":"string","enum":["EntryPoint"]},"urlTemplate":{"type":"string","description":"URL"}}}}}}},"ActionsCartAddOrderItem":{"description":"구매정보","type":"object","required":["orderedItem","orderQuantity"],"properties":{"@type":{"type":"string","enum":["OrderItem"]},"orderedItem":{"$ref":"#/components/schemas/ActionsCartAddProduct"},"orderQuantity":{"type":"number","description":"수량"}}},"ActionsCartAddProduct":{"description":"상품 객체","type":"object","required":["sku","name","offers"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]},"offers":{"$ref":"#/components/schemas/ActionsCartAddOffer"}}},"ActionsCartAddOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}},"paths":{"/actions/cart/add":{"post":{"summary":"장바구니 추가","description":"장바구니 추가 수집 API","operationId":"collectCartAdd","tags":["장바구니 (Cart)"],"parameters":[{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string","enum":["application/json"]},"description":"콘텐츠 타입"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"멱등성 키 - 클라이언트가 호출 시 전달해야 함 (UUID)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionsCartAddEvent"}}}},"responses":{"200":{"description":"수집 성공"},"400":{"description":"잘못된 요청"},"503":{"description":"서비스 일시 이용 불가"}}}}}}
```
## 장바구니 제거
> 장바구니 제거 수집 API
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"tags":[{"name":"장바구니 (Cart)","description":"장바구니 관련 사용자 행동 수집 API"}],"servers":[{"url":"https://api.gelatto.ai","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Api-Key","description":"API 키"}},"schemas":{"ActionsCartRemoveEvent":{"title":"장바구니 제거","description":"사용자가 상품을 장바구니에서 제거하는 행동을 수집합니다","type":"object","required":["time","source","data"],"properties":{"specversion":{"type":"string","description":"스펙 버전","enum":["1.0.0"]},"id":{"type":"string","description":"이벤트 고유 식별자","enum":["EVT-REMOVE-FROM-CART"]},"type":{"type":"string","description":"이벤트 유형","enum":["remove_from_cart"]},"time":{"type":"string","description":"ISO 8601 UTC 이벤트 생성시간","format":"date-time"},"source":{"type":"string","description":"이벤트 발생 출처"},"datacontenttype":{"type":"string","description":"데이터 콘텐츠 타입","enum":["application/ld+json"]},"dataschema":{"type":"string","description":"데이터 스키마 경로","enum":["https://api.gelatto.ai/schema/actions/cart_remove.json"]},"data":{"type":"object","description":"이벤트 데이터 객체","required":["agent","object"],"properties":{"@context":{"type":"string","description":"스키마 context","enum":["https://schema.org/"]},"@type":{"type":"string","description":"액션 유형","enum":["DeleteAction"]},"agent":{"type":"object","description":"행위자 (Person)","required":["identifier"],"properties":{"@type":{"type":"string","enum":["Person"]},"identifier":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"type":"string","description":"값"}}},"type":"array","description":"행위자 식별자 목록 (userId, memberId, cookieId는 필수로 추가해야 함, 속성의 추가가 필요할 경우 협의)"},"gender":{"type":"string","enum":["Female","Male","https://schema.org/Female","https://schema.org/Male"]},"additionalProperty":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"값"}}},"type":"array","description":"추가 속성"}}},"object":{"oneOf":[{"$ref":"#/components/schemas/ActionsCartRemoveOrderItem"},{"type":"array","items":{"$ref":"#/components/schemas/ActionsCartRemoveOrderItem"}}]},"target":{"type":"object","description":"엔드포인트 정보","required":["urlTemplate"],"properties":{"@type":{"type":"string","enum":["EntryPoint"]},"urlTemplate":{"type":"string","description":"URL"}}}}}}},"ActionsCartRemoveOrderItem":{"description":"구매정보","type":"object","required":["orderedItem","orderQuantity"],"properties":{"@type":{"type":"string","enum":["OrderItem"]},"orderedItem":{"$ref":"#/components/schemas/ActionsCartRemoveProduct"},"orderQuantity":{"type":"number","description":"수량"}}},"ActionsCartRemoveProduct":{"description":"상품 객체","type":"object","required":["sku","name","offers"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]},"offers":{"$ref":"#/components/schemas/ActionsCartRemoveOffer"}}},"ActionsCartRemoveOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}},"paths":{"/actions/cart/remove":{"post":{"summary":"장바구니 제거","description":"장바구니 제거 수집 API","operationId":"collectCartRemove","tags":["장바구니 (Cart)"],"parameters":[{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string","enum":["application/json"]},"description":"콘텐츠 타입"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"멱등성 키 - 클라이언트가 호출 시 전달해야 함 (UUID)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionsCartRemoveEvent"}}}},"responses":{"200":{"description":"수집 성공"},"400":{"description":"잘못된 요청"},"503":{"description":"서비스 일시 이용 불가"}}}}}}
```
# 위시리스트 (Wishlist)
위시리스트 관련 사용자 행동 수집 API
## 위시리스트 등록
> 위시리스트 등록 수집 API
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"tags":[{"name":"위시리스트 (Wishlist)","description":"위시리스트 관련 사용자 행동 수집 API"}],"servers":[{"url":"https://api.gelatto.ai","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Api-Key","description":"API 키"}},"schemas":{"ActionsWishlistAddEvent":{"title":"위시리스트 등록","description":"사용자가 상품을 위시리스트에 등록하는 행동을 수집합니다","type":"object","required":["time","source","data"],"properties":{"specversion":{"type":"string","description":"스펙 버전","enum":["1.0.0"]},"id":{"type":"string","description":"이벤트 고유 식별자","enum":["EVT-ADD-TO-WISHLIST"]},"type":{"type":"string","description":"이벤트 유형","enum":["add_to_wishlist"]},"time":{"type":"string","description":"ISO 8601 UTC 이벤트 생성시간","format":"date-time"},"source":{"type":"string","description":"이벤트 발생 출처"},"datacontenttype":{"type":"string","description":"데이터 콘텐츠 타입","enum":["application/ld+json"]},"dataschema":{"type":"string","description":"데이터 스키마 경로","enum":["https://api.gelatto.ai/schema/actions/wishlist_add.json"]},"data":{"type":"object","description":"이벤트 데이터 객체","required":["agent","object"],"properties":{"@context":{"type":"string","description":"스키마 context","enum":["https://schema.org/"]},"@type":{"type":"string","description":"액션 유형","enum":["AddAction"]},"agent":{"type":"object","description":"행위자 (Person)","required":["identifier"],"properties":{"@type":{"type":"string","enum":["Person"]},"identifier":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"type":"string","description":"값"}}},"type":"array","description":"행위자 식별자 목록 (userId, memberId, cookieId는 필수로 추가해야 함, 속성의 추가가 필요할 경우 협의)"},"gender":{"type":"string","enum":["Female","Male","https://schema.org/Female","https://schema.org/Male"]},"additionalProperty":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"값"}}},"type":"array","description":"추가 속성"}}},"object":{"oneOf":[{"$ref":"#/components/schemas/ActionsWishlistAddOrderItem"},{"type":"array","items":{"$ref":"#/components/schemas/ActionsWishlistAddOrderItem"}}]},"target":{"type":"object","description":"엔드포인트 정보","required":["urlTemplate"],"properties":{"@type":{"type":"string","enum":["EntryPoint"]},"urlTemplate":{"type":"string","description":"URL"}}}}}}},"ActionsWishlistAddOrderItem":{"description":"구매정보","type":"object","required":["orderedItem"],"properties":{"@type":{"type":"string","enum":["OrderItem"]},"orderedItem":{"$ref":"#/components/schemas/ActionsWishlistAddProduct"}}},"ActionsWishlistAddProduct":{"description":"상품 객체","type":"object","required":["sku","name"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]},"offers":{"$ref":"#/components/schemas/ActionsWishlistAddOffer"}}},"ActionsWishlistAddOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}},"paths":{"/actions/wishlist/add":{"post":{"summary":"위시리스트 등록","description":"위시리스트 등록 수집 API","operationId":"collectWishlistAdd","tags":["위시리스트 (Wishlist)"],"parameters":[{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string","enum":["application/json"]},"description":"콘텐츠 타입"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"멱등성 키 - 클라이언트가 호출 시 전달해야 함 (UUID)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionsWishlistAddEvent"}}}},"responses":{"200":{"description":"수집 성공"},"400":{"description":"잘못된 요청"},"503":{"description":"서비스 일시 이용 불가"}}}}}}
```
## 위시리스트 제거
> 위시리스트 제거 수집 API
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"tags":[{"name":"위시리스트 (Wishlist)","description":"위시리스트 관련 사용자 행동 수집 API"}],"servers":[{"url":"https://api.gelatto.ai","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Api-Key","description":"API 키"}},"schemas":{"ActionsWishlistRemoveEvent":{"title":"위시리스트 제거","description":"사용자가 상품을 위시리스트에서 제거하는 행동을 수집합니다","type":"object","required":["time","source","data"],"properties":{"specversion":{"type":"string","description":"스펙 버전","enum":["1.0.0"]},"id":{"type":"string","description":"이벤트 고유 식별자","enum":["EVT-REMOVE-FROM-WISHLIST"]},"type":{"type":"string","description":"이벤트 유형","enum":["remove_from_wishlist"]},"time":{"type":"string","description":"ISO 8601 UTC 이벤트 생성시간","format":"date-time"},"source":{"type":"string","description":"이벤트 발생 출처"},"datacontenttype":{"type":"string","description":"데이터 콘텐츠 타입","enum":["application/ld+json"]},"dataschema":{"type":"string","description":"데이터 스키마 경로","enum":["https://api.gelatto.ai/schema/actions/wishlist_remove.json"]},"data":{"type":"object","description":"이벤트 데이터 객체","required":["agent","object"],"properties":{"@context":{"type":"string","description":"스키마 context","enum":["https://schema.org/"]},"@type":{"type":"string","description":"액션 유형","enum":["DeleteAction"]},"agent":{"type":"object","description":"행위자 (Person)","required":["identifier"],"properties":{"@type":{"type":"string","enum":["Person"]},"identifier":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"type":"string","description":"값"}}},"type":"array","description":"행위자 식별자 목록 (userId, memberId, cookieId는 필수로 추가해야 함, 속성의 추가가 필요할 경우 협의)"},"gender":{"type":"string","enum":["Female","Male","https://schema.org/Female","https://schema.org/Male"]},"additionalProperty":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"값"}}},"type":"array","description":"추가 속성"}}},"object":{"oneOf":[{"$ref":"#/components/schemas/ActionsWishlistRemoveOrderItem"},{"type":"array","items":{"$ref":"#/components/schemas/ActionsWishlistRemoveOrderItem"}}]},"target":{"type":"object","description":"엔드포인트 정보","required":["urlTemplate"],"properties":{"@type":{"type":"string","enum":["EntryPoint"]},"urlTemplate":{"type":"string","description":"URL"}}}}}}},"ActionsWishlistRemoveOrderItem":{"description":"구매정보","type":"object","required":["orderedItem"],"properties":{"@type":{"type":"string","enum":["OrderItem"]},"orderedItem":{"$ref":"#/components/schemas/ActionsWishlistRemoveProduct"}}},"ActionsWishlistRemoveProduct":{"description":"상품 객체","type":"object","required":["sku","name"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]},"offers":{"$ref":"#/components/schemas/ActionsWishlistRemoveOffer"}}},"ActionsWishlistRemoveOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}},"paths":{"/actions/wishlist/remove":{"post":{"summary":"위시리스트 제거","description":"위시리스트 제거 수집 API","operationId":"collectWishlistRemove","tags":["위시리스트 (Wishlist)"],"parameters":[{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string","enum":["application/json"]},"description":"콘텐츠 타입"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"멱등성 키 - 클라이언트가 호출 시 전달해야 함 (UUID)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionsWishlistRemoveEvent"}}}},"responses":{"200":{"description":"수집 성공"},"400":{"description":"잘못된 요청"},"503":{"description":"서비스 일시 이용 불가"}}}}}}
```
# 결제 (Purchase)
결제 관련 사용자 행동 수집 API
## 결제 시작
> 결제시작 수집 API
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"tags":[{"name":"결제 (Purchase)","description":"결제 관련 사용자 행동 수집 API"}],"servers":[{"url":"https://api.gelatto.ai","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Api-Key","description":"API 키"}},"schemas":{"ActionsPurchaseCheckoutEvent":{"title":"결제 시작","description":"사용자가 결제를 시작하는 행동을 수집합니다","type":"object","required":["time","source","data"],"properties":{"specversion":{"type":"string","description":"스펙 버전","enum":["1.0.0"]},"id":{"type":"string","description":"이벤트 고유 식별자","enum":["EVT-START-CHECKOUT"]},"type":{"type":"string","description":"이벤트 유형","enum":["start_checkout"]},"time":{"type":"string","description":"ISO 8601 UTC 이벤트 생성시간","format":"date-time"},"source":{"type":"string","description":"이벤트 발생 출처"},"datacontenttype":{"type":"string","description":"데이터 콘텐츠 타입","enum":["application/ld+json"]},"dataschema":{"type":"string","description":"데이터 스키마 경로","enum":["https://api.gelatto.ai/schema/actions/purchase_checkout.json"]},"data":{"type":"object","description":"이벤트 데이터 객체","required":["agent","object"],"properties":{"@context":{"type":"string","description":"스키마 context","enum":["https://schema.org/"]},"@type":{"type":"string","description":"액션 유형","enum":["CheckoutAction"]},"agent":{"type":"object","description":"행위자 (Person)","required":["identifier"],"properties":{"@type":{"type":"string","enum":["Person"]},"identifier":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"type":"string","description":"값"}}},"type":"array","description":"행위자 식별자 목록 (userId, memberId, cookieId는 필수로 추가해야 함, 속성의 추가가 필요할 경우 협의)"},"gender":{"type":"string","enum":["Female","Male","https://schema.org/Female","https://schema.org/Male"]},"additionalProperty":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"값"}}},"type":"array","description":"추가 속성"}}},"object":{"oneOf":[{"$ref":"#/components/schemas/ActionsPurchaseCheckoutOrderItem"},{"type":"array","items":{"$ref":"#/components/schemas/ActionsPurchaseCheckoutOrderItem"}}]},"target":{"type":"object","description":"엔드포인트 정보","required":["urlTemplate"],"properties":{"@type":{"type":"string","enum":["EntryPoint"]},"urlTemplate":{"type":"string","description":"URL"}}}}}}},"ActionsPurchaseCheckoutOrderItem":{"description":"구매정보","type":"object","required":["orderedItem","orderQuantity"],"properties":{"@type":{"type":"string","enum":["OrderItem"]},"orderedItem":{"$ref":"#/components/schemas/ActionsPurchaseCheckoutProduct"},"orderQuantity":{"type":"number","description":"수량"}}},"ActionsPurchaseCheckoutProduct":{"description":"상품 객체","type":"object","required":["sku","name","offers"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]},"offers":{"$ref":"#/components/schemas/ActionsPurchaseCheckoutOffer"}}},"ActionsPurchaseCheckoutOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}},"paths":{"/actions/purchase/checkout":{"post":{"summary":"결제 시작","description":"결제시작 수집 API","operationId":"collectPurchaseCheckout","tags":["결제 (Purchase)"],"parameters":[{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string","enum":["application/json"]},"description":"콘텐츠 타입"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"멱등성 키 - 클라이언트가 호출 시 전달해야 함 (UUID)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionsPurchaseCheckoutEvent"}}}},"responses":{"200":{"description":"수집 성공"},"400":{"description":"잘못된 요청"},"503":{"description":"서비스 일시 이용 불가"}}}}}}
```
## 결제 완료
> 결제완료 수집 API
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"tags":[{"name":"결제 (Purchase)","description":"결제 관련 사용자 행동 수집 API"}],"servers":[{"url":"https://api.gelatto.ai","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Api-Key","description":"API 키"}},"schemas":{"ActionsPurchaseCompleteEvent":{"title":"결제 완료","description":"사용자가 결제를 완료하는 행동을 수집합니다","type":"object","required":["time","source","data"],"properties":{"specversion":{"type":"string","description":"스펙 버전","enum":["1.0.0"]},"id":{"type":"string","description":"이벤트 고유 식별자","enum":["EVT-COMPLETE-PURCHASE"]},"type":{"type":"string","description":"이벤트 유형","enum":["complete_purchase"]},"time":{"type":"string","description":"ISO 8601 UTC 이벤트 생성시간","format":"date-time"},"source":{"type":"string","description":"이벤트 발생 출처"},"datacontenttype":{"type":"string","description":"데이터 콘텐츠 타입","enum":["application/ld+json"]},"dataschema":{"type":"string","description":"데이터 스키마 경로","enum":["https://api.gelatto.ai/schema/actions/purchase_complete.json"]},"data":{"type":"object","description":"이벤트 데이터 객체","required":["agent","object"],"properties":{"@context":{"type":"string","description":"스키마 context","enum":["https://schema.org/"]},"@type":{"type":"string","description":"액션 유형","enum":["OrderAction"]},"agent":{"type":"object","description":"행위자 (Person)","required":["identifier"],"properties":{"@type":{"type":"string","enum":["Person"]},"identifier":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"type":"string","description":"값"}}},"type":"array","description":"행위자 식별자 목록 (userId, memberId, cookieId는 필수로 추가해야 함, 속성의 추가가 필요할 경우 협의)"},"gender":{"type":"string","enum":["Female","Male","https://schema.org/Female","https://schema.org/Male"]},"additionalProperty":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"값"}}},"type":"array","description":"추가 속성"}}},"object":{"oneOf":[{"$ref":"#/components/schemas/ActionsPurchaseCompleteOrderItem"},{"type":"array","items":{"$ref":"#/components/schemas/ActionsPurchaseCompleteOrderItem"}}]},"target":{"type":"object","description":"엔드포인트 정보","required":["urlTemplate"],"properties":{"@type":{"type":"string","enum":["EntryPoint"]},"urlTemplate":{"type":"string","description":"URL"}}}}}}},"ActionsPurchaseCompleteOrderItem":{"description":"구매정보","type":"object","required":["orderedItem","orderQuantity"],"properties":{"@type":{"type":"string","enum":["OrderItem"]},"orderedItem":{"$ref":"#/components/schemas/ActionsPurchaseCompleteProduct"},"orderQuantity":{"type":"number","description":"수량"}}},"ActionsPurchaseCompleteProduct":{"description":"상품 객체","type":"object","required":["sku","name","offers"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]},"offers":{"$ref":"#/components/schemas/ActionsPurchaseCompleteOffer"}}},"ActionsPurchaseCompleteOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}},"paths":{"/actions/purchase/complete":{"post":{"summary":"결제 완료","description":"결제완료 수집 API","operationId":"collectPurchaseComplete","tags":["결제 (Purchase)"],"parameters":[{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string","enum":["application/json"]},"description":"콘텐츠 타입"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"멱등성 키 - 클라이언트가 호출 시 전달해야 함 (UUID)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionsPurchaseCompleteEvent"}}}},"responses":{"200":{"description":"수집 성공"},"400":{"description":"잘못된 요청"},"503":{"description":"서비스 일시 이용 불가"}}}}}}
```
## 결제 취소
> 결제취소 수집 API
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"tags":[{"name":"결제 (Purchase)","description":"결제 관련 사용자 행동 수집 API"}],"servers":[{"url":"https://api.gelatto.ai","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Api-Key","description":"API 키"}},"schemas":{"ActionsPurchaseCancelEvent":{"title":"결제 취소","description":"사용자가 결제를 취소하는 행동을 수집합니다","type":"object","required":["time","source","data"],"properties":{"specversion":{"type":"string","description":"스펙 버전","enum":["1.0.0"]},"id":{"type":"string","description":"이벤트 고유 식별자","enum":["EVT-CANCEL-PURCHASE"]},"type":{"type":"string","description":"이벤트 유형","enum":["cancel_purchase"]},"time":{"type":"string","description":"ISO 8601 UTC 이벤트 생성시간","format":"date-time"},"source":{"type":"string","description":"이벤트 발생 출처"},"datacontenttype":{"type":"string","description":"데이터 콘텐츠 타입","enum":["application/ld+json"]},"dataschema":{"type":"string","description":"데이터 스키마 경로","enum":["https://api.gelatto.ai/schema/actions/purchase_cancel.json"]},"data":{"type":"object","description":"이벤트 데이터 객체","required":["agent","object"],"properties":{"@context":{"type":"string","description":"스키마 context","enum":["https://schema.org/"]},"@type":{"type":"string","description":"액션 유형","enum":["CancelAction"]},"agent":{"type":"object","description":"행위자 (Person)","required":["identifier"],"properties":{"@type":{"type":"string","enum":["Person"]},"identifier":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"type":"string","description":"값"}}},"type":"array","description":"행위자 식별자 목록 (userId, memberId, cookieId는 필수로 추가해야 함, 속성의 추가가 필요할 경우 협의)"},"gender":{"type":"string","enum":["Female","Male","https://schema.org/Female","https://schema.org/Male"]},"additionalProperty":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"값"}}},"type":"array","description":"추가 속성"}}},"object":{"oneOf":[{"$ref":"#/components/schemas/ActionsPurchaseCancelOrderItem"},{"type":"array","items":{"$ref":"#/components/schemas/ActionsPurchaseCancelOrderItem"}}]},"target":{"type":"object","description":"엔드포인트 정보","required":["urlTemplate"],"properties":{"@type":{"type":"string","enum":["EntryPoint"]},"urlTemplate":{"type":"string","description":"URL"}}}}}}},"ActionsPurchaseCancelOrderItem":{"description":"구매정보","type":"object","required":["orderedItem","orderQuantity"],"properties":{"@type":{"type":"string","enum":["OrderItem"]},"orderedItem":{"$ref":"#/components/schemas/ActionsPurchaseCancelProduct"},"orderQuantity":{"type":"number","description":"수량"}}},"ActionsPurchaseCancelProduct":{"description":"상품 객체","type":"object","required":["sku","name","offers"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]},"offers":{"$ref":"#/components/schemas/ActionsPurchaseCancelOffer"}}},"ActionsPurchaseCancelOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}},"paths":{"/actions/purchase/cancel":{"post":{"summary":"결제 취소","description":"결제취소 수집 API","operationId":"collectPurchaseCancel","tags":["결제 (Purchase)"],"parameters":[{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string","enum":["application/json"]},"description":"콘텐츠 타입"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"멱등성 키 - 클라이언트가 호출 시 전달해야 함 (UUID)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionsPurchaseCancelEvent"}}}},"responses":{"200":{"description":"수집 성공"},"400":{"description":"잘못된 요청"},"503":{"description":"서비스 일시 이용 불가"}}}}}}
```
# Models
## The ActionsCartAddEvent object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsCartAddEvent":{"title":"장바구니 추가","description":"사용자가 상품을 장바구니에 추가하는 행동을 수집합니다","type":"object","required":["time","source","data"],"properties":{"specversion":{"type":"string","description":"스펙 버전","enum":["1.0.0"]},"id":{"type":"string","description":"이벤트 고유 식별자","enum":["EVT-ADD-TO-CART"]},"type":{"type":"string","description":"이벤트 유형","enum":["add_to_cart"]},"time":{"type":"string","description":"ISO 8601 UTC 이벤트 생성시간","format":"date-time"},"source":{"type":"string","description":"이벤트 발생 출처"},"datacontenttype":{"type":"string","description":"데이터 콘텐츠 타입","enum":["application/ld+json"]},"dataschema":{"type":"string","description":"데이터 스키마 경로","enum":["https://api.gelatto.ai/schema/actions/cart_add.json"]},"data":{"type":"object","description":"이벤트 데이터 객체","required":["agent","object"],"properties":{"@context":{"type":"string","description":"스키마 context","enum":["https://schema.org/"]},"@type":{"type":"string","description":"액션 유형","enum":["AddAction"]},"agent":{"type":"object","description":"행위자 (Person)","required":["identifier"],"properties":{"@type":{"type":"string","enum":["Person"]},"identifier":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"type":"string","description":"값"}}},"type":"array","description":"행위자 식별자 목록 (userId, memberId, cookieId는 필수로 추가해야 함, 속성의 추가가 필요할 경우 협의)"},"gender":{"type":"string","enum":["Female","Male","https://schema.org/Female","https://schema.org/Male"]},"additionalProperty":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"값"}}},"type":"array","description":"추가 속성"}}},"object":{"oneOf":[{"$ref":"#/components/schemas/ActionsCartAddOrderItem"},{"type":"array","items":{"$ref":"#/components/schemas/ActionsCartAddOrderItem"}}]},"target":{"type":"object","description":"엔드포인트 정보","required":["urlTemplate"],"properties":{"@type":{"type":"string","enum":["EntryPoint"]},"urlTemplate":{"type":"string","description":"URL"}}}}}}},"ActionsCartAddOrderItem":{"description":"구매정보","type":"object","required":["orderedItem","orderQuantity"],"properties":{"@type":{"type":"string","enum":["OrderItem"]},"orderedItem":{"$ref":"#/components/schemas/ActionsCartAddProduct"},"orderQuantity":{"type":"number","description":"수량"}}},"ActionsCartAddProduct":{"description":"상품 객체","type":"object","required":["sku","name","offers"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]},"offers":{"$ref":"#/components/schemas/ActionsCartAddOffer"}}},"ActionsCartAddOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}}}
```
## The ActionsCartAddOrderItem object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsCartAddOrderItem":{"description":"구매정보","type":"object","required":["orderedItem","orderQuantity"],"properties":{"@type":{"type":"string","enum":["OrderItem"]},"orderedItem":{"$ref":"#/components/schemas/ActionsCartAddProduct"},"orderQuantity":{"type":"number","description":"수량"}}},"ActionsCartAddProduct":{"description":"상품 객체","type":"object","required":["sku","name","offers"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]},"offers":{"$ref":"#/components/schemas/ActionsCartAddOffer"}}},"ActionsCartAddOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}}}
```
## The ActionsCartAddProduct object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsCartAddProduct":{"description":"상품 객체","type":"object","required":["sku","name","offers"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]},"offers":{"$ref":"#/components/schemas/ActionsCartAddOffer"}}},"ActionsCartAddOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}}}
```
## The ActionsCartAddOffer object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsCartAddOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}}}
```
## The ActionsCartRemoveEvent object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsCartRemoveEvent":{"title":"장바구니 제거","description":"사용자가 상품을 장바구니에서 제거하는 행동을 수집합니다","type":"object","required":["time","source","data"],"properties":{"specversion":{"type":"string","description":"스펙 버전","enum":["1.0.0"]},"id":{"type":"string","description":"이벤트 고유 식별자","enum":["EVT-REMOVE-FROM-CART"]},"type":{"type":"string","description":"이벤트 유형","enum":["remove_from_cart"]},"time":{"type":"string","description":"ISO 8601 UTC 이벤트 생성시간","format":"date-time"},"source":{"type":"string","description":"이벤트 발생 출처"},"datacontenttype":{"type":"string","description":"데이터 콘텐츠 타입","enum":["application/ld+json"]},"dataschema":{"type":"string","description":"데이터 스키마 경로","enum":["https://api.gelatto.ai/schema/actions/cart_remove.json"]},"data":{"type":"object","description":"이벤트 데이터 객체","required":["agent","object"],"properties":{"@context":{"type":"string","description":"스키마 context","enum":["https://schema.org/"]},"@type":{"type":"string","description":"액션 유형","enum":["DeleteAction"]},"agent":{"type":"object","description":"행위자 (Person)","required":["identifier"],"properties":{"@type":{"type":"string","enum":["Person"]},"identifier":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"type":"string","description":"값"}}},"type":"array","description":"행위자 식별자 목록 (userId, memberId, cookieId는 필수로 추가해야 함, 속성의 추가가 필요할 경우 협의)"},"gender":{"type":"string","enum":["Female","Male","https://schema.org/Female","https://schema.org/Male"]},"additionalProperty":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"값"}}},"type":"array","description":"추가 속성"}}},"object":{"oneOf":[{"$ref":"#/components/schemas/ActionsCartRemoveOrderItem"},{"type":"array","items":{"$ref":"#/components/schemas/ActionsCartRemoveOrderItem"}}]},"target":{"type":"object","description":"엔드포인트 정보","required":["urlTemplate"],"properties":{"@type":{"type":"string","enum":["EntryPoint"]},"urlTemplate":{"type":"string","description":"URL"}}}}}}},"ActionsCartRemoveOrderItem":{"description":"구매정보","type":"object","required":["orderedItem","orderQuantity"],"properties":{"@type":{"type":"string","enum":["OrderItem"]},"orderedItem":{"$ref":"#/components/schemas/ActionsCartRemoveProduct"},"orderQuantity":{"type":"number","description":"수량"}}},"ActionsCartRemoveProduct":{"description":"상품 객체","type":"object","required":["sku","name","offers"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]},"offers":{"$ref":"#/components/schemas/ActionsCartRemoveOffer"}}},"ActionsCartRemoveOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}}}
```
## The ActionsCartRemoveOrderItem object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsCartRemoveOrderItem":{"description":"구매정보","type":"object","required":["orderedItem","orderQuantity"],"properties":{"@type":{"type":"string","enum":["OrderItem"]},"orderedItem":{"$ref":"#/components/schemas/ActionsCartRemoveProduct"},"orderQuantity":{"type":"number","description":"수량"}}},"ActionsCartRemoveProduct":{"description":"상품 객체","type":"object","required":["sku","name","offers"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]},"offers":{"$ref":"#/components/schemas/ActionsCartRemoveOffer"}}},"ActionsCartRemoveOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}}}
```
## The ActionsCartRemoveProduct object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsCartRemoveProduct":{"description":"상품 객체","type":"object","required":["sku","name","offers"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]},"offers":{"$ref":"#/components/schemas/ActionsCartRemoveOffer"}}},"ActionsCartRemoveOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}}}
```
## The ActionsCartRemoveOffer object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsCartRemoveOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}}}
```
## The ActionsClickProductEvent object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsClickProductEvent":{"title":"상품 클릭","description":"사용자가 상품을 클릭하는 행동을 수집합니다","type":"object","required":["time","source","data"],"properties":{"specversion":{"type":"string","description":"스펙 버전","enum":["1.0.0"]},"id":{"type":"string","description":"이벤트 고유 식별자","enum":["EVT-CLICK-PRODUCT"]},"type":{"type":"string","description":"이벤트 유형","enum":["click_product"]},"time":{"type":"string","description":"ISO 8601 UTC 이벤트 생성시간","format":"date-time"},"source":{"type":"string","description":"이벤트 발생 출처"},"datacontenttype":{"type":"string","description":"데이터 콘텐츠 타입","enum":["application/ld+json"]},"dataschema":{"type":"string","description":"데이터 스키마 경로","enum":["https://api.gelatto.ai/schema/actions/click_product.json"]},"data":{"type":"object","description":"이벤트 데이터 객체","required":["agent","object"],"properties":{"@context":{"type":"string","description":"스키마 context","enum":["https://schema.org/"]},"@type":{"type":"string","description":"액션 유형","enum":["ChooseAction"]},"agent":{"type":"object","description":"행위자 (Person)","required":["identifier"],"properties":{"@type":{"type":"string","enum":["Person"]},"identifier":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"type":"string","description":"값"}}},"type":"array","description":"행위자 식별자 목록 (userId, memberId, cookieId는 필수로 추가해야 함, 속성의 추가가 필요할 경우 협의)"},"gender":{"type":"string","enum":["Female","Male","https://schema.org/Female","https://schema.org/Male"]},"additionalProperty":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"값"}}},"type":"array","description":"추가 속성"}}},"object":{"oneOf":[{"$ref":"#/components/schemas/ActionsClickProductItemList"},{"type":"array","items":{"$ref":"#/components/schemas/ActionsClickProductItemList"}}]},"target":{"type":"object","description":"엔드포인트 정보","required":["urlTemplate"],"properties":{"@type":{"type":"string","enum":["EntryPoint"]},"urlTemplate":{"type":"string","description":"URL"}}}}}}},"ActionsClickProductItemList":{"description":"상품 목록 객체","type":"object","required":["itemListElement"],"properties":{"@type":{"type":"string","enum":["ItemList"]},"itemListElement":{"$ref":"#/components/schemas/ActionsClickProductListItem"}}},"ActionsClickProductListItem":{"description":"상품 목록 항목","type":"object","required":["position","item"],"properties":{"@type":{"type":"string","enum":["ListItem"]},"item":{"$ref":"#/components/schemas/ActionsClickProductProduct"},"position":{"type":"number","description":"목록 내 노출 순서"}}},"ActionsClickProductProduct":{"description":"상품 객체","type":"object","required":["sku"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]}}}}}}
```
## The ActionsClickProductItemList object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsClickProductItemList":{"description":"상품 목록 객체","type":"object","required":["itemListElement"],"properties":{"@type":{"type":"string","enum":["ItemList"]},"itemListElement":{"$ref":"#/components/schemas/ActionsClickProductListItem"}}},"ActionsClickProductListItem":{"description":"상품 목록 항목","type":"object","required":["position","item"],"properties":{"@type":{"type":"string","enum":["ListItem"]},"item":{"$ref":"#/components/schemas/ActionsClickProductProduct"},"position":{"type":"number","description":"목록 내 노출 순서"}}},"ActionsClickProductProduct":{"description":"상품 객체","type":"object","required":["sku"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]}}}}}}
```
## The ActionsClickProductListItem object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsClickProductListItem":{"description":"상품 목록 항목","type":"object","required":["position","item"],"properties":{"@type":{"type":"string","enum":["ListItem"]},"item":{"$ref":"#/components/schemas/ActionsClickProductProduct"},"position":{"type":"number","description":"목록 내 노출 순서"}}},"ActionsClickProductProduct":{"description":"상품 객체","type":"object","required":["sku"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]}}}}}}
```
## The ActionsClickProductProduct object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsClickProductProduct":{"description":"상품 객체","type":"object","required":["sku"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]}}}}}}
```
## The ActionsPurchaseCancelEvent object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsPurchaseCancelEvent":{"title":"결제 취소","description":"사용자가 결제를 취소하는 행동을 수집합니다","type":"object","required":["time","source","data"],"properties":{"specversion":{"type":"string","description":"스펙 버전","enum":["1.0.0"]},"id":{"type":"string","description":"이벤트 고유 식별자","enum":["EVT-CANCEL-PURCHASE"]},"type":{"type":"string","description":"이벤트 유형","enum":["cancel_purchase"]},"time":{"type":"string","description":"ISO 8601 UTC 이벤트 생성시간","format":"date-time"},"source":{"type":"string","description":"이벤트 발생 출처"},"datacontenttype":{"type":"string","description":"데이터 콘텐츠 타입","enum":["application/ld+json"]},"dataschema":{"type":"string","description":"데이터 스키마 경로","enum":["https://api.gelatto.ai/schema/actions/purchase_cancel.json"]},"data":{"type":"object","description":"이벤트 데이터 객체","required":["agent","object"],"properties":{"@context":{"type":"string","description":"스키마 context","enum":["https://schema.org/"]},"@type":{"type":"string","description":"액션 유형","enum":["CancelAction"]},"agent":{"type":"object","description":"행위자 (Person)","required":["identifier"],"properties":{"@type":{"type":"string","enum":["Person"]},"identifier":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"type":"string","description":"값"}}},"type":"array","description":"행위자 식별자 목록 (userId, memberId, cookieId는 필수로 추가해야 함, 속성의 추가가 필요할 경우 협의)"},"gender":{"type":"string","enum":["Female","Male","https://schema.org/Female","https://schema.org/Male"]},"additionalProperty":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"값"}}},"type":"array","description":"추가 속성"}}},"object":{"oneOf":[{"$ref":"#/components/schemas/ActionsPurchaseCancelOrderItem"},{"type":"array","items":{"$ref":"#/components/schemas/ActionsPurchaseCancelOrderItem"}}]},"target":{"type":"object","description":"엔드포인트 정보","required":["urlTemplate"],"properties":{"@type":{"type":"string","enum":["EntryPoint"]},"urlTemplate":{"type":"string","description":"URL"}}}}}}},"ActionsPurchaseCancelOrderItem":{"description":"구매정보","type":"object","required":["orderedItem","orderQuantity"],"properties":{"@type":{"type":"string","enum":["OrderItem"]},"orderedItem":{"$ref":"#/components/schemas/ActionsPurchaseCancelProduct"},"orderQuantity":{"type":"number","description":"수량"}}},"ActionsPurchaseCancelProduct":{"description":"상품 객체","type":"object","required":["sku","name","offers"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]},"offers":{"$ref":"#/components/schemas/ActionsPurchaseCancelOffer"}}},"ActionsPurchaseCancelOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}}}
```
## The ActionsPurchaseCancelOrderItem object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsPurchaseCancelOrderItem":{"description":"구매정보","type":"object","required":["orderedItem","orderQuantity"],"properties":{"@type":{"type":"string","enum":["OrderItem"]},"orderedItem":{"$ref":"#/components/schemas/ActionsPurchaseCancelProduct"},"orderQuantity":{"type":"number","description":"수량"}}},"ActionsPurchaseCancelProduct":{"description":"상품 객체","type":"object","required":["sku","name","offers"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]},"offers":{"$ref":"#/components/schemas/ActionsPurchaseCancelOffer"}}},"ActionsPurchaseCancelOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}}}
```
## The ActionsPurchaseCancelProduct object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsPurchaseCancelProduct":{"description":"상품 객체","type":"object","required":["sku","name","offers"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]},"offers":{"$ref":"#/components/schemas/ActionsPurchaseCancelOffer"}}},"ActionsPurchaseCancelOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}}}
```
## The ActionsPurchaseCancelOffer object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsPurchaseCancelOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}}}
```
## The ActionsPurchaseCheckoutEvent object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsPurchaseCheckoutEvent":{"title":"결제 시작","description":"사용자가 결제를 시작하는 행동을 수집합니다","type":"object","required":["time","source","data"],"properties":{"specversion":{"type":"string","description":"스펙 버전","enum":["1.0.0"]},"id":{"type":"string","description":"이벤트 고유 식별자","enum":["EVT-START-CHECKOUT"]},"type":{"type":"string","description":"이벤트 유형","enum":["start_checkout"]},"time":{"type":"string","description":"ISO 8601 UTC 이벤트 생성시간","format":"date-time"},"source":{"type":"string","description":"이벤트 발생 출처"},"datacontenttype":{"type":"string","description":"데이터 콘텐츠 타입","enum":["application/ld+json"]},"dataschema":{"type":"string","description":"데이터 스키마 경로","enum":["https://api.gelatto.ai/schema/actions/purchase_checkout.json"]},"data":{"type":"object","description":"이벤트 데이터 객체","required":["agent","object"],"properties":{"@context":{"type":"string","description":"스키마 context","enum":["https://schema.org/"]},"@type":{"type":"string","description":"액션 유형","enum":["CheckoutAction"]},"agent":{"type":"object","description":"행위자 (Person)","required":["identifier"],"properties":{"@type":{"type":"string","enum":["Person"]},"identifier":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"type":"string","description":"값"}}},"type":"array","description":"행위자 식별자 목록 (userId, memberId, cookieId는 필수로 추가해야 함, 속성의 추가가 필요할 경우 협의)"},"gender":{"type":"string","enum":["Female","Male","https://schema.org/Female","https://schema.org/Male"]},"additionalProperty":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"값"}}},"type":"array","description":"추가 속성"}}},"object":{"oneOf":[{"$ref":"#/components/schemas/ActionsPurchaseCheckoutOrderItem"},{"type":"array","items":{"$ref":"#/components/schemas/ActionsPurchaseCheckoutOrderItem"}}]},"target":{"type":"object","description":"엔드포인트 정보","required":["urlTemplate"],"properties":{"@type":{"type":"string","enum":["EntryPoint"]},"urlTemplate":{"type":"string","description":"URL"}}}}}}},"ActionsPurchaseCheckoutOrderItem":{"description":"구매정보","type":"object","required":["orderedItem","orderQuantity"],"properties":{"@type":{"type":"string","enum":["OrderItem"]},"orderedItem":{"$ref":"#/components/schemas/ActionsPurchaseCheckoutProduct"},"orderQuantity":{"type":"number","description":"수량"}}},"ActionsPurchaseCheckoutProduct":{"description":"상품 객체","type":"object","required":["sku","name","offers"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]},"offers":{"$ref":"#/components/schemas/ActionsPurchaseCheckoutOffer"}}},"ActionsPurchaseCheckoutOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}}}
```
## The ActionsPurchaseCheckoutOrderItem object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsPurchaseCheckoutOrderItem":{"description":"구매정보","type":"object","required":["orderedItem","orderQuantity"],"properties":{"@type":{"type":"string","enum":["OrderItem"]},"orderedItem":{"$ref":"#/components/schemas/ActionsPurchaseCheckoutProduct"},"orderQuantity":{"type":"number","description":"수량"}}},"ActionsPurchaseCheckoutProduct":{"description":"상품 객체","type":"object","required":["sku","name","offers"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]},"offers":{"$ref":"#/components/schemas/ActionsPurchaseCheckoutOffer"}}},"ActionsPurchaseCheckoutOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}}}
```
## The ActionsPurchaseCheckoutProduct object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsPurchaseCheckoutProduct":{"description":"상품 객체","type":"object","required":["sku","name","offers"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]},"offers":{"$ref":"#/components/schemas/ActionsPurchaseCheckoutOffer"}}},"ActionsPurchaseCheckoutOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}}}
```
## The ActionsPurchaseCheckoutOffer object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsPurchaseCheckoutOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}}}
```
## The ActionsPurchaseCompleteEvent object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsPurchaseCompleteEvent":{"title":"결제 완료","description":"사용자가 결제를 완료하는 행동을 수집합니다","type":"object","required":["time","source","data"],"properties":{"specversion":{"type":"string","description":"스펙 버전","enum":["1.0.0"]},"id":{"type":"string","description":"이벤트 고유 식별자","enum":["EVT-COMPLETE-PURCHASE"]},"type":{"type":"string","description":"이벤트 유형","enum":["complete_purchase"]},"time":{"type":"string","description":"ISO 8601 UTC 이벤트 생성시간","format":"date-time"},"source":{"type":"string","description":"이벤트 발생 출처"},"datacontenttype":{"type":"string","description":"데이터 콘텐츠 타입","enum":["application/ld+json"]},"dataschema":{"type":"string","description":"데이터 스키마 경로","enum":["https://api.gelatto.ai/schema/actions/purchase_complete.json"]},"data":{"type":"object","description":"이벤트 데이터 객체","required":["agent","object"],"properties":{"@context":{"type":"string","description":"스키마 context","enum":["https://schema.org/"]},"@type":{"type":"string","description":"액션 유형","enum":["OrderAction"]},"agent":{"type":"object","description":"행위자 (Person)","required":["identifier"],"properties":{"@type":{"type":"string","enum":["Person"]},"identifier":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"type":"string","description":"값"}}},"type":"array","description":"행위자 식별자 목록 (userId, memberId, cookieId는 필수로 추가해야 함, 속성의 추가가 필요할 경우 협의)"},"gender":{"type":"string","enum":["Female","Male","https://schema.org/Female","https://schema.org/Male"]},"additionalProperty":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"값"}}},"type":"array","description":"추가 속성"}}},"object":{"oneOf":[{"$ref":"#/components/schemas/ActionsPurchaseCompleteOrderItem"},{"type":"array","items":{"$ref":"#/components/schemas/ActionsPurchaseCompleteOrderItem"}}]},"target":{"type":"object","description":"엔드포인트 정보","required":["urlTemplate"],"properties":{"@type":{"type":"string","enum":["EntryPoint"]},"urlTemplate":{"type":"string","description":"URL"}}}}}}},"ActionsPurchaseCompleteOrderItem":{"description":"구매정보","type":"object","required":["orderedItem","orderQuantity"],"properties":{"@type":{"type":"string","enum":["OrderItem"]},"orderedItem":{"$ref":"#/components/schemas/ActionsPurchaseCompleteProduct"},"orderQuantity":{"type":"number","description":"수량"}}},"ActionsPurchaseCompleteProduct":{"description":"상품 객체","type":"object","required":["sku","name","offers"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]},"offers":{"$ref":"#/components/schemas/ActionsPurchaseCompleteOffer"}}},"ActionsPurchaseCompleteOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}}}
```
## The ActionsPurchaseCompleteOrderItem object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsPurchaseCompleteOrderItem":{"description":"구매정보","type":"object","required":["orderedItem","orderQuantity"],"properties":{"@type":{"type":"string","enum":["OrderItem"]},"orderedItem":{"$ref":"#/components/schemas/ActionsPurchaseCompleteProduct"},"orderQuantity":{"type":"number","description":"수량"}}},"ActionsPurchaseCompleteProduct":{"description":"상품 객체","type":"object","required":["sku","name","offers"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]},"offers":{"$ref":"#/components/schemas/ActionsPurchaseCompleteOffer"}}},"ActionsPurchaseCompleteOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}}}
```
## The ActionsPurchaseCompleteProduct object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsPurchaseCompleteProduct":{"description":"상품 객체","type":"object","required":["sku","name","offers"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]},"offers":{"$ref":"#/components/schemas/ActionsPurchaseCompleteOffer"}}},"ActionsPurchaseCompleteOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}}}
```
## The ActionsPurchaseCompleteOffer object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsPurchaseCompleteOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}}}
```
## The ActionsSearchResultEvent object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsSearchResultEvent":{"title":"검색 결과 노출","description":"사용자에게 검색 결과가 노출되는 행동을 수집합니다","type":"object","required":["time","source","data"],"properties":{"specversion":{"type":"string","description":"스펙 버전","enum":["1.0.0"]},"id":{"type":"string","description":"이벤트 고유 식별자","enum":["EVT-VIEW-SEARCH-RESULT"]},"type":{"type":"string","description":"이벤트 유형","enum":["view_search_result"]},"time":{"type":"string","description":"ISO 8601 UTC 이벤트 생성시간","format":"date-time"},"source":{"type":"string","description":"이벤트 발생 출처"},"datacontenttype":{"type":"string","description":"데이터 콘텐츠 타입","enum":["application/ld+json"]},"dataschema":{"type":"string","description":"데이터 스키마 경로","enum":["https://api.gelatto.ai/schema/actions/search_result.json"]},"data":{"type":"object","description":"이벤트 데이터 객체","required":["agent","object"],"properties":{"@context":{"type":"string","description":"스키마 context","enum":["https://schema.org/"]},"@type":{"type":"string","description":"액션 유형","enum":["ViewAction"]},"agent":{"type":"object","description":"행위자 (Person)","required":["identifier"],"properties":{"@type":{"type":"string","enum":["Person"]},"identifier":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"type":"string","description":"값"}}},"type":"array","description":"행위자 식별자 목록 (userId, memberId, cookieId는 필수로 추가해야 함, 속성의 추가가 필요할 경우 협의)"},"gender":{"type":"string","enum":["Female","Male","https://schema.org/Female","https://schema.org/Male"]},"additionalProperty":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"값"}}},"type":"array","description":"추가 속성"}}},"object":{"$ref":"#/components/schemas/ActionsSearchResultItemList"},"target":{"type":"object","description":"엔드포인트 정보","required":["urlTemplate"],"properties":{"@type":{"type":"string","enum":["EntryPoint"]},"urlTemplate":{"type":"string","description":"URL"}}}}}}},"ActionsSearchResultItemList":{"description":"상품 목록 객체","type":"object","required":["numberOfItems","itemListElement"],"properties":{"@type":{"type":"string","enum":["ItemList"]},"numberOfItems":{"type":"number","description":"검색 결과 총 건수"},"itemListElement":{"oneOf":[{"$ref":"#/components/schemas/ActionsSearchResultListItem"},{"type":"array","items":{"$ref":"#/components/schemas/ActionsSearchResultListItem"}}]}}},"ActionsSearchResultListItem":{"description":"상품 목록 항목","type":"object","required":["position","item"],"properties":{"@type":{"type":"string","enum":["ListItem"]},"item":{"$ref":"#/components/schemas/ActionsSearchResultProduct"},"position":{"type":"number","description":"목록 내 노출 순서"}}},"ActionsSearchResultProduct":{"description":"상품 객체","type":"object","required":["sku"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]}}}}}}
```
## The ActionsSearchResultItemList object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsSearchResultItemList":{"description":"상품 목록 객체","type":"object","required":["numberOfItems","itemListElement"],"properties":{"@type":{"type":"string","enum":["ItemList"]},"numberOfItems":{"type":"number","description":"검색 결과 총 건수"},"itemListElement":{"oneOf":[{"$ref":"#/components/schemas/ActionsSearchResultListItem"},{"type":"array","items":{"$ref":"#/components/schemas/ActionsSearchResultListItem"}}]}}},"ActionsSearchResultListItem":{"description":"상품 목록 항목","type":"object","required":["position","item"],"properties":{"@type":{"type":"string","enum":["ListItem"]},"item":{"$ref":"#/components/schemas/ActionsSearchResultProduct"},"position":{"type":"number","description":"목록 내 노출 순서"}}},"ActionsSearchResultProduct":{"description":"상품 객체","type":"object","required":["sku"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]}}}}}}
```
## The ActionsSearchResultListItem object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsSearchResultListItem":{"description":"상품 목록 항목","type":"object","required":["position","item"],"properties":{"@type":{"type":"string","enum":["ListItem"]},"item":{"$ref":"#/components/schemas/ActionsSearchResultProduct"},"position":{"type":"number","description":"목록 내 노출 순서"}}},"ActionsSearchResultProduct":{"description":"상품 객체","type":"object","required":["sku"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]}}}}}}
```
## The ActionsSearchResultProduct object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsSearchResultProduct":{"description":"상품 객체","type":"object","required":["sku"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]}}}}}}
```
## The ActionsSearchSubmittedEvent object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsSearchSubmittedEvent":{"title":"검색 제출","description":"사용자가 검색어를 제출하는 행동을 수집합니다","type":"object","required":["time","source","data"],"properties":{"specversion":{"type":"string","description":"스펙 버전","enum":["1.0.0"]},"id":{"type":"string","description":"이벤트 고유 식별자","enum":["EVT-SEARCH-SUBMITTED"]},"type":{"type":"string","description":"이벤트 유형","enum":["search_submitted"]},"time":{"type":"string","description":"ISO 8601 UTC 이벤트 생성시간","format":"date-time"},"source":{"type":"string","description":"이벤트 발생 출처"},"datacontenttype":{"type":"string","description":"데이터 콘텐츠 타입","enum":["application/ld+json"]},"dataschema":{"type":"string","description":"데이터 스키마 경로","enum":["https://api.gelatto.ai/schema/actions/search_submitted.json"]},"data":{"type":"object","description":"이벤트 데이터 객체","required":["agent","query"],"properties":{"@context":{"type":"string","description":"스키마 context","enum":["https://schema.org/"]},"@type":{"type":"string","description":"액션 유형","enum":["SearchAction"]},"agent":{"type":"object","description":"행위자 (Person)","required":["identifier"],"properties":{"@type":{"type":"string","enum":["Person"]},"identifier":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"type":"string","description":"값"}}},"type":"array","description":"행위자 식별자 목록 (userId, memberId, cookieId는 필수로 추가해야 함, 속성의 추가가 필요할 경우 협의)"},"gender":{"type":"string","enum":["Female","Male","https://schema.org/Female","https://schema.org/Male"]},"additionalProperty":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"값"}}},"type":"array","description":"추가 속성"}}},"query":{"type":"string","description":"검색어"},"object":{"type":"object","description":"대상 객체","required":["actionOption"],"properties":{"@type":{"type":"string","enum":["Thing"]},"actionOption":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"값"}}},"type":"array","description":"액션 옵션"}}},"target":{"type":"object","description":"엔드포인트 정보","required":["urlTemplate"],"properties":{"@type":{"type":"string","enum":["EntryPoint"]},"urlTemplate":{"type":"string","description":"URL"}}}}}}}}}}
```
## The ActionsViewProductEvent object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsViewProductEvent":{"title":"상품 상세조회","description":"사용자가 상품 상세 페이지에 진입하는 행동을 수집합니다","type":"object","required":["time","source","data"],"properties":{"specversion":{"type":"string","description":"스펙 버전","enum":["1.0.0"]},"id":{"type":"string","description":"이벤트 고유 식별자","enum":["EVT-VIEW-PRODUCT"]},"type":{"type":"string","description":"이벤트 유형","enum":["view_product"]},"time":{"type":"string","description":"ISO 8601 UTC 이벤트 생성시간","format":"date-time"},"source":{"type":"string","description":"이벤트 발생 출처"},"datacontenttype":{"type":"string","description":"데이터 콘텐츠 타입","enum":["application/ld+json"]},"dataschema":{"type":"string","description":"데이터 스키마 경로","enum":["https://api.gelatto.ai/schema/actions/view_product.json"]},"data":{"type":"object","description":"이벤트 데이터 객체","required":["agent","object"],"properties":{"@context":{"type":"string","description":"스키마 context","enum":["https://schema.org/"]},"@type":{"type":"string","description":"액션 유형","enum":["ViewAction"]},"agent":{"type":"object","description":"행위자 (Person)","required":["identifier"],"properties":{"@type":{"type":"string","enum":["Person"]},"identifier":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"type":"string","description":"값"}}},"type":"array","description":"행위자 식별자 목록 (userId, memberId, cookieId는 필수로 추가해야 함, 속성의 추가가 필요할 경우 협의)"},"gender":{"type":"string","enum":["Female","Male","https://schema.org/Female","https://schema.org/Male"]},"additionalProperty":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"값"}}},"type":"array","description":"추가 속성"}}},"object":{"$ref":"#/components/schemas/ActionsViewProductProduct"},"target":{"type":"object","description":"엔드포인트 정보","required":["urlTemplate"],"properties":{"@type":{"type":"string","enum":["EntryPoint"]},"urlTemplate":{"type":"string","description":"URL"}}}}}}},"ActionsViewProductProduct":{"description":"상품 객체","type":"object","required":["sku"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]}}}}}}
```
## The ActionsViewProductProduct object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsViewProductProduct":{"description":"상품 객체","type":"object","required":["sku"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]}}}}}}
```
## The ActionsWishlistAddEvent object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsWishlistAddEvent":{"title":"위시리스트 등록","description":"사용자가 상품을 위시리스트에 등록하는 행동을 수집합니다","type":"object","required":["time","source","data"],"properties":{"specversion":{"type":"string","description":"스펙 버전","enum":["1.0.0"]},"id":{"type":"string","description":"이벤트 고유 식별자","enum":["EVT-ADD-TO-WISHLIST"]},"type":{"type":"string","description":"이벤트 유형","enum":["add_to_wishlist"]},"time":{"type":"string","description":"ISO 8601 UTC 이벤트 생성시간","format":"date-time"},"source":{"type":"string","description":"이벤트 발생 출처"},"datacontenttype":{"type":"string","description":"데이터 콘텐츠 타입","enum":["application/ld+json"]},"dataschema":{"type":"string","description":"데이터 스키마 경로","enum":["https://api.gelatto.ai/schema/actions/wishlist_add.json"]},"data":{"type":"object","description":"이벤트 데이터 객체","required":["agent","object"],"properties":{"@context":{"type":"string","description":"스키마 context","enum":["https://schema.org/"]},"@type":{"type":"string","description":"액션 유형","enum":["AddAction"]},"agent":{"type":"object","description":"행위자 (Person)","required":["identifier"],"properties":{"@type":{"type":"string","enum":["Person"]},"identifier":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"type":"string","description":"값"}}},"type":"array","description":"행위자 식별자 목록 (userId, memberId, cookieId는 필수로 추가해야 함, 속성의 추가가 필요할 경우 협의)"},"gender":{"type":"string","enum":["Female","Male","https://schema.org/Female","https://schema.org/Male"]},"additionalProperty":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"값"}}},"type":"array","description":"추가 속성"}}},"object":{"oneOf":[{"$ref":"#/components/schemas/ActionsWishlistAddOrderItem"},{"type":"array","items":{"$ref":"#/components/schemas/ActionsWishlistAddOrderItem"}}]},"target":{"type":"object","description":"엔드포인트 정보","required":["urlTemplate"],"properties":{"@type":{"type":"string","enum":["EntryPoint"]},"urlTemplate":{"type":"string","description":"URL"}}}}}}},"ActionsWishlistAddOrderItem":{"description":"구매정보","type":"object","required":["orderedItem"],"properties":{"@type":{"type":"string","enum":["OrderItem"]},"orderedItem":{"$ref":"#/components/schemas/ActionsWishlistAddProduct"}}},"ActionsWishlistAddProduct":{"description":"상품 객체","type":"object","required":["sku","name"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]},"offers":{"$ref":"#/components/schemas/ActionsWishlistAddOffer"}}},"ActionsWishlistAddOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}}}
```
## The ActionsWishlistAddOrderItem object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsWishlistAddOrderItem":{"description":"구매정보","type":"object","required":["orderedItem"],"properties":{"@type":{"type":"string","enum":["OrderItem"]},"orderedItem":{"$ref":"#/components/schemas/ActionsWishlistAddProduct"}}},"ActionsWishlistAddProduct":{"description":"상품 객체","type":"object","required":["sku","name"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]},"offers":{"$ref":"#/components/schemas/ActionsWishlistAddOffer"}}},"ActionsWishlistAddOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}}}
```
## The ActionsWishlistAddProduct object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsWishlistAddProduct":{"description":"상품 객체","type":"object","required":["sku","name"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]},"offers":{"$ref":"#/components/schemas/ActionsWishlistAddOffer"}}},"ActionsWishlistAddOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}}}
```
## The ActionsWishlistAddOffer object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsWishlistAddOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}}}
```
## The ActionsWishlistRemoveEvent object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsWishlistRemoveEvent":{"title":"위시리스트 제거","description":"사용자가 상품을 위시리스트에서 제거하는 행동을 수집합니다","type":"object","required":["time","source","data"],"properties":{"specversion":{"type":"string","description":"스펙 버전","enum":["1.0.0"]},"id":{"type":"string","description":"이벤트 고유 식별자","enum":["EVT-REMOVE-FROM-WISHLIST"]},"type":{"type":"string","description":"이벤트 유형","enum":["remove_from_wishlist"]},"time":{"type":"string","description":"ISO 8601 UTC 이벤트 생성시간","format":"date-time"},"source":{"type":"string","description":"이벤트 발생 출처"},"datacontenttype":{"type":"string","description":"데이터 콘텐츠 타입","enum":["application/ld+json"]},"dataschema":{"type":"string","description":"데이터 스키마 경로","enum":["https://api.gelatto.ai/schema/actions/wishlist_remove.json"]},"data":{"type":"object","description":"이벤트 데이터 객체","required":["agent","object"],"properties":{"@context":{"type":"string","description":"스키마 context","enum":["https://schema.org/"]},"@type":{"type":"string","description":"액션 유형","enum":["DeleteAction"]},"agent":{"type":"object","description":"행위자 (Person)","required":["identifier"],"properties":{"@type":{"type":"string","enum":["Person"]},"identifier":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"type":"string","description":"값"}}},"type":"array","description":"행위자 식별자 목록 (userId, memberId, cookieId는 필수로 추가해야 함, 속성의 추가가 필요할 경우 협의)"},"gender":{"type":"string","enum":["Female","Male","https://schema.org/Female","https://schema.org/Male"]},"additionalProperty":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"값"}}},"type":"array","description":"추가 속성"}}},"object":{"oneOf":[{"$ref":"#/components/schemas/ActionsWishlistRemoveOrderItem"},{"type":"array","items":{"$ref":"#/components/schemas/ActionsWishlistRemoveOrderItem"}}]},"target":{"type":"object","description":"엔드포인트 정보","required":["urlTemplate"],"properties":{"@type":{"type":"string","enum":["EntryPoint"]},"urlTemplate":{"type":"string","description":"URL"}}}}}}},"ActionsWishlistRemoveOrderItem":{"description":"구매정보","type":"object","required":["orderedItem"],"properties":{"@type":{"type":"string","enum":["OrderItem"]},"orderedItem":{"$ref":"#/components/schemas/ActionsWishlistRemoveProduct"}}},"ActionsWishlistRemoveProduct":{"description":"상품 객체","type":"object","required":["sku","name"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]},"offers":{"$ref":"#/components/schemas/ActionsWishlistRemoveOffer"}}},"ActionsWishlistRemoveOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}}}
```
## The ActionsWishlistRemoveOrderItem object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsWishlistRemoveOrderItem":{"description":"구매정보","type":"object","required":["orderedItem"],"properties":{"@type":{"type":"string","enum":["OrderItem"]},"orderedItem":{"$ref":"#/components/schemas/ActionsWishlistRemoveProduct"}}},"ActionsWishlistRemoveProduct":{"description":"상품 객체","type":"object","required":["sku","name"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]},"offers":{"$ref":"#/components/schemas/ActionsWishlistRemoveOffer"}}},"ActionsWishlistRemoveOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}}}
```
## The ActionsWishlistRemoveProduct object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsWishlistRemoveProduct":{"description":"상품 객체","type":"object","required":["sku","name"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]},"offers":{"$ref":"#/components/schemas/ActionsWishlistRemoveOffer"}}},"ActionsWishlistRemoveOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}}}
```
## The ActionsWishlistRemoveOffer object
```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsWishlistRemoveOffer":{"description":"수량/가격 객체","type":"object","required":["price","priceCurrency"],"properties":{"@type":{"type":"string","enum":["Offer"]},"price":{"type":"number","description":"판매가격"},"priceCurrency":{"type":"string","description":"ISO 4217 통화코드 (예: KRW, USD, JPY)"}}}}}}
```
# Naver EP URL 설정 가이드
NaverEP URL을 확인하는 방법에 대해 안내합니다.
{% hint style="warning" %}
URL 은 접근 가능한 공개 URL만 사용할 수 있습니다.
{% endhint %}
## **URL만 찾으면 되는 경우**
TSV 파일이 어디에 저장되어 있는지에 따라 URL 형태가 다릅니다. 환경을 확인하여 URL 주소를 확인해 주세요.
#### **방법 1: 네이버 쇼핑파트너센터에서 확인**
1. [네이버 쇼핑파트너센터](https://center.shopping.naver.com/login) 로그인
2. 상품 관리 → 상품정보 수신현황 이동
3. 쇼핑몰 상품 DB URL 항목에서 URL 복사
{% hint style="warning" %}
URL 은 접근 가능한 공개 URL만 사용할 수 있습니다.
{% endhint %}
#### **방법 2: 개발팀에 문의**
TSV 파일은 보통 아래 중 한 곳에 저장되어 있습니다.
* 쇼핑몰 서버 내 특정 경로에 정적 파일로 생성되는 경우
* AWS S3, Google Cloud Storage 등 외부 파일 서버(오브젝트 스토리지)에 업로드되는 경우
* 별도 API 엔드포인트로 동적으로 생성되는 경우
저장 위치에 따라 EP URL 형태가 다릅니다. 아래의 URL 을 참고해 주세요.
개발팀에 아래와 같이 문의해 주세요.
> "네이버 쇼핑 연동에 사용 중인 TSV 피드 파일 URL이 어떻게 되나요? S3나 CDN 등 외부 파일 서버를 사용 중이라면 해당 공개 URL도 함께 알려주세요."
***
## **처음 만드는 경우**
* **TSV 파일 스펙**
* 1행: 컬럼 헤더
* 2행 이후: 상품 데이터 (상품 1개 = 1행)
* 구분자: 탭(`\t`)
* 인코딩: UTF-8 (BOM 없음)
{% hint style="info" %}
gelatto는 [네이버 EP 3.0](https://join.shopping.naver.com/misc/download/ep_guide.nhn) TSV 표준 포맷을 사용합니다.
{% endhint %}
#### **필수 필드**
컬럼명
설명
예시
id
상품 고유 ID
PRD_001
title
상품명
[브랜드] 반팔 티셔츠 화이트 L
price_pc
PC 판매가 (정수, 원화)
29000
link
상품 상세 URL
https://shop.example.com/product/1
image_link
대표 이미지 URL
https://cdn.example.com/img/1.jpg
category_name1
카테고리 대분류
의류
shipping
배송비 (무료=0, 착불=-1)
3000
#### **선택 필드 (권장)**
| 컬럼명 | 설명 |
| ---------------- | ------------ |
| `price_mobile` | 모바일 판매가 |
| `normal_price` | 정가 (할인 전 가격) |
| `mobile_link` | 모바일 상품 URL |
| `add_image_link` | 추가 이미지 URL |
| `category_name2` | 카테고리 중분류 |
| `category_name3` | 카테고리 소분류 |
| `brand` | 브랜드명 |
| `review_count` | 리뷰 수 |
**TSV 샘플**
```
id title price_pc link image_link category_name1 shipping
PRD_001 [브랜드] 반팔 티셔츠 화이트 L 29000 https://shop.example.com/product/1 https://cdn.example.com/img/1.jpg 의류 3000
PRD_002 [브랜드] 슬랙스 블랙 M 49000 https://shop.example.com/product/2 https://cdn.example.com/img/2.jpg 의류 0
```
#### **개발팀 구현 체크리스트**
* 전체 상품을 TSV 형식으로 출력하는 엔드포인트 구현
* 파일 URL이 외부에서 HTTP/HTTPS로 접근 가능한지 확인
{% hint style="warning" %}
URL 은 접근 가능한 공개 URL만 사용할 수 있습니다.
{% endhint %}
***
## **Naver EP URL 정상 여부 확인**
브라우저 주소창에 EP URL을 직접 입력했을 때 TSV 데이터가 텍스트로 표시되면 정상입니다.
```
O 정상 브라우저에서 탭 구분 텍스트 데이터가 표시됨
```
***
## **자주 묻는 질문**
Q. 상품이 추가·수정되면 TSV 파일도 업데이트해야 하나요?
TSV 생성 로직이 항상 최신 데이터를 반영하도록 구현되어 있으면 됩니다. 이후 gelatto가 어드민에서 설정된 주기로 EP URL에 접근하여 자동으로 최신 데이터를 수집합니다.
Q. 컬럼 값에 탭이나 줄바꿈이 포함된 경우 어떻게 처리하나요?
탭(`\t`)과 개행(`\n`, `\r`) 문자는 반드시 공백( ) 처리 또는 제거 후 출력해야 합니다. 포함된 경우 파싱 오류로 해당 상품이 무효 처리됩니다.
# GMC Feed URL 설정 가이드
GMC(Google Merchant Center) Feed URL 확인하는 방법에 대해 안내합니다.
## **URL만 찾으면 되는 경우**
피드 파일이 어디에 저장되어 있는지에 따라 URL 형태가 다릅니다.
#### **방법 1: Google Merchant Center에서 확인**
1. [Google Merchant Center](https://merchants.google.com/) 로그인
2. 좌측 메뉴 제품 → 피드 이동
3. 등록된 피드 항목 클릭 후 가져오기 URL 확인 및 복사
{% hint style="info" %}
GMC Feed 목록에서 `Content API` 라고 표시된 항목은 파일 URL이 아닙니다.\
파일 형식으로 등록된 항목에서만 가져오기 URL을 확인할 수 있습니다.
{% endhint %}
#### **방법 2: 개발팀에 문의**
피드 파일은 보통 아래 중 한 곳에 저장되어 있습니다.
* 쇼핑몰 서버 내 특정 경로에 정적 파일로 생성되는 경우
* AWS S3, Google Cloud Storage 등 외부 파일 서버(오브젝트 스토리지)에 업로드되는 경우
* 별도 API 엔드포인트로 동적으로 생성되는 경우
저장 위치에 따라 Feed URL 형태가 다릅니다.
개발팀에 아래와 같이 문의해 주세요.
> "Google Merchant Center 연동에 사용 중인 피드 파일 URL이 어떻게 되나요? S3나 CDN 등 외부 파일 서버를 사용 중이라면 해당 공개 URL도 함께 알려주세요."
***
## **처음 만드는 경우**
GMC Feed 파일을 개발팀에서 직접 구현해야 합니다. gelatto는 아래 세 가지 형식을 지원합니다.
형식
특징
확장자 예시
XML
구조화된 태그 형식, 계층적 데이터 표현 가능
products.xml
TSV
탭 구분 텍스트, 용량 작고 처리 빠름
products.tsv
TXT
TSV와 동일한 탭 구분 형식, 확장자만 다름
products.txt
#### **필수 필드**
포함되어야 하는 내용은 파일 형식과 관계없이 동일합니다.
필드명
설명
예시
id
상품 고유 ID
PRD_001
title
상품명
[브랜드] 반팔 티셔츠 화이트 L
description
상품 설명
레드 커튼은 옅은 회색 배경에 다양한 색상의 꽃들이 풍성하게 그려진 홈데코 패브릭 커튼입니다.
price
판매가 (통화 포함)
29000 KRW
link
상품 상세 URL
https://shop.example.com/product/1
image_link
대표 이미지 URL
https://cdn.example.com/img/1.jpg
brand
브랜드명
gelatto
availability
재고 상태
in_stock, out_of_stock
{% hint style="info" %}
[Google 공식 문서](https://support.google.com/merchants/answer/7052112#product_category)를 참고해 주세요.
{% endhint %}
#### **선택 필드 (권장)**
필드명
설명
google_product_category
Google 제품 카테고리
sale_price
할인가
mobile_link
모바일 상품 URL
additional_image_link
추가 이미지 URL
color
컬러 (패션에서는 특히 권장)
size
사이즈 (패션에서는 특히 권장)
gtin
국제 상품 번호 (바코드)
mpn
제조사 상품 번호
**XML 샘플**
```xml
My Shop Feed
https://shop.example.com
PRD_001[브랜드] 반팔 티셔츠 화이트 L29000 KRWhttps://shop.example.com/product/1https://cdn.example.com/img/1.jpg의류 및 액세서리 > 의류KR3000 KRW
```
**TSV / TXT 샘플**
```
id title price link image_link google_product_category shipping
PRD_001 [브랜드] 반팔 티셔츠 화이트 L 29000 KRW https://shop.example.com/product/1 https://cdn.example.com/img/1.jpg 의류 및 액세서리 > 의류 KR:::3000 KRW
PRD_002 [브랜드] 슬랙스 블랙 M 49000 KRW https://shop.example.com/product/2 https://cdn.example.com/img/2.jpg 의류 및 액세서리 > 의류 KR:::0 KRW
```
#### **개발팀 구현 체크리스트**
* 전체 상품을 지원 형식(XML / TSV / TXT) 중 하나로 출력하는 엔드포인트 구현
* TSV / TXT: 컬럼값 내 탭(`\t`), 개행(`\n`) 문자 제거 또는 공백 치환
* 파일 URL이 외부에서 HTTP/HTTPS로 접근 가능한지 확인
***
## **GMC Feed URL 정상 여부 확인**
브라우저 주소창에 Feed URL을 직접 입력했을 때 파일 데이터가 표시되면 정상입니다.
* 정상: 브라우저에서 XML 또는 탭 구분 텍스트 데이터가 표시됨
***
## **자주 묻는 질문**
Q. XML, TSV, TXT 중 어떤 형식을 사용해야 하나요?
세 형식 모두 지원합니다. 이미 GMC에 연동 중인 파일이 있다면 해당 형식을 그대로 사용하시면 됩니다. 새로 만드는 경우라면 용량이 작고 처리가 빠른 TSV 또는 TXT를 권장합니다.
Q. TSV / TXT 컬럼값에 탭이나 줄바꿈이 포함된 경우 어떻게 처리하나요?
탭(`\t`)과 개행(`\n`, `\r`) 문자는 반드시 공백( ) 처리 또는 제거 후 출력해야 합니다. 포함된 경우 파싱 오류로 해당 상품이 무효 처리됩니다.
# 유입 트래픽 추적 (UTM)
젠서 디스커버리 및 젤라또에서 파트너사 자사몰로 이동(아웃링크)할 때, URL에 UTM 파라미터를 추가할 수 있습니다. 파트너사에서는 Google Analytics 등 분석 도구를 통해 **젠서 디스커버리와 젤라또가 기여한** 유입 트래픽과 **전환 성과를 명확하게** 확인하고 성과를 측정할 수 있습니다.
사용자가 위 버튼을 클릭하면 파트너사 자사몰로 이동하며, 이때 설정한 UTM 파라미터가 URL에 추가됩니다.
{% hint style="info" %}
젠서 디스커버리는 UTM 파라미터가 꺼진 상태로, 젤라또는 켜진 상태로 시작합니다. 사용 여부와 값은 [파라미터 설정](https://help.genser.ai/settings/site/parameter-settings)에서 변경할 수 있습니다.
{% endhint %}
***
## **1. UTM 파라미터 규칙**
UTM 파라미터를 사용하면 자사몰로 이동하는 링크에 아래 파라미터가 추가됩니다.
| 파라미터 | 설명 | 젠서 디스커버리 | 젤라또 |
| --------------- | ----- | ----------- | ------------ |
| **utm\_source** | 유입 출처 | 연결한 커스텀 도메인 | `gelatto.ai` |
| **utm\_medium** | 유입 방식 | `referral` | `referral` |
사용자가 젠서 디스커버리에서 상품을 클릭하여 자사몰로 이동하면, URL은 아래와 같은 형태가 됩니다.
```http
https://shop.example.com/product/123?utm_source=aishop.example.com&utm_medium=referral
```
{% hint style="info" %}
위 값은 기본값입니다. [파라미터 설정](https://help.genser.ai/settings/site/parameter-settings)에서 직접 설정을 선택하면 원하는 값으로 바꿀 수 있고, 젠서 디스커버리에서는 커스텀 파라미터를 추가할 수 있습니다.
{% endhint %}
***
## **2. Google Analytics에서 확인하는 방법**
1. Google Analytics 로그인
2. **트래픽 획득** 보고서로 이동
3. 소스/매체 기준으로 조회
4. **연결한 커스텀 도메인 / referral**로 필터링(예: `aishop.example.com / referral`)
젤라또 유입은 **gelatto.ai / referral**로 필터링해 확인합니다.
***
## **자주 묻는 질문**
Q. UTM 파라미터를 원하는 형태로 변경할 수 있나요?
[파라미터 설정](https://help.genser.ai/settings/site/parameter-settings)에서 직접 설정을 선택하면 값을 직접 등록할 수 있습니다. `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`를 최대 5개까지 등록할 수 있습니다.
Q. UTM 파라미터를 추가하지 않고 링크를 보낼 수 있나요?
[파라미터 설정](https://help.genser.ai/settings/site/parameter-settings)에서 UTM 파라미터를 끄면 파라미터 없이 링크가 전달됩니다. 젠서 디스커버리는 꺼진 상태로 시작하고, 젤라또는 켜진 상태로 시작합니다.
# 에러 코드
대분류 코드 (분류명)
코드
설명
상세 설명
001 (파일 에러)
001
파일 확장자
지원하지 않는 파일 확장자입니다.
002
파일 인코딩
지원하지 않는 파일 인코딩 형식입니다.
003
파일 용량
지원하는 파일 용량을 초과하였습니다.
004
파일명
지원하는 파일명의 길이를 초과하였습니다.
005
손상된 파일
손상된 파일입니다.
200 (이미지 파일 에러)
200
이미지 사이즈
업로드한 이미지의 사이즈는 지원되지 않습니다.
201
이미지 비율
업로드한 이미지의 비율은 지원되지 않습니다.
900 (서버 에러)
900
서버 에러
예기치 못한 에러가 발생했습니다.
# Copy of 요청 파라미터 설명
{% hint style="info" %}
**요청 데이터를 설명합니다. 자세한 API 요청 방식은**[ **상품 수집 API** ](/developers/product-collection/api)**를 참고해 주세요.**
{% endhint %}
## 공통 데이터 구조
### 다국어 텍스트 필드
상품명, 브랜드명, 카테고리명 등 텍스트 필드는 세 가지 형식을 지원합니다.
**형식 1. 단순 문자열**
```json
"name": "클래식 티셔츠"
```
**형식 2. 언어 지정 객체**
```json
"name": {
"@value": "클래식 티셔츠",
"@language": "ko"
}
```
**형식 3. 다국어 배열**
* 지원 언어 코드 (ISO 639-1): `ko`, `en`, `ja`
```json
"name": [
{ "@value": "클래식 티셔츠", "@language": "ko" },
{ "@value": "Classic T-Shirt", "@language": "en" },
{ "@value": "クラシックTシャツ", "@language": "ja" }
]
```
{% hint style="info" %}
언어 지정 객체(형식 2, 3)를 사용할 때 `@value`와 `@language`는 모두 필수입니다. `@language`를 생략하면 `400` 에러가 반환됩니다. 모든 언어를 반드시 제공할 필요는 없으며, 필요한 언어만 전달하면 됩니다.
{% endhint %}
### 데이터 입력 규칙
* **필수 필드와 null**: 필드 명세표에서 **필수(O)** 로 표기된 필드는 반드시 유효한 값을 포함해야 합니다. 필수 필드에 `null`을 전송하면 `400` 에러가 반환됩니다. 선택(X) 필드는 생략하거나 `null`로 전송할 수 있습니다.
* **문자열(string)**: 별도의 `maxLength` 제약 없이 적절한 길이로 전송하는 것을 권장합니다.
* **숫자(number)**: 별도의 소수점 정밀도 규약 없이 통화에 맞는 일반적인 자릿수를 사용합니다 (예: KRW는 정수, USD는 소수점 이하 2자리).
* **enum**: 허용되는 값이 지정된 필드는 Enum 값 레퍼런스 섹션에 정리되어 있습니다. 명시된 값 이외의 값을 전송하면 `400` 에러가 반환됩니다.
* **필드 간 의존관계**: 특정 필드의 값에 따라 다른 필드의 필수 여부가 변경되는 조건부 필수 규칙은 적용되지 않습니다. 필드 명세표의 필수 여부만 기준으로 데이터를 구성합니다.
* `@graph` 배열에 최소 1개, 최대 1,000개의 상품을 포함할 수 있습니다.
* API 명세서에 기재된 모든 필드는 null을 허용하지 않습니다.
***
## 필드 상세 명세
#### **이벤트 객체 (CollectorProductsEvent)**
필드
타입
필수
설명
@context
string
X
스키마 context. 고정값: "https://schema.org"
specversion
string
X
스펙 버전. 고정값: "1.0"
id
string
X
이벤트 고유 식별자. 등록: "EVT-CREATE-PRODUCT", 수정: "EVT-UPDATE-PRODUCT"
type
string
X
이벤트 유형. 등록: "create_product", 수정: "update_product"
agent
object
O
행위자 정보
@graph
array
O
상품 데이터 배열 (1~1,000건)
#### **agent 객체**
필드
타입
필수
설명
@type
string
X
유형. 고정값: "Organization"
name
string
O
요청 기업명
#### **상품 객체 (@graph)**
`@graph` 배열의 각 항목은 하나의 상품을 나타냅니다.
필드
타입
필수
설명
@type
string
X
유형. 고정값: "Product"
sku
string
O
상품 코드 (고유 식별자)
name
string | object | array
O
상품명. 다국어 지원
description
object | array
O
상품 설명
brand
object
O
브랜드 정보
category
object | array
O
카테고리 정보
positiveNotes
string | object | array
X
핵심 장점 요약. 다국어 지원
url
string | object | array
O
상품 페이지 URL. 다국어 지원
mobileUrl
string | object | array
X
모바일 상품 페이지 URL. 다국어 지원
itemCondition
string
X
상품 상태. enum 참고
hasAdultConsideration
string
X
성인 대상 상품 구분. enum 참고
countryOfOrigin
object
X
제조 국가 정보
material
string | object | array
X
소재 정보. 다국어 지원
additionalProperty
array
X
추가 속성
offers
object | array
O
SKU별 가격/재고 정보
#### **countryOfOrigin 객체**
필드
타입
필수
설명
@type
string
X
유형. 고정값: "Country"
address
string
O
제조 국가 코드 (ISO 3166-1 alpha-2, 예: "KR", "JP", "US")
#### **브랜드 (brand)**
| 필드 | 타입 | 필수 | 설명 |
| ------- | ------------------------- | -- | ------------------ |
| `@type` | string | X | 유형. 고정값: `"Brand"` |
| `@id` | string | O | 브랜드 식별자 |
| `name` | string \| object \| array | O | 브랜드 이름. 다국어 지원 |
| `logo` | array\ | X | 브랜드 로고 URL 목록 |
#### **카테고리 (category)**
단일 객체 또는 배열로 전달합니다. 배열 사용 시 `position` 값으로 카테고리 계층 수준을 표현합니다.
필드
타입
필수
설명
@type
string
X
유형. 고정값: "CategoryCode"
codeValue
string
O
카테고리 코드
name
object | array
O
카테고리 이름. 다국어 지원
position
integer
O
카테고리 수준 (1 = 대분류, 2 = 중분류, ...)
#### **상품 설명 (description)**
필드
타입
필수
설명
@type
string
X
유형. 고정값: "TextObject"
text
string
O
설명 텍스트
inLanguage
string
O
언어 코드 (ISO 639-1): ko, en, ja
image
object | array
X
설명에 포함된 이미지 정보
additionalProperty
array
X
추가 속성
#### **description 내 이미지 객체**
| 필드 | 타입 | 필수 | 설명 |
| ------------ | ------ | -- | ------------------------ |
| `@type` | string | X | 유형. 고정값: `"ImageObject"` |
| `contentUrl` | string | X | 이미지 URL |
| `inLanguage` | string | X | 언어 코드 |
#### **가격/재고 정보 (offers)**
단일 객체 또는 배열로 전달합니다. 색상·사이즈 등 옵션별로 별도의 offer를 구성합니다.
필드
타입
필수
설명
@type
string
X
유형. 고정값: "Offer"
sku
string
O
옵션별 상품 코드
gtin
string
O
국제 표준 바코드
mpn
string
O
제조사 부품 번호
price
number
O
가격
priceCurrency
string
O
통화 코드 (ISO 4217, 예: "KRW", "JPY", "USD")
priceSpecification
object | array
X
가격 유형 상세
color
string
O
색상
size
string
O
사이즈
availability
string
O
재고 상태. enum 참고
availabilityStarts
string
O
판매 시작 일시 (UTC ISO 8601)
availabilityEnds
string
O
판매 종료 일시 (UTC ISO 8601)
inventoryLevel
object
X
재고 수량 정보
shippingDetails
object
X
배송 정보
image
object | array
O
상품 이미지
additionalProperty
array
X
추가 속성
#### **inventoryLevel 객체**
필드
타입
필수
설명
@type
string
X
유형. 고정값: "QuantitativeValue"
value
number
O
재고 수량
#### **shippingDetails 객체**
| 필드 | 타입 | 필수 | 설명 |
| -------- | ------ | -- | --------------------------------- |
| `@type` | string | X | 유형. 고정값: `"OfferShippingDetails"` |
| `weight` | object | O | 배송 무게 |
#### **shippingDetails.weight 객체**
| 필드 | 타입 | 필수 | 설명 |
| ---------- | ------ | -- | ------------------------------ |
| `@type` | string | X | 유형. 고정값: `"QuantitativeValue"` |
| `value` | number | O | 무게 값 |
| `unitCode` | string | O | 단위 코드 (예: `"KGM"`, `"GRM"`) |
#### **가격 유형 (priceSpecification)**
정가, 판매가, 권장소비자가격 등 다양한 가격 유형을 표현합니다.
필드
타입
필수
설명
@type
string
X
유형. 고정값: "UnitPriceSpecification"
priceType
string
O
가격 구분. enum 참고
price
number
O
가격
priceCurrency
string
O
통화 코드 (ISO 4217)
unitCode
string
O
단위 코드
#### **이미지 (image)**
| 필드 | 타입 | 필수 | 설명 |
| ---------------------- | ------- | -- | ----------------------------------------------------- |
| `@type` | string | X | 유형. 고정값: `"ImageObject"` |
| `representativeOfPage` | boolean | X | 대표 이미지 여부 (`true` = 대표 이미지) |
| `contentUrl` | string | O | 이미지 URL |
| `contentSize` | string | X | 파일 크기 |
| `width` | object | X | 너비 (`{ "@type": "QuantitativeValue", "value": 800 }`) |
| `height` | object | X | 높이 (`{ "@type": "QuantitativeValue", "value": 600 }`) |
#### **추가 속성 (additionalProperty)**
표준 필드로 표현할 수 없는 추가 정보를 담기 위한 확장 필드입니다.
상품 객체(`@graph[]`), 상품 설명(`description`), 가격 정보(`offers`) 내에서 사용할 수 있습니다.
필드
타입
필수
설명
@type
string
X
유형. 고정값: "PropertyValue"
propertyID
string
X
속성 아이디 (속성을 구분하는 키)
value
any
X
값 (string, number, boolean, array 등 모든 타입 가능)
{% hint style="warning" %}
상품 객체(`@graph[]`) 내로 값을 전달하기를 권장합니다.
{% endhint %}
**속성 레퍼런스**
아래는 `additionalProperty`에서 사용할 수 있는 권장 속성 목록입니다. 허용 값 예시를 참고하여 값을 맞춰서 보내주세요.
propertyID
value 타입
설명
허용 값 / 예시
gender
string
성별
"M" (Men), "W" (Women), "U" (Unisex), null (미지정)
season
string[]
계절
"Spring", "Summer", "Fall", "Winter" 중 선택
temperature
string
보관 방법
"Refrigerate" 등
platform_rate
number
플랫폼 수수료
0.15
unit
object
포장/무게 정보
하위 필드: unit, unit_quantity, weight_unit, weight_quantity
seller
object
판매자 정보
하위 필드: prefecture, seller_name
**`unit` 객체 구조**
| 하위 필드 | 타입 | 설명 | 예시 |
| ----------------- | ------ | ----- | --------------------------- |
| `unit` | string | 포장 단위 | `"box"`, `"pack"`, `"ea"` 등 |
| `unit_quantity` | number | 포장 수량 | `500` |
| `weight_unit` | string | 무게 단위 | `"g"`, `"ml"` |
| `weight_quantity` | string | 무게 값 | `"500"` |
**`seller` 객체 구조**
개발팀에 아래와 같이 문의해 주세요.
> "네이버 쇼핑 연동에 사용 중인 TSV 피드 파일 URL이 어떻게 되나요? S3나 CDN 등 외부 파일 서버를 사용 중이라면 해당 공개 URL도 함께 알려주세요."
***
## **처음 만드는 경우**
### **임대형 쇼핑몰**
임대형 쇼핑몰은 플랫폼에서 TSV 파일을 자동 생성하는 기능을 제공합니다. \
기능을 활성화한 후 표시되는 URL을 복사하여 gelatto에 입력하시면 됩니다.
#### **카페24**
1. 카페24 관리자 페이지 로그인
2. 판매 채널 → 네이버 → 네이버 쇼핑 설정 이동
3. 서비스 상태를 \[사용함]으로 선택 후 설정 사항 확인 후 저장
4. 최대 1시간 후 같은 화면에서 상품 DBURL 경로 확인 및 복사
{% hint style="info" %}
저장 직후에는 URL이 표시되지 않을 수 있습니다. 최대 1시간 후 다시 확인해 주세요.\
Naver EP URL 생성 및 gelatto 연동은 네이버 쇼핑파트너센터 계정이 없어도 가능합니다. \
파트너센터 계정은 네이버 쇼핑 상품 노출을 위한 별도 절차입니다.
{% endhint %}
#### **아임웹**
1. 아임웹 관리자 페이지 로그인
2. \[환경설정 > 데이터] 연결 이동
3. 설정 에 사용 설정 항목에서 네이버 쇼핑 사용 토글 옵션을 클릭해 켠 후 저장
4. 최대 1시간 후 같은 화면에서 DB URL 경로 확인 및 복사
{% hint style="info" %}
자세한 내용은 [아임웹](https://imweb.me/faq?mode=view\&category=29\&category2=40\&idx=65180)을 참고해 주세요.
{% endhint %}
#### **고도몰**
1. 고도몰 관리자 페이지 로그인
2. 마케팅 → 네이버 쇼핑 설정 이동
3. 사용 여부를 사용함으로 설정, 네이버 쇼핑 버전 설정을 v3.0(신규)으로 선택 후 저장
4. 같은 화면 네이버 쇼핑 상품 DB URL 항목에서 전체상품 URL 복사
{% hint style="info" %}
자세한 내용은 [고도몰](https://marketing.nhn-commerce.com/board/view.gd?postNo=203) 을 참고해 주세요.
{% endhint %}
### **자체 구축 쇼핑몰**
자체 구축몰을 사용하는 경우는 TSV를 자동 생성하는 기능이 없으므로, 개발팀에서 직접 구현해야 합니다.
* **TSV 파일 스펙**
* 1행: 컬럼 헤더
* 2행 이후: 상품 데이터 (상품 1개 = 1행)
* 구분자: 탭(`\t`)
* 인코딩: UTF-8 (BOM 없음)
{% hint style="info" %}
gelatto는 [네이버 EP 3.0](https://join.shopping.naver.com/misc/download/ep_guide.nhn) TSV 표준 포맷을 사용합니다.
{% endhint %}
#### **필수 필드**
컬럼명
설명
예시
id
상품 고유 ID
PRD_001
title
상품명
[브랜드] 반팔 티셔츠 화이트 L
price_pc
PC 판매가 (정수, 원화)
29000
link
상품 상세 URL
https://www.yourshop.com/product/1
image_link
대표 이미지 URL
https://cdn.yourshop.com/img/1.jpg
category_name1
카테고리 대분류
의류
shipping
배송비 (무료=0, 착불=-1)
3000
#### **선택 필드 (권장)**
| 컬럼명 | 설명 |
| ---------------- | ------------ |
| `price_mobile` | 모바일 판매가 |
| `normal_price` | 정가 (할인 전 가격) |
| `mobile_link` | 모바일 상품 URL |
| `add_image_link` | 추가 이미지 URL |
| `category_name2` | 카테고리 중분류 |
| `category_name3` | 카테고리 소분류 |
| `brand` | 브랜드명 |
| `review_count` | 리뷰 수 |
**TSV 샘플**
```
id title price_pc link image_link category_name1 shipping
PRD_001 [브랜드] 반팔 티셔츠 화이트 L 29000 https://www.yourshop.com/product/1 https://cdn.yourshop.com/img/1.jpg 의류 3000
PRD_002 [브랜드] 슬랙스 블랙 M 49000 https://www.yourshop.com/product/2 https://cdn.yourshop.com/img/2.jpg 의류 0
```
#### **개발팀 구현 체크리스트**
* 전체 상품을 TSV 형식으로 출력하는 엔드포인트 구현
* 파일 URL이 외부에서 HTTP/HTTPS로 접근 가능한지 확인
***
## **Naver EP URL 정상 여부 확인**
브라우저 주소창에 EP URL을 직접 입력했을 때 TSV 데이터가 텍스트로 표시되면 정상입니다.
```
O 정상 브라우저에서 탭 구분 텍스트 데이터가 표시됨
```
***
## **자주 묻는 질문**
Q. 카페24 등 임대형 쇼핑몰에서 EP URL을 사용하려면 네이버 쇼핑 파트너센터 계정이 꼭 있어야 하나요?
아닙니다. 카페24에서 EP URL 파일을 생성하고 gelatto에 연동하는 것은 파트너센터 계정 없이도 가능합니다. 파트너센터 계정은 네이버 쇼핑에 상품을 직접 노출하기 위한 별도 절차이며, gelatto가 EP URL로 상품 데이터를 수집하는 것과는 무관합니다.
Q. 상품이 추가·수정되면 TSV 파일도 업데이트해야 하나요?
임대형 쇼핑몰은 플랫폼에서 자동으로 갱신됩니다. 구축 쇼핑몰은 TSV 생성 로직이 항상 최신 데이터를 반영하도록 구현되어 있으면 됩니다. 이후 gelatto가 어드민에서 설정된 주기로 EP URL에 접근하여 자동으로 최신 데이터를 수집합니다.
Q. 컬럼 값에 탭이나 줄바꿈이 포함된 경우 어떻게 처리하나요?
탭(`\t`)과 개행(`\n`, `\r`) 문자는 반드시 공백( ) 처리 또는 제거 후 출력해야 합니다. 포함된 경우 파싱 오류로 해당 상품이 무효 처리됩니다.
# CS 지식 관리 백업
{% hint style="info" %}
**젠서 디스커버리 전용 기능**입니다.
{% endhint %}
CS 지식 관리는 에이전트가 고객 문의에 답변할 때 활용할 지식을 등록·관리하는 페이지입니다. 문서와 웹페이지로 등록하며, 에이전트는 등록한 지식을 바탕으로 답변합니다.
## **1. 지식 등록 방식**
지식은 두 가지 방식으로 등록하며, 각각 **문서** 탭과 **웹페이지** 탭에서 관리합니다.
구분
무엇을 등록하나
답변에 어떻게 쓰이나
문서
파일을 업로드
문서 내용을 답변에 직접 활용합니다.
웹페이지
페이지 주소(URL)를 등록
관련 질문에 링크를 안내하거나(링크 안내), 페이지 내용을 답변에 활용합니다(내용 반영).
{% hint style="warning" %}
등록 한도(문서·웹페이지 각 최대 300개)는 상한일 뿐 권장값이 아닙니다. 답변에 활용되는 자료가 많을수록 에이전트가 골라야 할 후보가 늘어 답변 정확도가 떨어지고 느려질 수 있습니다. 한도 안에서도 답변에 **꼭 필요한 지식만** 등록해 주세요.
{% endhint %}
***
## **2. 문서**
### **2-1. 등록**
문서를 업로드하면 내용을 처리(학습)한 뒤 답변에 반영됩니다. 처리에는 보통 수 분, 길어도 10분 안팎이 걸립니다.
항목
정책
파일 형식
TXT, Markdown, PDF, HTML, DOCX, PPTX, XLSX, XLSM
파일 용량
PDF는 파일당 최대 160MB, 그 외 형식은 10MB
파일 개수
한 번에 50개, 전체 300개까지
{% hint style="info" %}
같은 파일명·확장자의 파일을 다시 업로드하면 기존 문서를 교체할지 선택할 수 있습니다. (교체하면 중복으로 쌓이지 않습니다.)
{% endhint %}
### **2-2. 상태**
상태
의미
학습 중
내용을 처리하는 중입니다. 아직 답변에 반영되지 않습니다.
답변 반영
처리가 끝나 답변에 활용되고 있습니다.
답변 제외
답변에 활용하지 않습니다.
제외 중
답변에서 제외하는 처리 중입니다. 잠시 후 '답변 제외'로 바뀝니다.
반영 실패
처리에 실패했습니다. 다시 시도할 수 있습니다.
### **2-3. 답변 반영 관리**
문서별로 행 끝의 메뉴에서 답변에 활용할지 켜고 끌 수 있습니다.
* **답변에서 제외**: 답변에 활용하지 않습니다. 제외 처리에는 잠시 시간이 걸립니다.
* **답변에 반영**: 제외했던 문서를 다시 활용합니다. 다시 처리(학습)를 거칩니다.
* **다시 시도**: 반영에 실패한 문서를 다시 처리합니다.
### **2-4. 미리보기·다운로드·삭제**
* **미리보기**: 등록한 문서를 어드민에서 미리볼 수 있습니다. DOCX·PPTX·XLSX·XLSM 형식은 미리보기가 제공되지 않습니다.
* **다운로드**: 등록한 파일을 내려받을 수 있습니다.
* **삭제**: 삭제하면 답변에서 바로 제외되며, 되돌릴 수 없습니다.
***
## **3. 웹페이지**
### **3-1. 등록**
#### **등록 유형**
구분
링크 안내
내용 반영
답변 활용 방식
관련 질문에 링크를 함께 안내합니다(페이지 내용은 답변에 담기지 않습니다).
페이지 내용을 가져와 답변에 직접 활용합니다.
한 번에 등록
한 건씩
관련 페이지를 한 세트에 최대 5개까지
답변 반영
바로 반영됩니다.
내용을 처리(학습)한 뒤 반영됩니다.
#### **입력 항목**
항목
설명
URL
안내하거나 내용을 가져올 페이지 주소입니다.
웹페이지명
페이지를 구분하는 이름으로, 질문과 연결할 때 쓰입니다.
설명
페이지의 핵심 주제·키워드입니다. 질문과 연결할 때 쓰입니다. (링크 안내는 필수, 내용 반영은 선택)
유효기간
한시적으로 운영하는 페이지의 답변 참조 기간입니다. (선택)
{% hint style="info" %}
링크 안내는 입력한 **웹페이지명·설명**으로만 질문과 연결합니다. 고객이 실제로 쓰는 표현으로 적어 주세요.
{% endhint %}
#### **유효기간**
* 설정하지 않으면 상시 답변에 반영됩니다.
* 설정하면 지정한 기간에만 답변에 반영되고, 종료일이 지나면 자동으로 답변에서 제외됩니다.
* 이벤트·시즌처럼 한시적으로 운영하는 페이지에 사용합니다.
### **3-2. 상태**
상태
의미
답변 반영
답변에 활용되고 있습니다.
반영 예정
유효기간 시작일이 되면 자동으로 답변에 반영됩니다.
학습 중
내용을 처리하는 중입니다.
답변 제외
답변에 활용하지 않습니다.
제외 중
답변에서 제외하는 처리 중입니다. 잠시 후 '답변 제외'로 바뀝니다.
기간 만료
유효기간이 지나 자동으로 제외되었습니다.
반영 실패
처리에 실패했습니다. 다시 시도할 수 있습니다.
{% hint style="info" %}
'학습 중'·'제외 중'·'반영 실패'는 내용을 처리하는 **내용 반영 유형**에서만 나타납니다.
{% endhint %}
### **3-3. 답변 반영 관리**
웹페이지별로 행 끝의 메뉴에서 답변에 활용할지 켜고 끌 수 있습니다.
* **답변에서 제외**: 답변에 활용하지 않습니다. 제외 처리에는 잠시 시간이 걸립니다.
* **답변에 반영**: 제외했던 웹페이지를 다시 활용합니다. 내용 반영은 다시 처리(학습)를 거칩니다.
* **다시 시도**: 내용 반영으로 등록한 페이지가 반영에 실패하면 다시 처리합니다.
### **3-4. 미리보기·내용 업데이트·수정·삭제**
* **미리보기**: 내용 반영으로 등록한 페이지는 가져온 내용을 어드민에서 미리볼 수 있습니다.
* **내용 업데이트**: 내용 반영으로 등록한 페이지의 출처가 바뀌었을 때, 같은 URL의 내용을 다시 가져와 반영합니다. 목록에서 여러 항목을 골라 한 번에 업데이트할 수도 있습니다.
* **수정**: 웹페이지명·설명·유효기간은 바로 반영됩니다. 내용 반영에서 URL을 바꾸면 내용을 다시 가져오므로 처리(학습)를 거칩니다.
* **삭제**: 삭제하면 답변에서 바로 제외되며, 되돌릴 수 없습니다.
***
## **4. 답변 확인**
등록한 지식이 실제 답변에 어떻게 반영되는지는 헤더의 [**검색 미리보기**](https://help.genser.ai/products/search-preview)에서 확인할 수 있습니다.
***
## **자주 묻는 질문**
Q. 문서나 웹페이지를 등록했는데 답변에 언제 반영되나요?
문서와 웹페이지 '내용 반영'은 내용을 처리한 뒤 답변에 반영됩니다. 보통 수 분, 길어도 10분 안팎이 걸립니다. 웹페이지 '링크 안내'는 바로 반영됩니다.
Q. 링크 안내와 내용 반영은 무엇이 다른가요?
링크 안내는 관련 질문에 페이지 링크를 함께 안내하며, 페이지 내용 자체는 답변에 담기지 않습니다. 내용 반영은 페이지 내용을 가져와 답변에 직접 활용합니다.
Q. 특정 문서·웹페이지를 답변에서 빼고 싶습니다.
해당 항목을 행 끝의 메뉴에서 답변에서 제외하면 됩니다. 다시 활용하려면 답변에 반영으로 되돌릴 수 있습니다.
Q. 반영 실패로 표시됩니다.
처리에 실패한 상태입니다. 다시 시도해 주세요. 문서는 같은 문제가 반복되면 다른 파일로, 웹페이지는 URL이 올바른지 확인 후 다시 시도해 주세요.
Q. 등록한 페이지 내용이 바뀌면 자동으로 업데이트되나요?
자동으로 업데이트되지 않습니다. 내용 반영으로 등록한 페이지는 출처가 바뀌면 내용 업데이트로 직접 다시 가져와 주세요.
# Geo
GEO 생성 콘텐츠 조회
## GET /geo/contents
> GEO 생성 콘텐츠 페이지 조회
```json
{"openapi":"3.1.0","info":{"title":"GEO 콘텐츠 API","version":"0.1.0"},"tags":[{"name":"geo","description":"GEO 생성 콘텐츠 조회"}],"servers":[{"url":"https://api.genser.ai","description":"운영"},{"url":"https://api-stg.gelatto.ai","description":"스테이징"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"api-key","description":"발급받은 API 키"}},"schemas":{"GeoContentPage":{"properties":{"vendor_id":{"type":"string","title":"Vendor Id"},"total":{"type":"integer","title":"Total","description":"이 벤더의 전달 대상 전체 건수(조회 시점)"},"size":{"type":"integer","title":"Size","description":"요청 페이지 크기"},"items":{"items":{"$ref":"#/components/schemas/GeoContentItem"},"type":"array","title":"Items"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"마지막 항목 위치. has_more 와 무관하게 보관해 두고 다음 호출의 cursor 로 넘기면 그 이후에 생성·갱신된 항목만 받는다(증분 폴링)"},"has_more":{"type":"boolean","title":"Has More"}},"type":"object","required":["vendor_id","total","size","items","has_more"],"title":"GeoContentPage"},"GeoContentItem":{"properties":{"sku":{"type":"string","title":"Sku"},"version":{"type":"integer","title":"Version","description":"생성 횟수. 같은 sku 가 더 큰 version 으로 다시 오면 갱신본이므로 덮어쓸 것"},"generated_at":{"type":"string","format":"date-time","title":"Generated At","description":"생성(갱신) 시각. 커서 정렬 기준"},"payload":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Payload","description":"고객 deliverable — final/{sku}.json 의 payload 부분(벤더별 스키마: sku/name/brand/canonical_url/summary/meta_description/alt_texts/jsonld ...). 조회 실패 시 null 이고 error 에 사유가 실린다. 단건 API 로 재조회 가능"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"payload_not_found / payload_malformed / payload_unavailable"}},"type":"object","required":["sku","version","generated_at"],"title":"GeoContentItem"},"ErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/ErrorBody"}},"type":"object","required":["error"],"title":"ErrorResponse"},"ErrorBody":{"properties":{"code":{"type":"string","title":"Code","description":"에러 식별자. 분기 처리는 이 값으로 한다. 목록은 각 응답 설명 참고"},"message":{"type":"string","title":"Message","description":"사람이 읽는 설명. 문구는 예고 없이 다듬어질 수 있으므로 분기에 쓰지 않는다"},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail","description":"원인을 좁히는 부가 정보. 없으면 null"}},"type":"object","required":["code","message"],"title":"ErrorBody"}}},"paths":{"/geo/contents":{"get":{"tags":["geo"],"summary":"GEO 생성 콘텐츠 페이지 조회","parameters":[{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"이전 응답의 next_cursor. 그 위치 이후에 생성·갱신된 항목만 반환. 비우면 처음부터","title":"Cursor"},"description":"이전 응답의 next_cursor. 그 위치 이후에 생성·갱신된 항목만 반환. 비우면 처음부터"},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"cursor 대신 날짜로 시작점 지정. KST 기준 YYYYMMDD(예: 20260901)이며 그 날 00:00 KST 이후 생성·갱신된 항목부터 반환한다. 하이픈 표기(2026-09-01)도 허용. cursor 와 동시 사용 불가","title":"Since"},"description":"cursor 대신 날짜로 시작점 지정. KST 기준 YYYYMMDD(예: 20260901)이며 그 날 00:00 KST 이후 생성·갱신된 항목부터 반환한다. 하이픈 표기(2026-09-01)도 허용. cursor 와 동시 사용 불가"},{"name":"size","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"페이지 크기. 기본 50, 최대 200","title":"Size"},"description":"페이지 크기. 기본 50, 최대 200"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoContentPage"}}}},"400":{"description":"`INVALID_CURSOR` — cursor 값이 유효하지 않음\n`INVALID_PAGE_SIZE` — size 가 1~200 범위를 벗어남\n`INVALID_SINCE` — since 가 KST YYYYMMDD 형식이 아니거나 존재하지 않는 날짜\n`CURSOR_AND_SINCE_CONFLICT` — cursor 와 since 를 함께 보냄","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED` — api-key 가 없거나 유효하지 않음","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`VALIDATION_FAILED` — 요청 형식 오류. detail 에 문제가 된 필드가 실린다","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`TOO_MANY_REQUESTS` — 동시 요청 제한 초과. Retry-After 초 후 같은 커서로 재시도 — 커서 페이지네이션은 순차 호출이 정상","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_SERVER_ERROR` — 처리되지 않은 서버 오류","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE` — 이 환경에 GEO 콘텐츠가 설정되지 않음","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## GET /geo/contents/{sku}
> GEO 생성 콘텐츠 단건 조회
```json
{"openapi":"3.1.0","info":{"title":"GEO 콘텐츠 API","version":"0.1.0"},"tags":[{"name":"geo","description":"GEO 생성 콘텐츠 조회"}],"servers":[{"url":"https://api.genser.ai","description":"운영"},{"url":"https://api-stg.gelatto.ai","description":"스테이징"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"api-key","description":"발급받은 API 키"}},"schemas":{"GeoContentItem":{"properties":{"sku":{"type":"string","title":"Sku"},"version":{"type":"integer","title":"Version","description":"생성 횟수. 같은 sku 가 더 큰 version 으로 다시 오면 갱신본이므로 덮어쓸 것"},"generated_at":{"type":"string","format":"date-time","title":"Generated At","description":"생성(갱신) 시각. 커서 정렬 기준"},"payload":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Payload","description":"고객 deliverable — final/{sku}.json 의 payload 부분(벤더별 스키마: sku/name/brand/canonical_url/summary/meta_description/alt_texts/jsonld ...). 조회 실패 시 null 이고 error 에 사유가 실린다. 단건 API 로 재조회 가능"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"payload_not_found / payload_malformed / payload_unavailable"}},"type":"object","required":["sku","version","generated_at"],"title":"GeoContentItem"},"ErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/ErrorBody"}},"type":"object","required":["error"],"title":"ErrorResponse"},"ErrorBody":{"properties":{"code":{"type":"string","title":"Code","description":"에러 식별자. 분기 처리는 이 값으로 한다. 목록은 각 응답 설명 참고"},"message":{"type":"string","title":"Message","description":"사람이 읽는 설명. 문구는 예고 없이 다듬어질 수 있으므로 분기에 쓰지 않는다"},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail","description":"원인을 좁히는 부가 정보. 없으면 null"}},"type":"object","required":["code","message"],"title":"ErrorBody"}}},"paths":{"/geo/contents/{sku}":{"get":{"tags":["geo"],"summary":"GEO 생성 콘텐츠 단건 조회","parameters":[{"name":"sku","in":"path","required":true,"schema":{"type":"string","title":"Sku"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoContentItem"}}}},"401":{"description":"`UNAUTHORIZED` — api-key 가 없거나 유효하지 않음","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`GEO_CONTENT_NOT_FOUND` — 제공 대상이 아닌 sku","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`VALIDATION_FAILED` — 요청 형식 오류. detail 에 문제가 된 필드가 실린다","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`TOO_MANY_REQUESTS` — 동시 요청 제한 초과. Retry-After 초 후 같은 커서로 재시도 — 커서 페이지네이션은 순차 호출이 정상","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`GEO_PAYLOAD_UNAVAILABLE` — 콘텐츠 본문을 읽지 못함. detail 에 사유\n`INTERNAL_SERVER_ERROR` — 처리되지 않은 서버 오류","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE` — 이 환경에 GEO 콘텐츠가 설정되지 않음","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
# 임시-content api 사용 안내용
### Shopify 사용자 안내
Shopify는 기본적으로 **Google & YouTube 앱**을 통해 GMC와 연동합니다. 이 방식은 Shopify가 GMC에 직접 상품 데이터를 API로 전송하며, GMC에서 `Content API` 피드로 표시됩니다. 파일 URL이 생성되지 않으므로 파일 피드 URL 방식은 사용할 수 없습니다.
**gelatto는 Shopify 고객사를 위해 Merchant API 방식을 지원합니다.** 파일 URL 없이도 GMC에 올라간 상품 데이터를 gelatto가 직접 수집할 수 있습니다.
#### 연동 방법
Merchant API 방식은 고객사가 별도로 파일을 만들거나 URL을 생성할 필요가 없습니다. 아래 정보를 gelatto 담당자에게 전달해 주세요.
1. **Google Merchant Center ID** (Merchant Center 우측 상단에서 확인)
2. **gelatto 계정에 대한 GMC 접근 권한 부여**
권한 부여 방법은 아래와 같습니다.
1. [Google Merchant Center](https://merchants.google.com/) 로그인
2. 좌측 메뉴 **설정 → 계정 액세스** 이동
3. **사용자 추가** 클릭 후 gelatto 담당자 이메일 입력
4. 권한 수준 **표준** 선택 후 저장
권한 부여 후 gelatto 담당자에게 Merchant Center ID와 함께 완료 사실을 알려주세요. 이후 연동 설정은 gelatto 측에서 처리합니다.
***
### Merchant API 방식 안내
카페24·아임웹·Shopify는 GMC와 Content API 방식으로 연동되어 파일 피드 URL이 생성되지 않습니다. gelatto는 이 경우를 위해 **Merchant API 방식**을 지원합니다. 파일 URL 없이도 GMC에 올라간 상품 데이터를 gelatto가 직접 수집할 수 있습니다.
#### 플랫폼별 연동 구조
플랫폼
GMC 연동 방식
gelatto 수집 방식
카페24
구글 채널 앱 → Content API
Merchant API
아임웹
구글 채널 앱 → Content API
Merchant API
Shopify
Google & YouTube 앱 → Content API
Merchant API
#### 연동 방법
Merchant API 방식은 고객사가 별도로 파일을 만들거나 URL을 생성할 필요가 없습니다. 아래 두 가지를 gelatto 담당자에게 전달해 주세요.
1. **Google Merchant Center ID** (Merchant Center 우측 상단에서 확인)
2. **gelatto 계정에 대한 GMC 접근 권한 부여**
권한 부여 방법은 아래와 같습니다.
1. [Google Merchant Center](https://merchants.google.com/) 로그인
2. 좌측 메뉴 **설정 → 계정 액세스** 이동
3. **사용자 추가** 클릭 후 gelatto 담당자 이메일 입력
4. 권한 수준 **표준** 선택 후 저장
{% hint style="info" %} 권한 부여 후 gelatto 담당자에게 Merchant Center ID와 함께 완료 사실을 알려주세요. 이후 연동 설정은 gelatto 측에서 처리합니다. {% endhint %}
버튼을 클릭하여 EP URL과 연동 스케줄을 설정합니다.
버튼을 클릭하여 실행합니다.
당일 즉시 연동 잔여 횟수는 연동 정보에서 확인할 수 있으며, 제공 횟수는 **매일 00시(자정)를 기준으로 자동 초기화**됩니다.
버튼을 클릭하여 실행합니다.
* **1일 제공 횟수:** 3회
* 당일 즉시 연동 잔여 횟수는 연동 정보에서 확인할 수 있으며, 제공 횟수는 **매일 00시(자정)를 기준으로 자동 초기화**됩니다.
***
## **4. API**
젤라또·네이버 커머스·구글 머천트 API를 통해 상품 데이터를 실시간으로 전송하는 방식입니다. 네이버 EP나 GMC Feed와 달리 별도의 스케줄이나 토글 설정 없이, **API 호출 시점에 즉시 데이터가 연동**됩니다.
버튼을 클릭하여 [**API 키 발급**](/settings/api-key) 페이지로 이동한 뒤, 새로운 API 키를 발급 받을 수 있습니다.
키 발급이 완료되면 카드 화면에 마스킹된 API 키와 
버튼이 표시됩니다.
보기
복사
라벨이 표시됩니다.
버튼을 클릭하여 새로운 계정을 생성할 수 있습니다.
아이콘을 클릭하면, 해당 계정을 관리할 수 있는 메뉴가 나타납니다.
수정
차단
차단 해제
2단계 인증 초기화
주관리자 권한 이관
삭제
버튼을 클릭하여 허용 IP를 등록해 주세요. 현재 접속 IP는 우측에서 확인할 수 있으며, 본인 계정의 접근 차단(Self-Lockout) 방지를 위해 설정 저장 시 현재 접속 IP가 허용 목록에 포함되어 있어야 합니다.
라벨이 표시됩니다.
{% hint style="warning" %}
주관리자 계정에 한해, 제한된 네트워크 환경에서 이메일 인증으로 로그인할 수 있습니다. 단, 보안상 이 방법은 권장하지 않으며 불가피한 경우에만 사용해 주세요.
{% endhint %}
{% endtab %}
{% endtabs %}
#### **허용 IP 목록**
