# genser 가이드

genser는 이커머스 사이트 내 자연어 질의를 분석해 최적의 상품을 제안하는 **‘생성형 AI 검색’**과, 고객의 검색 의도를 학습하여 상품 페이지에 설득력 있는 콘텐츠를 자동 생성하는 **‘AI Comment’** 기능을 핵심으로 합니다. 이를 통해 기업은 고객의 구매 여정을 단축할 뿐만 아니라, 생성된 콘텐츠를 **GEO(생성형 엔진 최적화)** 자산으로 활용하여 미래 AI 트래픽을 선점할 수 있습니다.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="image">Cover image</th></tr></thead><tbody><tr><td>genser <strong>이해하기</strong></td><td>genser가 처음인 분을 위해 이해를 돕기 위한 가이드입니다.</td><td></td><td><a href="/pages/6uvu1lmzHTiQSNFDg0XC">/pages/6uvu1lmzHTiQSNFDg0XC</a></td><td><a href="/files/wLnXFhJgKyiIfRxRPJxZ">/files/wLnXFhJgKyiIfRxRPJxZ</a></td></tr><tr><td><strong>연동 이해하기</strong></td><td>genser를 연동하는 전반적인 플로우에 대해 알 수 있습니다. </td><td></td><td><a href="/pages/XD11BoYcivIqj9AjpMCD">/pages/XD11BoYcivIqj9AjpMCD</a></td><td><a href="/files/tH4wLk7fxTqmFwxosuya">/files/tH4wLk7fxTqmFwxosuya</a></td></tr><tr><td>genser <strong>만들기</strong></td><td>genser 인스턴스를 만드는 방법에 대해 알 수 있습니다. </td><td></td><td><a href="/pages/KiTCQdCzlnU0Un0dtoq3">/pages/KiTCQdCzlnU0Un0dtoq3</a></td><td><a href="/files/cKezRUtcYfh04GPG0dE8">/files/cKezRUtcYfh04GPG0dE8</a></td></tr></tbody></table>

> **안내:** 기존의 genser S(키워드형)와 genser G(생성형) 인스턴스 구분은 순차적으로 통합 예정입니다.

### **더 궁금한 점이 있으신가요?**

***

자주묻는 질문을 통해 궁금증을 해결해 보세요!

<a href="/pages/DSQqnsAqJPnIRyPgQJ1S" class="button secondary">자주 묻는 질문</a>

***

genser에 대해서 제품소개서를 받아보고싶다면 신청해 보세요!

<a href="https://www.genser.ai/request" class="button secondary">제품 소개서 신청</a>

***

genser 홈페이지 바로가기

<a href="https://www.genser.ai/" class="button secondary">genser 더 알아보기</a>

**👇 다음 genser 가이드를 읽고 AI로 새로운 검색 혁신을 만들어 보세요!**


# genser 이해하기

<figure><img src="/files/qyuSYaBPJe8aMSiqH2mK" alt=""><figcaption></figcaption></figure>

## 핵심 기능 3가지

### **1. GenAI보다 더 나은 검색 경험 제공**

> *"검색은 결과의 나열이 아닌, 설득력 있는 구매 경험이 됩니다."*

* **문맥과 의도의 깊은 이해:** genser는 고객의 질문 속 문맥과 조건, 숨겨진 의도까지 파악하여 단순 답변 이상의 가치를 제공합니다.
* **추천의 근거와 이유 제시:** 상품을 단순히 나열하는 대신, 왜 이 상품이 고객에게 최적의 선택인지 명확한 근거를 제시하여 신뢰도를 높입니다.

### **2. 의도(Intent) 데이터를 새로운 콘텐츠로 생성**

> *"검색 데이터가 곧, 기업의 경쟁력이 됩니다."*

* **Intent Data의 구조화:** 일회성 검색 로그를 넘어, 고객이 "왜, 어떤 조건으로" 상품을 찾는지에 대한 의도 데이터를 수집하고 자산화합니다.
* **선순환 구조:** 리뷰나 단순 행동 데이터만으로는 파악할 수 없는 니즈를 공략하여, 검색이 쌓일수록 콘텐츠와 매출이 함께 향상됩니다.

### **3. Zero-Click 대응을 위한 GEO 향상**

> *"AI 검색 엔진이 선택하는 콘텐츠로, 미래 AI 트래픽을 선점합니다."*

* **GEO(생성형 엔진 최적화) 강화:** 수집된 의도 데이터를 기반으로 상품 페이지에 ‘AI Comment’와 같은 고부가가치 콘텐츠를 자동 생성합니다.
* **미래 유입 경로 확보:** 검색 의도와 고객 행동 데이터에 기반한 콘텐츠를 통해 AI 검색의 인용률을 높이고, 새로운 트래픽을 선점합니다.

## genser만의 차별점

### **1. 검색 로직과 패턴, 그리고 커버리지**

genser는 고객이 명확히 표현하지 못한 요구까지 해석하는 AI 검색으로, 모든 상품군에서 최적의 선택을 근거와 함께 제시합니다. 필터링에 소모되던 고객들의 탐색 과정을 설득력 있는 추천으로 전환하여 구매 전환율과 고객 생애 가치를 동시에 높입니다.

* **숨겨진 요구 (불분명한 니즈):**
  * *예: “캠핑 입문자인데, 무엇을 준비해야 하는 거지?”* → 다양한 카테고리에서 맞춤 상품 추천
* **드러난 요구 (상세 조건 및 스펙):**
  * *예: “30대 남자고 30만 원 이하의 네이비 컬러 자켓 추천해 줘”* → 복잡한 조건 검증과 정답 제시 및 추천 이유 설명

#### **상품군별 특화 전략**

* **고관여 / 복잡 상품 (가전, 가구, PC/IT 기기 등)**
  * **The Consultant:** 전문 지식으로 고객의 의도를 파악해 검색 실패를 방지하는 가이드 역할
  * **The Expert:** 복잡하고 상세한 속성과 스펙을 완벽하게 검증하여 정확한 결과를 도출
* **저관여 / 단순 상품 (패션, 식품, 생활용품 등)**
  * **The Curator:** 상황(TPO)과 감성에 딱 맞는 센스 있는 제안을 통해 고객 맞춤 큐레이팅 제공
  * **The Fast Finder:** 고민의 시간을 줄여 최단 시간 내에 최적의 상품을 제공

### **2. 가장 빠른 정답의 길로 안내, Auto Routing**

genser의 **Auto Routing**은 고객의 입력을 실시간으로 분석해 단순 키워드 탐색과 AI 의도 분석 중 최적의 경로를 자동 선택합니다. 검색 상황에 맞는 유연한 흐름을 제공함으로써 불필요한 탐색을 줄이고, 고객이 가장 짧은 거리로 만족스러운 결과에 도달하도록 돕습니다.

* **키워드 입력 시:** AI가 이를 인식하여 빠르고 정확한 상품 리스트를 즉시 제공합니다.
* **문장형 질문 입력 시:** AI가 질문의 맥락을 분석하여 이유와 근거가 포함된 답변을 생성합니다.

### **3. 근거 있는 추천과 확장된 발견**

genser는 검색 결과에 대해 브랜드 톤앤매너에 맞춘 추천 이유를 명확히 제시해 고객의 신뢰를 높이고 선택의 피로를 줄입니다. 여기에 연관 키워드와 제안 질문을 더해 고객이 미처 인지하지 못한 니즈까지 확장하며, 가장 빠른 경로로 구매 결정에 도달하도록 돕습니다.

* **추천 이유 설명:** 검색 결과에 대한 이유와 핵심 근거를 설명
* **연관 키워드 제공:** 고객의 검색과 연결된 맥락의 키워드 제공
* **제안 질문:** 고객의 탐색 흐름에 맞는 다음 질문을 제안

### **4. Zero-Click의 위기를 기회로 바꾸는 GEO 전략, AI Comment**

**genser AI Comment**는 실제 검색 의도와 행동 데이터를 기반으로 상품에 대한 신뢰도 높은 콘텐츠를 자동 생성합니다. 이렇게 만들어진 콘텐츠는 상품의 설득력을 높이는 동시에, 외부 AI 검색 환경(GEO)에서 채택되는 정보로 확장되어 자사몰로의 안정적인 유입을 이끌어 냅니다.

* **Step 1 - Input:** 사용자가 입력한 자연어 검색 질의 수집
* **Step 2 - Verification:** 검색 결과에 대한 사용자 클릭을 통해 정답 여부 검증
* **Step 3 - Output:** 검증된 의도 데이터를 바탕으로 상품 페이지에 구체적인 AI Comment 생성


# 새로운 소식


# 제안 질문 오픈! (2025.12.23)

<figure><img src="/files/pullVf6wmUWrQnl6YqPe" alt=""><figcaption></figcaption></figure>

고객의 검색 의도를 파악하여, 자연스럽게 다음 검색으로 이어질 수 있도록 질문을 문장 형태로 제안합니다.

***

#### 왜 만들었나요?

**검색의 고민을 끝내고, 끊김 없는 탐색을 완성하기 위해**

지금까지는 고객이 상품을 찾기 위해 매번 스스로 다음 검색어를 고민하고 입력해야 했습니다. "캠핑 의자를 검색했는데, 이제 뭘 더 봐야 하지?", "어떤 브랜드를 비교해야 하지?"와 같은 막막함은 쇼핑을 중단시키는 원인이 되기도 합니다.

제안 질문은 이러한 고민을 해결하기 위해 기획되었습니다. AI가 고객의 검색어 이면에 담긴 맥락을 정교하게 분석하고, 숨겨진 의도를 예측하여 '브랜드 비교', '사용 상황 구체화' 등 가장 최적화된 다음 탐색 경로를 먼저 제시합니다. 고객의 검색 여정이 끊김 없이 자연스럽게 이어지도록 만들어 보세요.

***

#### 무엇이 좋아지나요?

1\. 4가지 전략으로 완성하는 탐색의 선순환! 단순한 연관어 나열이 아닙니다. 비즈니스 목적에 맞는 4가지 핵심 질문 유형으로, 고객이 제안을 선택하고 다시 탐색을 이어가는 검색과 탐색의 선순환을 만들어냅니다.&#x20;

* 구매 의도 확인: 검색어 뒤에 숨겨진 '진짜 의도'를 파악해 구체적인 상황을 제안합니다.
  * *(검색)* "친구 집에 갈 때 가져갈 5만원대 선물"
  * → (제안) "센스 있는 집들이 선물 보여줘"
* 브랜드 좁히기: 검색 결과 내 선호 브랜드를 연결해 탐색 범위를 최적화합니다.
  * *(검색)* "요즘 인기 있는 가벼운 런닝화"
  * → (제안) "나이키 제품만 모아서 보여줘"
* 속성 좁히기: 가격, 색상, 소재 등 디테일한 취향을 반영해 원하는 결과로 좁혀줍니다.
  * *(검색)* "봄에 입기 좋은 화사한 가디건"
  * → (제안) "파스텔 톤 색상만 보여줘"
* 리뷰/랭킹 추천: 검증된 기준을 제시하여 탐색에 확신을 더합니다.
  * *(검색)* "튼튼하고 오래 쓰는 캠핑 의자"
  * → (제안) "평점 4.5점 이상인 상품만 보여줘"

2\. 상황에 맞춰 똑똑하게 변하는 노출 로직을 사용합니다. 검색 결과가 적을 때는 가장 중요한 질문만, 결과가 많을 때는 다양한 선택지를 제공합니다. genser는 검색 결과 수를 판단하여 질문 유형을 자동으로 최적화해 제안합니다.

***

더 자세한 사용법이 궁금하다면?

{% content-ref url="/pages/KiTCQdCzlnU0Un0dtoq3" %}
[인스턴스 만들기](/ai-search/genser-instance/create)
{% endcontent-ref %}


# 데이터 연동 현황 기능 오픈! (2025.11.25)

<figure><img src="/files/Cae9TBoGZ4TUyaoGNapB" alt=""><figcaption></figcaption></figure>

genser 어드민에서 데이터가 정상적으로 연동되고 있는지 실시간 지표로 확인하고, 실패 원인까지 한눈에 파악하세요.&#x20;

***

#### 왜 만들었나요?

지금까지는 상품 데이터가 genser에 연동 되어, 실제 검색에 잘 반영되었는지 확인하기가 어려웠습니다.&#x20;

"방금 등록한 신상품이 왜 검색이 안 되지?", "혹시 중간에 오류가 나서 누락된 건 아닐까?" 이런 불안함을 해소하고 데이터 파이프라인을 확인할 수 있게 보여드리기 위해 '데이터 연동 현황' 대시보드를 만들었습니다.&#x20;

***

#### 무엇이 좋아지나요?

1. **데이터 흐름을 한눈에:** 복잡한 로그를 뒤질 필요가 없습니다. 인스턴스를 선택하기만 하면 4가지 핵심 지표가 즉시 표시됩니다.&#x20;
   1. 전체 아이템 수
   2. 최근 접수 된 아이템 수
   3. 연동 성공 아이템 수
   4. 품절 아이템 수
2. **인스턴스별 독립 확인:** 운영 중인 인스턴스가 여러 개여도 걱정 없습니다. 화면 상단에서 등록한 인스턴스를 선택할 수 있고 전환하며 각각의 인스턴스별 데이터 현황을 모니터링할 수 있습니다.&#x20;

***

더 자세한 사용법이 궁금하다면?

{% content-ref url="/pages/aS0gRHYFxaLnKnf8Dp4D" %}
[데이터 연동 현황](/ai-search/data)
{% endcontent-ref %}


# 검색 결과 미리보기 오픈! (2025.11.05)

<figure><img src="/files/eBPpBAIPRH9KrkWxnJeE" alt=""><figcaption></figcaption></figure>

설정한 검색 로직이 실제로 어떻게 보이는지 시뮬레이션하고, 두 개의 인스턴스 결과를 한 화면에서 비교할 수 있는 '검색 결과 미리보기' 기능이 추가되었습니다.

***

#### 왜 만들었나요?

검색 인스턴스를 처음 설정하고 변경할 때마다 "이게 우리 검색 결과 화면에서 어떻게 보일지" 불안하셨나요? 혹은 기존 genser 인스턴스와 새로운 genser 인스턴스의 성능 차이를 눈으로 직접 확인하고 싶으셨나요? 라이브 서비스에 영향을 주지 않으면서, 검색 품질을 검증하고 최적화할 수 있는 전용 테스트 공간이 필요했습니다.

***

#### 무엇이 좋아지나요?

1. **실제와 동일한 시뮬레이션:** 인스턴스를 선택하고 "코트", "봄 원피스" 같은 검색어를 입력해 보세요. 상품 이미지, 가격, 브랜드 정보 등 실제 고객이 보게 될 화면 구성을 그대로 확인할 수 있습니다.&#x20;
2. **A/B 비교를 한눈에:** 화면을 분할하여 두 개의 검색 인스턴스를 동시에 띄울 수 있습니다.&#x20;
3. **디테일한 화면 제어:** 인스턴스 설정을 수정하고 실시간으로 반영된 결과를 확인할 수 있습니다. 선택한 인스턴스 상단의 \[설정] 메뉴를 통해 인스턴스 설정을 조작해 가며 원하는 설정 값을 발견할 수 있습니다.&#x20;

***

더 자세한 사용법이 궁금하다면?

{% content-ref url="/pages/E4xRXzp83NQPUEK84X8Q" %}
[검색 결과 미리보기](/ai-search/srp)
{% endcontent-ref %}


# 연동 시작하기

<figure><img src="/files/L3FTdwr9HM8kXdhVw0Vo" alt=""><figcaption></figcaption></figure>

데이터 연결부터 실제 검색 구현까지 아래의 순서대로 따라오시면 됩니다.

{% stepper %}
{% step %}

## 인스턴스 준비하기

가장 먼저 독립적인 검색 엔진 공간인 '인스턴스'를 생성해야 합니다.

* **어드민 접속:** [genser 어드민 페이지](https://admin.groobee.io/genser/login)에 로그인합니다.
* **인스턴스 생성:** [인스턴스 설정 메뉴](https://admin.groobee.io/genser/aiSearch)에서 \[만들기] 버튼을 클릭하여 검색 엔진을 생성합니다.
* **인스턴스 키 확인:** 인스턴스 생성 완료 후, `인스턴스 목록 > 관리도구 > 코드복사` 하여 Instance Key를 별도로 기록해 두세요. 추후 연동 시 필요합니다.
  {% endstep %}

{% step %}

## 상품 데이터 연동하기

AI가 학습할 수 있도록 상품 정보를 genser로 전송합니다. 현재는 **API 직접 연동 방식**을 지원합니다.

#### **A. API 직접 연동 (현재 지원)**

개발자가 직접 상품 데이터를 genser 서버로 전송하는 방식입니다. [API 직접 연동](/integration/product-data-integration/standard-api)을 참고하여 연동해 주세요.

#### **B. 간편 URL 파일 연동 (오픈 예정)**

GMC, 네이버 쇼핑(EP) 등에서 사용하는 상품 피드 URL(TSV, XML)을 등록해 두면 자동으로 수집하는 방식입니다. 별도의 전송 작업 없이, 등록해 둔 피드 파일(URL)의 내용만 최신 상태로 유지해 주세요.
{% endstep %}

{% step %}

## 데이터 전처리 및 인덱싱 기다리기

데이터 전송이 완료되면 genser의 AI Data 팀에서 데이터 최적화 작업을 수행합니다.

* **완료 대기:** 전처리가 완료될 때까지 기다려 주세요. 데이터 규모에 따라 처리에 일정 시간이 소요될 수 있습니다. 처리가 완료되면 연동 완료 알림 메일을 드립니다. 이메일은 genser 어드민 설정에서 등록한 '관리자 메일'로 전송됩니다. &#x20;

{% hint style="info" %}
**genser가 하는 일**&#x20;

전송된 상품 데이터를 AI가 잘 이해할 수 있도록 정제하고 분류하는 전처리를 수행합니다.
{% endhint %}
{% endstep %}

{% step %}

## 검색 품질 테스트하기

데이터 처리가 끝났다면, 라이브 적용 전에 검색 품질을 검증합니다.

* **메뉴 이동:** 어드민의 [검색 결과 미리보기 메뉴](https://admin.groobee.io/genser/simulator)로 이동합니다.
* **검색 테스트:** "30대 여자 오피스 출근용 원피스 추천해줘", "3인 가족 캠핑 의자 보여줘" 등 자연어로 검색 질문을 입력해보세요. 우리 상품이 의도에 맞게 검색되는지, AI 설명이 적절한지 미리 확인할 수 있습니다.
  {% endstep %}

{% step %}

## 프론트엔드 설치 및 UI 구현

검증이 완료되었다면 이제 실제 고객이 사용할 검색 화면을 구현합니다.

* **스크립트 설치:** HTML 헤더에 [genser SDK 스크립트](https://docs.genser.ai/integration/installation)를 삽입합니다.
* **UI 구현:** 고객사 가이드에 맞춰 검색창과 검색 결과 리스트 UI를 자유롭게 구성합니다. genser는 검색 결과 데이터를 API로 제공하므로, 디자인의 제약 없이 커스텀 가능합니다.
  {% endstep %}
  {% endstepper %}


# 상품 데이터 연동하기

<figure><img src="/files/UpdFZfbMxyNrwclvPTQE" alt=""><figcaption></figcaption></figure>

{% hint style="success" %}
**genser만의 데이터 인텔리전스 노하우**

genser는 단순 연동을 넘어, 자체 멀티모달 엔진으로 데이터를 최적화합니다. 상세 페이지가 이미지여도 텍스트를 추출하는 OCR과, 상품 이미지를 스스로 해석해 설명을 생성하는 Captioning 기술 등을 적용합니다. 이러한 고도화된 전처리를 통해 원천 데이터의 한계를 보완하고 AI가 완벽히 이해할 수 있는 고품질 메타 데이터로 재가공하여 최상의 검색 품질을 보장합니다.
{% endhint %}

{% hint style="success" %}
**상품 데이터 연동 방식 안내**

상품 데이터는 운영 환경에 맞춰 아래 두 가지 방식 중 하나를 선택하거나 병행하여 연동이 가능합니다.
{% endhint %}

{% hint style="info" %}
**데이터 반영 시점 안내**

API로 전송된 데이터는 즉시 검색 결과에 노출되지 않으며, 해당 국가의 현지 시간으로 **매일 오전 00:15**에 실행되는 일괄 처리(Batch) 작업을 통해 검색 엔진에 반영됩니다.
{% endhint %}

#### 이미 운영 중인 상품 피드(URL)가 있나요?

네이버 쇼핑, 구글 쇼핑 등 기존에 사용 중인 상품 피드 URL이 있다면 별도의 추가 개발 없이 즉시 연동할 수 있습니다. 대량의 데이터를 정기적으로 자동 수집하기에 가장 적합한 방식입니다.

* **특징:** 낮은 개발 난이도, 정기적인 자동 업데이트(Batch), 기존 피드 재활용 가능
* **추천 대상:** 사이트 운영 시스템에서 상품 피드 URL 추출이 가능한 경우

{% content-ref url="/pages/Rk5fj0loPbRPzUPJFRFY" %}
[(서비스 준비 중) 상품 데이터 파일 연동](/integration/product-data-integration/feed-file-import)
{% endcontent-ref %}

***

#### 상품 정보를 genser에 전달해야 하나요?

상품의 생성, 수정, 삭제 이벤트를 genser 서버로 전송하는 방식입니다. 복잡한 비즈니스 로직에 맞춰 유연하게 연동할 수 있습니다.

* **특징:** 높은 연동 자유도, CloudEvents 표준 규격 준수
* **추천 대상:** 상품 정보를 genser에 전달해야 하는 경우

{% content-ref url="/pages/Dqak5rR85LWKahJHsLSF" %}
[표준 API 직접 연동](/integration/product-data-integration/standard-api)
{% endcontent-ref %}


# (서비스 준비 중) 상품 데이터 파일 연동

<figure><img src="/files/AvPvaWCJ2qQl6ZD8ugxY" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
상품 데이터 파일 URL 연동 기능은 2026년 1월 말 오픈 예정입니다.&#x20;
{% endhint %}

genser는 고객사가 이미 보유하고 있는 상품 정보 파일(GMC, 네이버 EP 등)을 활용하여 별도의 복잡한 개발 없이도 상품데이터를 연동할 수 있습니다.&#x20;

***

고객사 웹 서버에 배포된 상품 피드 URL을 관리자 페이지에 등록하여 데이터를 자동 수집(Fetch)하는 방식입니다.

이미 **구글 머천트 센터(GMC)** 나 **네이버 쇼핑(네이버 EP)**&#xC744; 운영 중이라면, 해당 매체에 제출하고 있는 피드 URL을 그대로 사용할 수 있습니다. genser의 수집 엔진이 해당 경로에 정기적으로 접속하여 최신 정보를 가져옵니다.

{% stepper %}
{% step %}

## 사전 준비사항

연동 전, 원활한 수집을 위해 아래 두 가지 사항을 반드시 확인해 주시기 바랍니다.

* **데이터 항목(Field) 최적화:** genser의 AI는 상품 상세 설명(Description)과 속성 정보를 기반으로 깊이 있는 답변을 생성합니다. 기존 피드 내에 상세 설명 텍스트가 충분히 포함되어 있는지 확인해 주세요.
* **접근 권한(IP 허용) 설정:** 보안을 위해 외부 접속을 차단한 경우, genser 수집 서버가 해당 파일에 접근할 수 있도록 IP 화이트리스트 등록 등의 네트워크 방화벽 해제 조치가 필요합니다.
  {% endstep %}

{% step %}

## 파일 URL 확인하기

#### A. 구글 머천트 센터(GMC) 파일 URL 확인하기

1. **GMC 로그인:** [구글 머천트 센터](https://merchants.google.com/)에 접속합니다.
2. **메뉴 이동:** 왼쪽 탐색 메뉴에 있는 `설정(Settings) > 데이터 소스(Data sources)` 메뉴를 클릭합니다.
3. **소스 선택:** 제품 소스 탭에서 현재 연동 중인 소스 이름을 클릭합니다.
4. **파일 URL 확인:**
   1. \[가져오기 일정] 페이지에서 파일 URL을 확인하고 복사합니다.
   2. **중요**: 파일 위치의 URL은 http\://, https\://, ftp\:// 또는 sftp\://로 시작해야 합니다.

{% hint style="info" %}
**설정 화면에 URL이 없는 경우**

구글 머천트 센터 설정 화면에 URL이 없다면, 이용 중인 쇼핑몰 관리자(카페24 등)에서 '파일 URL'을 찾아 복사해 주세요.
{% endhint %}

#### B. 네이버 쇼핑 EP 파일 URL 확인하기

1. **파트너센터 로그인:** [네이버 쇼핑 파트너센터](https://center.shopping.naver.com/)에 접속합니다.
2. **메뉴 이동:** `상품 관리` > `상품정보 수신 현황` 메뉴로 이동합니다.
3. **쇼핑 URL 확인:** 쇼핑몰 상품 DB URL 란에서 \[수정요청] 버튼을 클릭합니다.
4. **쇼핑 URL 복사:** 상품 DB URL 설정 요청 페이지에서 URL을 확인하고 복사합니다.

[**네이버 쇼핑 EP URL 가이드**](https://join.shopping.naver.com/misc/download/ep_guide.nhn)
{% endstep %}

{% step %}

## 파일 URL 등록하기

1. **관리자 페이지 접속:** 발급받은 계정으로 관리자페이지에 로그인합니다.
2. **메뉴 이동:** 왼쪽 사이드 메뉴에 있는 `인스턴스 설정`  메뉴를 클릭합니다.
3. **데이터 연동 설정:** 인스턴스 목록에서 해당 인스턴스의  `관리 도구` > `상품 정보 URL 연동` 메뉴를 선택합니다.
4. **모달에서 정보 입력:**
   1. 플랫폼 선택: '네이버 쇼핑' 또는 '구글 머천트 센터(GMC)' 중 선택합니다.
   2. 피드 URL 입력: 복사한 주소를 입력란에 붙여넣습니다.
   3. 저장 및 테스트: 모달 하단의 \[저장 및 수집 테스트] 버튼을 클릭하여 genser가 해당 주소에 정상적으로 접근하여 데이터를 읽어오는지 확인합니다.
5. **동기화 시점:** 동기화는 해당 국가의 현지 시간으로 **매일(00:15am)에 일배치 작업**을 통해 검색 엔진에 일괄 적용됩니다.
   {% endstep %}
   {% endstepper %}


# 표준 API 직접 연동

<figure><img src="/files/YehlINDMwTaT8Y0a7xdI" alt=""><figcaption></figcaption></figure>

표준 API 직접 연동은 고객사의 상품 정보를 API를 통해 genser로 데이터를 직접 전송하는 방식입니다.&#x20;

***

genser의 직접 연동 API는 데이터의 확장성과 상호운용성을 위해 다음과 같은 글로벌 기술 표준을 준수합니다.

* **JSON-LD & Schema.org:** 데이터에 의미를 부여하는 구조화된 데이터 포맷을 사용하여, Vertex AI가 상품의 맥락을 완벽하게 이해하도록 돕습니다.
* **CloudEvents:** 모든 상품 정보 변경을 '이벤트'로 취급하여, 시스템 간의 신뢰성 있는 데이터 교환을 보장합니다.

{% stepper %}
{% step %}

## 연동 준비하기 (Prepare)

API를 호출하기 위해 필요한 기본 정보입니다.

* **API Endpoint:** `https://api.genser.app/collectors/products`
* **Method:** `POST`
* **Content-Type:** `application/json` (또는 `application/ld+json`)
* **Service Key:** genser 어드민 \[설정] 메뉴에서 발급받은 `apiKey`

> **데이터 반영 시점 안내**
>
> API로 전송된 데이터는 즉시 검색 결과에 노출되지 않으며, 해당 국가의 현지 시간으로 매일 오전 00:15am에 실행되는 일괄 처리(Batch) 작업을 통해 검색 엔진에 반영됩니다.

{% endstep %}

{% step %}

## 인증하기 (Authenticate)

genser API는 복잡한 토큰 교환 방식 대신, 헤더(Header)에 키 값을 직접 포함하는 간편한 방식을 사용합니다. 어드민에서 발급받은 **Service Key**를 준비해 주세요. (`genser 어드민 > 설정` 에서 확인 가능)

* **Header Name:** `apiKey`&#x20;
* **Value:** 발급받은 키 값 그대로 입력 (Base64 인코딩 불필요)

**HTTP 요청 헤더 예시:**

```
POST /searches/products HTTP/1.1
Host: api.genser.app
Content-Type: application/json
apiKey: cb37cce9d6ae434fa366151b3420a9af //발급 받은 서비스 키
```

{% endstep %}

{% step %}

## 상품 데이터 전송하기 (Send Data)

신규 상품을 등록하거나, 기존 상품 정보(가격, 재고 등)가 변경되었을 때 아래 형식으로 데이터를 전송합니다. **JSON-LD** 및 **CloudEvents** 표준 규격을 따릅니다.

#### 요청 본문 (Request Body)

상품 수집 API를 호출할 때 본문(Body)에 포함해야 하는 최상위 필드입니다. 상세 상품 정보는 `@graph` 객체에 담아 전송합니다.

<table><thead><tr><th width="117.11328125">필드명</th><th width="96.91015625">타입</th><th width="79.609375">구분</th><th>설명</th></tr></thead><tbody><tr><td>@context</td><td>String</td><td>권장</td><td>JSON-LD 데이터의 기준 사전 정의 (값: <code>https://schema.org/</code>)</td></tr><tr><td>specversion</td><td>String</td><td>권장</td><td>CloudEvents 스펙 버전 (값: <code>1.0</code>)</td></tr><tr><td>id</td><td>String</td><td>권장</td><td>요청 건당 고유 식별자 (UUID 등)</td></tr><tr><td>type</td><td>String</td><td>권장</td><td>이벤트 유형 (예: create_product)</td></tr><tr><td>agent</td><td>Object</td><td>필수</td><td>데이터를 전송하는 주체(시스템) 식별값</td></tr><tr><td>@graph</td><td>Object</td><td>필수</td><td>실제 상품 정보가 포함된 Product 객체 리스트</td></tr></tbody></table>

#### 리소스 객체 (Resource Objects)

<table><thead><tr><th width="174.95703125">필드명</th><th width="89.03515625">타입</th><th width="80.3671875">구분</th><th>설명</th></tr></thead><tbody><tr><td>@type</td><td>String</td><td>필수</td><td>객체 타입 정의 (값: <code>Product</code>)</td></tr><tr><td>sku</td><td>String</td><td>필수</td><td>회사 내부에서 상품을 구분할 때 쓰는 관리 코드 (예: A001-Red)</td></tr><tr><td>name</td><td>String</td><td>필수</td><td>고객에게 보여지는 실제 상품의 이름</td></tr><tr><td>category</td><td>Object</td><td>필수</td><td>사이트에 진열되는 카테고리 분류 (예: 의류 > 남성 > 티셔츠)</td></tr><tr><td>└ @type</td><td>String</td><td>필수</td><td>객체 타입 정의 (값: <code>CategoryCode</code>)</td></tr><tr><td>└ name</td><td>String</td><td>필수</td><td>카테고리 명칭 (예: 스니커즈, 아우터)</td></tr><tr><td>└ code</td><td>String</td><td>권장</td><td>카테고리 분류 코드</td></tr><tr><td>brand</td><td>Object</td><td>필수</td><td>이 상품을 만든 브랜드 정보</td></tr><tr><td>└ @type</td><td>String</td><td>선택</td><td>객체 타입 정의 (값: <code>Brand</code>)</td></tr><tr><td>└ id</td><td>String</td><td>필수</td><td>브랜드 아이디</td></tr><tr><td>└ name</td><td>Object</td><td>필수</td><td>브랜드 이름, 브랜드 이름 표기 언어 코드(예: ko)</td></tr><tr><td>description</td><td>Object</td><td>필수</td><td>상품 설명, 언어 코드, 상품 설명 부가 정보 등</td></tr><tr><td>offers</td><td>Object</td><td>필수</td><td>가격 및 재고 정보 객체</td></tr><tr><td>└ @type</td><td>String</td><td>선택</td><td>객체 타입 정의 (값: <code>Offer</code>)</td></tr><tr><td>└ sku</td><td>String</td><td>필수</td><td>판매용 SKU</td></tr><tr><td>└ gtin</td><td>String</td><td>필수</td><td>전 세계적으로 통용되는 상품 고유 번호 (예: 880으로 시작하는 바코드, EAN/UPC)</td></tr><tr><td>└ mpn</td><td>String</td><td>필수</td><td>제조사에서 부여한 부품 번호나 모델명</td></tr><tr><td>└ price</td><td>Number</td><td>필수</td><td>고객이 실제로 결제하게 될 최종 판매 금액</td></tr><tr><td>└ priceCurrency</td><td>String</td><td>필수</td><td>결제 통화 기준 (한국은 KRW, 미국은 USD 등)</td></tr><tr><td>└ availability</td><td>String</td><td>필수</td><td>지금 구매가 가능한지 여부 ( 값: <code>InStock, OutOfStock, PreOrder</code>)</td></tr><tr><td>└ availabilityStarts</td><td>Date</td><td>필수</td><td>상품 판매가 시작되는 날짜와 시간 (2025-11-28T10:00:00Z)</td></tr><tr><td>└ availabilityEnds</td><td>Date</td><td>필수</td><td>상품 판매를 마감하는 날짜와 시간 (2025-11-28T10:00:00Z)</td></tr><tr><td>└ shippingDetails</td><td>Object</td><td>선택</td><td>배송 정보</td></tr><tr><td>└ image</td><td>Object</td><td>필수</td><td>상품 이미지</td></tr><tr><td>additionalProperty</td><td>Array</td><td>선택</td><td>관세청 신고를 위한 HS Code나 친환경 태그 등 특수한 추가 정보</td></tr><tr><td>└ @type</td><td>String</td><td>선택</td><td>정보가 어떤 형태인지 정의 (값: <code>PropertyValue</code>)</td></tr><tr><td>└ propertyID</td><td>String</td><td>선택</td><td><p>정보 이름표 (ID)<br></p><ul><li><code>html</code>: 웹용 HTML 설명</li><li><code>seo_title</code>: 검색 노출용 제목</li><li><code>hsCode</code>: 통관용 관세 코드</li><li><code>sustainabilityTags</code>: 친환경 태그</li></ul></td></tr><tr><td>└ value</td><td>String</td><td>선택</td><td>이름표에 해당하는 실제 내용 (예: 이름표가 <code>hsCode</code>라면, 값은 <code>851762</code>)</td></tr></tbody></table>

<details>

<summary><strong>요청 본문 샘플 코드 예시</strong></summary>

```js
{
  "@context": "https://schema.org/",
  "specversion": "1.0",
  "id": "EVT-CREATE-PRODUCT",
  "type": "create_product",
  "agent": {
    "@type": "Organization",
    "name": "ExampleCorp"
  },
  "@graph": [
    {
      "@type": "Product",
      "sku": "PROD-001-A",
      "name": {
        "@value": "프리미엄 블루투스 이어폰",
        "@language": "ko"
      },
      "description": [
        {
          "@type": "TextObject",
          "text": "완전 무선 블루투스 이어폰으로 고음질 사운드와 편안한 착용감을 제공합니다.",
          "inLanguage": "ko",
          "additionalProperty": [
            {
              "@type": "PropertyValue",
              "propertyID": "html",
              "value": "<p>완전 무선 블루투스 이어폰으로 <strong>고음질 사운드</strong>와 편안한 착용감을 제공합니다.</p>"
            },
            {
              "@type": "PropertyValue",
              "propertyID": "seo_title",
              "value": "프리미엄 블루투스 이어폰 - 고음질 무선 이어폰"
            },
            {
              "@type": "PropertyValue",
              "propertyID": "seo_description",
              "value": {
                "@value": "고음질 완전 무선 이어폰, 장시간 착용에도 편안한 프리미엄 제품",
                "@language": "ko"
              }
            }
          ]
        }
      ],
      "brand": {
        "@type": "Brand",
        "@id": "brand-001",
        "name": {
          "@value": "사운드맥스",
          "@language": "ko"
        },
        "logo": "https://example.com/brand/soundmax-logo.png"
      },
      "category": [
        {
          "@type": "CategoryCode",
          "codeValue": "ELEC001",
          "name": {
            "@value": "전자기기",
            "@language": "ko"
          },
          "position": 1
        },
        {
          "@type": "CategoryCode",
          "codeValue": "AUDIO005",
          "name": {
            "@value": "오디오 기기",
            "@language": "ko"
          },
          "position": 2
        }
      ],
      "positiveNotes": {
        "@value": "고음질, 장시간 배터리, 편안한 착용감",
        "@language": "ko"
      },
      "url": {
        "@value": "https://example.com/product/P001",
        "@language": "ko"
      },
      "itemCondition": "NewCondition",
      "hasAdultConsideration": "UnclassifiedAdultConsideration",
      "countryOfOrigin": {
        "@type": "Country",
        "address": "KR"
      },
      "material": {
        "@value": "플라스틱, 실리콘",
        "@language": "ko"
      },
      "offers": {
        "@type": "Offer",
        "sku": "PROD-001-A",
        "gtin": "8801234567890",
        "mpn": "SM-EAR-2025",
        "price": 129000,
        "priceCurrency": "KRW",
        "priceSpecification": {
          "@type": "UnitPriceSpecification",
          "price": 129000,
          "unitCode": "EA"
        },
        "availability": "InStock",
        "availabilityStarts": "2025-11-28T10:00:00Z",
        "availabliltyEnds": "2026-12-31T23:59:59Z", 
        "inventoryLevel": {
          "@type": "QuantitativeValue",
          "value": 250
        },
        "shippingDetails": {
          "@type": "OfferShippingDetails",
          "weight": {
            "@type": "QuantitativeValue",
            "value": 0.2,
            "unitCode": "KG"
          }
        },
        "image": [
          {
            "@type": "ImageObject",
            "contentUrl": "https://example.com/product/P001/main.jpg",
            "contentSize": "350KB",
            "width": {
              "@type": "QuantitativeValue",
              "value": 1080
            },
            "height": {
              "@type": "QuantitativeValue",
              "value": 1080
            }
          }
        ]
      },
      "additionalProperty": [
        {
          "@type": "PropertyValue",
          "propertyID": "hsCode",
          "value": "851762"
        },
        {
          "@type": "PropertyValue",
          "propertyId": "sustainabilityTags", 
          "value": ["lowEnergyConsumption", "recyclablePackaging"]
        }
      ]
    }
  ]
}
```

</details>

#### 다국어 정보 연동 (Multi-language Support)

단일 요청으로 여러 언어의 상품 정보를 동시에 등록할 수 있습니다. 글로벌 판매를 위해 상품명, 브랜드, 카테고리 등 텍스트 정보에 다국어 값을 설정하려면, 해당 필드를 JSON 배열(`Array`)로 변경하고 언어 코드(`@language`)를 구분하여 입력해 주세요.

* **기본 원칙**
  * **단일 언어:** Object 형식 `{ "@value": "...", "@language": "ko" }`
  * **다국어:** Array 형식 `[ { "ko" 데이터 }, { "en" 데이터 } ]`
* **지원 필드:** `name`, `brand.name`, `category.name`, `positiveNotes`, `material`, `url` 등
* **주의사항:** `description` 필드는 `inLanguage`속성을 사용하여 구분합니다.

<details>

<summary><strong>다국어 적용 요청 본문 샘플 코드 예시</strong></summary>

```js
{
  "@context": "https://schema.org/",
  "specversion": "1.0",
  "id": "EVT-CREATE-PRODUCT",
  "type": "create_product",
  "agent": {
    "@type": "Organization",
    "name": "ExampleCorp"
  },
  "@graph": [
    {
      "@type": "Product",
      "sku": "PROD-001-A",
      "name": [
        {
          "@value": "프리미엄 블루투스 이어폰",
          "@language": "ko"
        },
        {
          "@value": "Premium Bluetooth Earphones",
          "@language": "en"
        }
      ],
      "description": [
        {
          "@type": "TextObject",
          "text": "완전 무선 블루투스 이어폰으로 고음질 사운드와 편안한 착용감을 제공합니다.",
          "inLanguage": "ko",
          "additionalProperty": [
            {
              "@type": "PropertyValue",
              "propertyID": "html",
              "value": "<p>완전 무선 블루투스 이어폰...</p>"
            }
          ]
        },
        {
          "@type": "TextObject",
          "text": "True wireless bluetooth earphones providing high-quality sound and comfortable fit.",
          "inLanguage": "en",
          "additionalProperty": [
            {
              "@type": "PropertyValue",
              "propertyID": "html",
              "value": "<p>True wireless bluetooth earphones...</p>"
            }
          ]
        }
      ],
      "brand": {
        "@type": "Brand",
        "@id": "brand-001",
        "name": [
          {
            "@value": "사운드맥스",
            "@language": "ko"
          },
          {
            "@value": "SoundMax",
            "@language": "en"
          }
        ],
        "logo": "https://example.com/brand/soundmax-logo.png"
      },
      "category": [
        {
          "@type": "CategoryCode",
          "codeValue": "ELEC001",
          "name": [
             { "@value": "전자기기", "@language": "ko" },
             { "@value": "Electronics", "@language": "en" }
          ],
          "position": 1
        },
        {
          "@type": "CategoryCode",
          "codeValue": "AUDIO005",
          "name": [
             { "@value": "오디오 기기", "@language": "ko" },
             { "@value": "Audio Devices", "@language": "en" }
          ],
          "position": 2
        }
      ],
      "positiveNotes": [
        {
          "@value": "고음질, 장시간 배터리, 편안한 착용감",
          "@language": "ko"
        },
        {
          "@value": "High fidelity, Long battery life, Comfortable fit",
          "@language": "en"
        }
      ],
      "url": [
        {
          "@value": "https://example.com/product/P001",
          "@language": "ko"
        },
        {
          "@value": "https://example.com/en/product/P001",
          "@language": "en"
        }
      ],
      "itemCondition": "NewCondition",
      "hasAdultConsideration": "UnclassifiedAdultConsideration",
      "countryOfOrigin": {
        "@type": "Country",
        "address": "KR"
      },
      "material": [
        {
          "@value": "플라스틱, 실리콘",
          "@language": "ko"
        },
        {
          "@value": "Plastic, Silicone",
          "@language": "en"
        }
      ],
      "offers": {
        "@type": "Offer",
        "sku": "PROD-001-A",
        "gtin": "8801234567890",
        "mpn": "SM-EAR-2025",
        "price": 129000,
        "priceCurrency": "KRW",
        "priceSpecification": {
          "@type": "UnitPriceSpecification",
          "price": 129000,
          "unitCode": "EA"
        },
        "availability": "InStock",
        "availabilityStarts": "2025-11-28T10:00:00Z",
        "availabliltyEnds": "2026-12-31T23:59:59Z",
        "inventoryLevel": {
          "@type": "QuantitativeValue",
          "value": 250
        },
        "shippingDetails": {
          "@type": "OfferShippingDetails",
          "weight": {
            "@type": "QuantitativeValue",
            "value": 0.2,
            "unitCode": "KG"
          }
        },
        "image": [
          {
            "@type": "ImageObject",
            "contentUrl": "https://example.com/product/P001/main.jpg",
            "contentSize": "350KB",
            "width": {
              "@type": "QuantitativeValue",
              "value": 1080
            },
            "height": {
              "@type": "QuantitativeValue",
              "value": 1080
            }
          }
        ]
      },
      "additionalProperty": [
        {
          "@type": "PropertyValue",
          "propertyID": "hsCode",
          "value": "851762"
        },
        {
          "@type": "PropertyValue",
          "propertyId": "sustainabilityTags",
          "value": ["lowEnergyConsumption", "recyclablePackaging"]
        }
      ]
    }
  ]
}
```

</details>

{% endstep %}

{% step %}

## 응답 확인하기 (Check Response)

API 호출 후 HTTP 상태 코드를 확인하여 전송 성공 여부를 판단합니다.

#### 상태 코드 (HTTP Status Codes)

가장 먼저 확인해야 할 응답 상태 코드입니다.

<table><thead><tr><th width="166.3515625">상태 코드</th><th width="117.9609375">결과</th><th>설명</th></tr></thead><tbody><tr><td>200 OK</td><td>성공</td><td>성공입니다. 다음날 00:15am 배치를 통해 반영됩니다.</td></tr><tr><td>400 Bad Request</td><td>요청 형식 오류</td><td>JSON 문법이 틀렸거나, 필수 값(<code>sku</code>, <code>name</code> 등)이 누락되었는지 확인하세요.</td></tr><tr><td>401 Unauthorized</td><td>인증 실패</td><td>Header의 <code>apiKey</code> 값이 정확한지, 공백은 없는지 확인하세요.</td></tr><tr><td>500 Internal Error</td><td>서버 오류</td><td>일시적인 장애일 수 있습니다. 잠시 후 재시도(Retry) 로직을 실행하세요.</td></tr></tbody></table>
{% endstep %}
{% endstepper %}


# 레거시 API 연동 (v0.3)

본 가이드는 **기존 전용 API(v0.3)를 이용해 상품 데이터를 연동 중인 고객사**를 위한 페이지입니다.

해당 규격은 상품의 기본 정보부터 브랜드, 카테고리, 상세 가격 정보를 계층 구조(Object)로 수집합니다. 만약 신규로 연동을 진행하시는 고객사라면, 본 페이지 대신 [\[표준 API 직접 연동\]](/integration/product-data-integration/standard-api) 가이드를 참고해 주시기 바랍니다.

## 1. 개요 및 연동 정보

고객사의 상품 데이터를 genser API 엔드포인트로 전송하여 검색 엔진에 반영합니다.

<table><thead><tr><th width="181.09765625">항목</th><th>내용</th></tr></thead><tbody><tr><td><strong>Endpoint (운영)</strong></td><td><a href="https://api.genser.app/searches/products">https://api.genser.app/searches/products</a></td></tr><tr><td><strong>HTTP Method</strong></td><td><code>POST</code></td></tr><tr><td><strong>인증 방식</strong></td><td>Header에 <code>x-api-key: {발급받은_API_KEY}</code> 포함</td></tr></tbody></table>

## 2. 데이터 업데이트 및 반영 시점

데이터는 성격별로 반영 시점이 다릅니다.

* **일반 상품 정보 (신규/수정):** 매일 **오전 00:15** 일괄 업데이트 (Batch)
* **품절 정보 (Status):** 데이터 수신 즉시 **실시간** 반영
* **업데이트 방법:** 상품 정보가 변경되거나 신규 등록될 때마다 동일한 API를 다시 호출하여 최신 데이터를 전송해 주세요.

## 3. 상세 데이터 규격 (v0.3)

필드 정의서에 따른 주요 항목들입니다.&#x20;

### 3.1 검색 상품 (Product)

<table><thead><tr><th width="206.3359375">필드명</th><th width="146.8984375">타입</th><th width="74.63671875">필수</th><th width="489.00390625">설명</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>Y</td><td>상품 고유 코드</td></tr><tr><td>name</td><td>String</td><td>Y</td><td>상품명</td></tr><tr><td>brand</td><td>Object</td><td>Y</td><td>브랜드 정보</td></tr><tr><td>└ code</td><td>String</td><td>Y</td><td>브랜드 이름</td></tr><tr><td>└ name</td><td>String</td><td>Y</td><td>브랜드코드</td></tr><tr><td>categories</td><td>Array</td><td>Y</td><td>카테고리 정보</td></tr><tr><td>└ largeCode</td><td>String</td><td>Y</td><td>대분류 코드</td></tr><tr><td>└ largeName</td><td>String</td><td>Y</td><td>대분류 이름</td></tr><tr><td>└ midCode</td><td>String</td><td>N</td><td>중분류 코드</td></tr><tr><td>└ midName</td><td>String</td><td>N</td><td>중분류 이름</td></tr><tr><td>└ smallCode</td><td>String</td><td>N</td><td>소분류 코드</td></tr><tr><td>└ smallName</td><td>String</td><td>N</td><td>소분류 이름</td></tr><tr><td>└ detailCode</td><td>String</td><td>N</td><td>세분류 코드</td></tr><tr><td>└ detailName</td><td>String</td><td>N</td><td>세분류 이름</td></tr><tr><td>image</td><td>Object</td><td>Y</td><td>상품 이미지 정보</td></tr><tr><td>└ mainUrl</td><td>String</td><td>Y</td><td>대표 이미지 url</td></tr><tr><td>└ detailUrls</td><td>Array</td><td>Y</td><td>상품 상세 이미지 URL 배열</td></tr><tr><td>└ productUrl</td><td>String</td><td>N</td><td>제품 상세 페이지 url</td></tr><tr><td>priceInfo</td><td>Object</td><td>Y</td><td>가격 정보</td></tr><tr><td>└ currency</td><td>String</td><td>Y</td><td>통화 코드</td></tr><tr><td>└ price</td><td>Double</td><td>Y</td><td>상품 가격</td></tr><tr><td>└ salePrice</td><td>Double</td><td>Y</td><td>상품 할인가격</td></tr><tr><td>└ salePercent</td><td>Double</td><td>N</td><td>상품 할인율</td></tr><tr><td>rating</td><td>Object</td><td>N</td><td>리뷰 정보</td></tr><tr><td>└ reviewCount</td><td>Integer</td><td>N</td><td>리뷰수</td></tr><tr><td>└ avgRating</td><td>Double</td><td>N</td><td>평균 평점</td></tr><tr><td>└ avgDeliveryRating</td><td>Double</td><td>N</td><td>평균 배송 평점</td></tr><tr><td>createdAt</td><td>String</td><td>Y</td><td>상품 등록일</td></tr><tr><td>createdAtEpochMilli</td><td>Long</td><td>N</td><td>상품 등록일</td></tr><tr><td>isInStock</td><td>Boolean</td><td>N</td><td>상품 재고 여부</td></tr><tr><td>attribute</td><td>Object</td><td>N</td><td>상품 속성 정보</td></tr><tr><td>└ description</td><td>String</td><td>N</td><td>상품 상세 정보</td></tr><tr><td>└ keywords</td><td>Array</td><td>N</td><td>주요 키워드</td></tr><tr><td>└ colors</td><td>Array</td><td>N</td><td>색상</td></tr><tr><td>└ series</td><td>String</td><td>N</td><td>시리즈</td></tr><tr><td>└ situations</td><td>Array</td><td>N</td><td>상황</td></tr><tr><td>└ seasons</td><td>Array</td><td>N</td><td>계절</td></tr><tr><td>└ materials</td><td>Array</td><td>N</td><td>소재</td></tr><tr><td>└ gender</td><td>Array</td><td>N</td><td>성별</td></tr><tr><td>└ ages</td><td>Array</td><td>N</td><td>연령대</td></tr><tr><td>└ sizes</td><td>Array</td><td>N</td><td>공통 사이즈</td></tr><tr><td>└ features</td><td>Array</td><td>N</td><td>상품 특징</td></tr><tr><td>└ styles</td><td>Array</td><td>N</td><td>상품 스타일</td></tr><tr><td>└ installTime</td><td>Integer</td><td>N</td><td>설치 예상 시간 (분)</td></tr><tr><td>└ flavor</td><td>Array</td><td>N</td><td>맛</td></tr><tr><td>└ maxLoad</td><td>String</td><td>N</td><td>최대 하중</td></tr><tr><td>└ skinType</td><td>Array</td><td>N</td><td>적합 피부타입</td></tr><tr><td>└ spf</td><td>Array</td><td>N</td><td>자외선 차단 지수</td></tr><tr><td>└ fragrance</td><td>Array</td><td>N</td><td>향</td></tr><tr><td>└ energyGrade</td><td>String</td><td>N</td><td>에너지효율 등급</td></tr><tr><td>└ originCountry</td><td>String</td><td>N</td><td>제조국 / 원산지</td></tr><tr><td>└ promotions</td><td>String</td><td>N</td><td>상품 프로모션</td></tr><tr><td>└ isBroadcast</td><td>Boolean</td><td>N</td><td>방송된 상품 유무</td></tr><tr><td>└ width</td><td>Double</td><td>N</td><td>가로</td></tr><tr><td>└ height</td><td>Double</td><td>N</td><td>높이</td></tr><tr><td>└ depth</td><td>Double</td><td>N</td><td>세로</td></tr><tr><td>└ skinColors</td><td>Array</td><td>N</td><td>피부색상</td></tr><tr><td>└ diseaseInfos</td><td>Array</td><td>N</td><td>질병종류</td></tr><tr><td>└ functions</td><td>Array</td><td>N</td><td>기능</td></tr><tr><td>└ applyAreas</td><td>Array</td><td>N</td><td>적용 부위</td></tr><tr><td>└ alternatives</td><td>Array</td><td>N</td><td>대체 상품 리스트</td></tr><tr><td>customs</td><td>Array</td><td>N</td><td>고객사 커스텀 데이터</td></tr><tr><td>└ name</td><td>String</td><td>Y</td><td>이름</td></tr><tr><td>└ values</td><td>Array</td><td>N</td><td>값</td></tr></tbody></table>

<details>

<summary>검색 상품 데이터 JSON 요청 예시</summary>

```js
[
  {
    "code": "P-KR-2025-001",
    "name": "프리미엄 울 니트 가디건",
    "brand": {
      "code": "BR-LOMO",
      "name": "로모 스튜디오"
    },
    "categories": [
      {
        "largeCode": "10",
        "largeName": "여성의류",
        "midCode": "1010",
        "midName": "아우터",
        "smallCode": "101010",
        "smallName": "가디건",
        "detailCode": "10101001",
        "detailName": "라운드넥 가디건"
      }
    ],
    "image": {
      "mainUrl": "https://api.example.co.kr/images/products/2025/05/wool_cardigan_main.jpg",
      "detailUrls": [
        "https://api.example.co.kr/images/products/2025/05/wool_cardigan_detail_01.jpg",
        "https://api.example.co.kr/images/products/2025/05/wool_cardigan_detail_02.jpg"
      ],
      "productUrl": "https://www.example.co.kr/product/detail.html?product_no=1001"
    },
    "priceInfo": {
      "currency": "KRW",
      "price": 50000.0,
      "salePrice": 45000.0,
      "salePercent": 10.0
    },
    "rating": {
      "reviewCount": 128,
      "avgRating": 4.8,
      "avgDeliveryRating": 4.9
    },
    "createAt": "2025-05-03T09:30:00+09:00",
    "createdAtEpochMilli": 1746232200000,
    "isInStock": true,
    "attribute": {
      "description": "부드러운 촉감의 오버핏 울 가디건으로, 클래식한 감성과 현대적인 실루엣이 조화를 이룹니다.",
      "keywords": ["울 가디건", "오버핏", "하객룩", "봄 아우터", "데일리룩"],
      "series": "2025 Spring 컬렉션",
      "situations": ["출근룩", "데이트룩", "주말 나들이"],
      "seasons": ["봄", "가을", "간절기"],
      "materials": ["울 80%", "폴리에스터 20%"],
      "gender": ["여성", "남녀공용"],
      "ages": ["20대", "30대"],
      "sizes": ["Free", "S", "M", "L"],
      "features": ["오버핏", "드롭숄더", "안감 없음", "신축성 좋음"],
      "styles": ["미니멀", "캐주얼", "베이직"],
      "originCountry": "대한민국",
      "promotions": ["신규가입 쿠폰 적용가능"],
      "isBroadcast": false
    },
    "customs": [
      {
        "name": "gift_option",
        "values": ["선물 포장", "쇼핑백 동봉"]
      }
    ]
  }
]
```

</details>

### 3.2 필터 (Filters)

<table><thead><tr><th width="226.76953125">필드명</th><th width="96.58984375">타입</th><th width="79.49609375">필수</th><th>설명</th></tr></thead><tbody><tr><td>httpStatus</td><td></td><td></td><td>http 상태</td></tr><tr><td>└ code</td><td>String</td><td>Y</td><td>HTTP 상태코드</td></tr><tr><td>└ reasonPhrase</td><td>String</td><td>Y</td><td>HTTP 상태메세지</td></tr><tr><td>processCode</td><td>String</td><td>Y</td><td>요청의 성공여부 “OK“ or “FAIL“</td></tr><tr><td>processValue</td><td>Object</td><td>Y</td><td>요청의 결과값</td></tr></tbody></table>

<details>

<summary>필터 데이터 JSON 요청 예시</summary>

```js
[
    {
        "name": "color",
        "values": [
            "골드",
            "베이지",
            "브라운"
        ]
    }
]
```

</details>

### 3.3 콘텐트 (Content)

콘텐트 수집 API 입니다.&#x20;

<table><thead><tr><th width="239.60546875">필드명</th><th width="98.1484375">타입</th><th width="77.72265625">필수</th><th width="489.00390625">설명</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>Y</td><td>콘텐츠 코드</td></tr><tr><td>name</td><td>String</td><td>Y</td><td>콘텐츠 이름</td></tr><tr><td>categories</td><td>Array</td><td>Y</td><td>상품 카테고리</td></tr><tr><td>└ largeCode</td><td>String</td><td>Y</td><td>대분류 코드</td></tr><tr><td>└ largeName</td><td>String</td><td>Y</td><td>대분류 이름</td></tr><tr><td>└ midCode</td><td>String</td><td>N</td><td>중분류 코드</td></tr><tr><td>└ midName</td><td>String</td><td>N</td><td>중분류 이름</td></tr><tr><td>└ smallCode</td><td>String</td><td>N</td><td>소분류 코드</td></tr><tr><td>└ smallName</td><td>String</td><td>N</td><td>소분류 이름</td></tr><tr><td>└ detailCode</td><td>String</td><td>N</td><td>세분류 코드</td></tr><tr><td>└ detailName</td><td>String</td><td>N</td><td>세분류 이름</td></tr><tr><td>image</td><td>Object</td><td>Y</td><td>상품 이미지 정보</td></tr><tr><td>└ mainUrl</td><td>String</td><td>Y</td><td>대표 이미지 url</td></tr><tr><td>└ detailUrls</td><td>Array</td><td>Y</td><td>상품상세이미지 url</td></tr><tr><td>└ productUrl</td><td>String</td><td>N</td><td>제품 상세 페이지 url</td></tr><tr><td>priceInfo</td><td>Object</td><td>Y</td><td>가격 정보</td></tr><tr><td>└ currency</td><td>String</td><td>Y</td><td>통화</td></tr><tr><td>└ price</td><td>Double</td><td>Y</td><td>상품 가격</td></tr><tr><td>└ salePrice</td><td>Double</td><td>Y</td><td>상품 할인가격</td></tr><tr><td>└ salePercent</td><td>Double</td><td>N</td><td>상품 할인율</td></tr><tr><td>createdAt</td><td>String</td><td>Y</td><td>상품 등록일</td></tr><tr><td>createdAtEpochMilli</td><td>Long</td><td>N</td><td>상품 등록일</td></tr><tr><td>languageCode</td><td>String</td><td>N</td><td>언어 코드</td></tr><tr><td>display</td><td>Object</td><td>N</td><td>전시 정보</td></tr><tr><td>└ isYn</td><td>Boolean</td><td>N</td><td>전시 여부</td></tr><tr><td>└ start</td><td>Long</td><td>Y</td><td>전시 시작 시간</td></tr><tr><td>└ end</td><td>Long</td><td>Y</td><td>전시 종료 시간</td></tr><tr><td>attribute</td><td>Object</td><td>N</td><td>상품 속성 정보</td></tr><tr><td>└ description</td><td>String</td><td>N</td><td>상품 설명</td></tr><tr><td>└ keywords</td><td>Array</td><td>N</td><td>주요 키워드</td></tr><tr><td>└ series</td><td>String</td><td>N</td><td>시리즈</td></tr><tr><td>└ location</td><td>String</td><td>N</td><td>위치</td></tr><tr><td>└ branchName</td><td>String</td><td>N</td><td>지점명</td></tr><tr><td>└ instructorName</td><td>String</td><td>N</td><td>강사명</td></tr><tr><td>└ sessionCount</td><td>Int</td><td>N</td><td>강의횟수</td></tr><tr><td>└ materialsPrice</td><td>Double</td><td>N</td><td>재료비</td></tr><tr><td>└ requiredSupplies</td><td>String</td><td>N</td><td>준비물</td></tr><tr><td>└ textbookInfo</td><td>String</td><td>N</td><td>교재정보</td></tr><tr><td>└ note</td><td>String</td><td>N</td><td>유의사항</td></tr><tr><td>└ cancellationRefundPolicy</td><td>String</td><td>N</td><td>강좌 취소 및 환불안내</td></tr><tr><td>└ phoneNumber</td><td>String</td><td>N</td><td>전화번호</td></tr><tr><td>└ lastOrder</td><td>Long</td><td>N</td><td>라스트오더 시간</td></tr><tr><td>└ menuName</td><td>Array</td><td>N</td><td>메뉴명</td></tr><tr><td>└ menuPrice</td><td>Array</td><td>N</td><td>메뉴 가격</td></tr><tr><td>└ menuDescription</td><td>Array</td><td>N</td><td>메뉴 설명</td></tr></tbody></table>

<details>

<summary>콘텐츠 정보 수집 JSON 요청 예시</summary>

```js
[
  {
    "code": "F-KR-2025-MK01",
    "name": "프리미엄 티본 스테이크 밀키트 (2인분)",
    "categories": [
      {
        "largeCode": "50",
        "largeName": "식품",
        "midCode": "5010",
        "midName": "밀키트/간편식",
        "smallCode": "501010",
        "smallName": "메인요리",
        "detailCode": "50101001",
        "detailName": "스테이크/고기"
      }
    ],
    "image": {
      "mainUrl": "https://api.example.co.kr/images/food/2025/steak_kit_main.jpg",
      "detailUrls": [
        "https://api.example.co.kr/images/food/2025/steak_kit_detail_01.jpg",
        "https://api.example.co.kr/images/food/2025/steak_kit_detail_02.jpg"
      ]
    },
    "priceInfo": {
      "currency": "KRW",
      "price": 65000.0,
      "salePrice": 58500.0,
      "salePercent": 10.0
    },
    "createAt": "2025-05-15T10:00:00+09:00",
    "createdAtEpochMilli": 1747270800000,
    "languageCode": "ko",
    "display": {
      "isYn": true,
      "start": 1747270800000,
      "end": 2534022000000
    },
    "attribute": {
      "description": "유명 레스토랑의 맛 그대로, 집에서 즐기는 프리미엄 숙성 티본 스테이크 쿠킹 박스입니다.",
      "keywords": [
        "밀키트",
        "홈파티",
        "캠핑요리",
        "스테이크",
        "기념일"
      ],
      "series": "2025 홈 다이닝 컬렉션",
      "location": "충청북도 음성군 (HACCP 인증 제조시설)",
      "brandName": "셰프의 식탁",
      "instructorName": "에드워드 홍 셰프",
      "sessionCount": 2,
      "materialsPrice": 0,
      "requiredSupplies": "조리도구(프라이팬) 외 필요 없음",
      "textbookInfo": "시크릿 레시피 카드 동봉",
      "note": "신선식품 특성상 배송 후 단순 변심 반품 불가",
      "cancellationRefundPolicy": "출고 전 취소 가능, 출고 후 환불 불가",
      "phoneNumber": "1544-0000",
      "lastOrder": 1762837200000,
      "menuName": "티본 스테이크 & 가니쉬 세트",
      "menuPrice": 58500,
      "menuDescription": "30일 숙성 티본(500g) + 아스파라거스 + 특제 소스"
    }
  }
]
```

</details>

## 4. 응답 코드 (Response)

API 호출 후 응답 본문의 `processCode`를 통해 성공 여부를 확인합니다.

* **processCode "0":** 정상 접수 (익일 00:15 반영 예정)
* **그 외 코드:** 오류 발생 (응답 본문의 `processValue` 메시지 확인 필요)

{% hint style="info" %}
**데이터 반복 안내**

데이터가 Array 타입일 때, 데이터가 반복될 수 있습니다.&#x20;
{% endhint %}

{% hint style="info" %}
**개발 가이드 팁**

* 품절 정보를 실시간으로 반영하려면 `inInstock` 필드를 포함하여 API를 즉시 호출하세요.
* 상품 상세 정보가 수정된 경우, 변경된 필드뿐만 아니라 전체 스키마를 포함하여 다시 전송하는 것이 안전합니다.
  {% endhint %}


# 검색 프론트엔드 설치하기

<figure><img src="/files/BpIOK0nEiSNvI1zyzHWi" alt=""><figcaption></figcaption></figure>

#### genser 프론트엔드 연동 시작하기

SDK 설치부터 API 호출까지, 서비스에 검색 엔진을 연동하는 개발 가이드를 확인하세요.

{% content-ref url="/pages/XD11BoYcivIqj9AjpMCD" %}
[검색 연동 프론트엔드 설치 가이드](/integration/frontend-installation/installation-guide)
{% endcontent-ref %}

***

#### 💡 genser를 어떻게 노출하면 좋을지 고민 중이신가요?

AI 검색 경험을 높여주는 4가지 실무 팁과 예시 코드를 참고해 보세요.

{% content-ref url="/pages/CeXYjtvIuKy5vp1MLnFG" %}
[genser 활용 제안](/integration/frontend-installation/installation-tips)
{% endcontent-ref %}


# 검색 연동 프론트엔드 설치 가이드

<figure><img src="/files/JPpK30HLxoHm8PcuJ16U" alt=""><figcaption></figcaption></figure>

프론트엔드에서 genser 검색 엔진을 연동하는 전체 과정을 안내합니다. 복잡한 개발 없이, **스크립트 설치**와 **함수 호출**만으로 AI 검색을 구현할 수 있습니다.

{% stepper %}
{% step %}

## 연동 키 준비하기 (Setup)

#### 서비스 키 및 인스턴스 키 확인

스크립트 연동에 필요한 두 가지 필수 키(Key) 값을 genser 어드민에서 미리 확보해야 합니다.

<table data-full-width="false"><thead><tr><th width="209.5078125">키 이름</th><th width="250.69921875">설명</th><th>용도</th></tr></thead><tbody><tr><td>서비스 키(Service Key)</td><td>서비스 연동을 위한 고유 인증 키</td><td>초기화 스크립트(<code>head</code> 영역) 설정용</td></tr><tr><td>인스턴스 키(Instance Key)</td><td>생성된 검색 인스턴스의 고유 식별자</td><td>검색 API(<code>searchProducts</code>) 및 로그 수집 호출용</td></tr></tbody></table>

{% hint style="info" %}
**서비스 키 확인 경로**

genser 어드민의 설정 메뉴에서 "서비스 키" 확인이 가능합니다.
{% endhint %}

<figure><img src="/files/eh4JZSZlVjnYiKxnpIHk" alt=""><figcaption><p>어드민 설정 화면에서 서비스 키 위치</p></figcaption></figure>

{% hint style="info" %}
**인스턴스 키 확인 경로**

genser 어드민의 인스턴스 설정 메뉴에서 테이블의 인스턴스 관리 도구 "코드 복사"로 인스턴스 키 복사 가능합니다.
{% endhint %}

<figure><img src="/files/jfxTWrorqfgrXudyS5O7" alt=""><figcaption><p>어드민 인스턴스 설정에서 인스턴스 키 복사 위치</p></figcaption></figure>

#### 기능 활성화 확인

API 응답에 특정 데이터를 포함받으려면 어드민의 인스턴스 설정에서 해당 기능을 미리 '활성화(ON)' 상태로 변경해야 합니다.
{% endstep %}

{% step %}

## 스크립트 설치하기 (Install)

genser 서비스를 이용하기 위해서는 모든 페이지의 공통 레이아웃에 기본 스크립트를 삽입해야 합니다.&#x20;

{% hint style="warning" %}
공통 레이아웃이 적용되지 않는 페이지가 있다면 해당 페이지에도 개별적으로 스크립트를 삽입해야 합니다.&#x20;
{% endhint %}

* **위치:** HTML 문서의 `<head>` 태그 종료 직전.
* **주의사항:**
  * 공통 레이아웃이 적용되지 않는 페이지가 있다면 해당 페이지에도 개별적으로 삽입해야 합니다.
  * `발급 받은 서비스 키` 부분에 실제 할당받은 키 값을 입력해야 합니다.

```js
<head>
    <!-- ... 기존 헤더 내용 ... -->
    
    <!-- genser 스크립트 설치 코드 시작 -->
    <script type="text/javascript">
        (function (a, i, u, e, o) {
            a[u] = a[u] || function () { (a[u].q = a[u].q || []).push(arguments) };
        })(window, document, "genser");
        
        // 발급 받은 서비스 키를 입력하세요
        genser("serviceKey", "발급 받은 서비스 키"); 
        genser("siteType", "custom");
    </script>
    <script charset="utf-8" src="//static.groobee.io/dist/g2/genser.init.min.js"></script>
    <!-- genser 스크립트 설치 코드 끝 -->
</head>
```

{% endstep %}

{% step %}

## 검색 결과 호출하기 (Search)

기본 스크립트 모든 페이지에 삽입되어 있다는 가정 하에 해당 페이지 내에서 아래와 같은 자바스크립트 함수를 사용할 수 있습니다.&#x20;

아래의 함수에 타입에 맞는 데이터를 넣어 호출하면 상품 검색 결과 데이터를 받을 수 있습니다.&#x20;

### 검색 호출(searchProducts)

```js
genser.call('searchProducts', {
    instanceKey: 'instanceKey', // 필수: 어드민에서 생성한 인스턴스 키
    queryText: '상품 검색어',     // 필수: 사용자 입력 검색어
  })
  .success((res) => {
    console.log(res);           // 검색 결과 데이터 반환 (아래 응답 구조 참고)
  })
  .error((err) => {
    console.error(err);         // 오류 발생 시
  });
```

<table data-full-width="false"><thead><tr><th width="131.3828125">항목</th><th width="79.3046875">타입</th><th width="79.578125">필수</th><th>설명</th></tr></thead><tbody><tr><td>instanceKey</td><td>string</td><td>필수</td><td>genser 어드민에서 생성한 인스턴스 키(고유 식별자)</td></tr><tr><td>queryText</td><td>string</td><td>필수</td><td>사용자가 입력한 상품 검색어</td></tr><tr><td>...</td><td></td><td>선택</td><td>기타 확장 필드 (사용 목적에 따라 추가 가능)</td></tr></tbody></table>

### 응답 데이터 구조(Response)

`success` 콜백을 통해 반환되는 데이터는 `type`에 따라 4가지 형태로 구분됩니다.

#### 1. 상품 정보(SEARCH)

검색된 상품 목록입니다.&#x20;

```js
{
    "requestId": "검색어에 대한 ID",
    "type": "SEARCH",
    "products": [
        {
            "code": "상품 코드",
            "name": "상품 이름",
            ...
        },
        {
            "code": "상품 코드",
            "name": "상품 이름",
            ...
        },
    ],
    "facet": {},
    "nextPageToken": ''
}
```

<table data-full-width="false"><thead><tr><th width="151.2421875">항목</th><th width="79.3046875">타입</th><th width="79.578125">필수</th><th>설명</th></tr></thead><tbody><tr><td>requestId</td><td>string</td><td>필수</td><td>검색어에 대한 고유 요청 ID</td></tr><tr><td>type</td><td>string</td><td>필수</td><td>응답 타입(예: " SEARCH")</td></tr><tr><td>products</td><td>array</td><td>필수</td><td>상품 목록 배열</td></tr><tr><td>products[].code</td><td>string</td><td>필수</td><td>상품 코드</td></tr><tr><td>products[].name</td><td>string</td><td>필수</td><td>상품 이름</td></tr><tr><td>facet</td><td>object</td><td>선택</td><td>-</td></tr><tr><td>nextPageToken</td><td>string</td><td>선택</td><td>-</td></tr></tbody></table>

#### 2. 검색 결과 설명(SUMMARY)

`검색 결과 설명 설정`이 어드민에서 활성화된 경우,  검색 결과에 대한 요약 텍스트를 반환합니다.

```js
{
    "requestId": "검색어에 대한 ID",
    "type": "SUMMARY",
    "summary": "요약 내용 텍스트"
}
```

<table data-full-width="false"><thead><tr><th width="151.2421875">항목</th><th width="79.3046875">타입</th><th width="79.578125">필수</th><th>설명</th></tr></thead><tbody><tr><td>requestId</td><td>string</td><td>필수</td><td>검색어에 대한 고유 요청 ID</td></tr><tr><td>type</td><td>string</td><td>필수</td><td>응답 타입(예: " SUMMARY")</td></tr><tr><td>summary</td><td>string</td><td>필수</td><td>검색어 또는 결과에 대한 요약 내용 텍스트</td></tr></tbody></table>

#### 3. 연관 키워드(KEYWORDS)

`연관 키워드 설정`이 어드민에서 활성화된 경우, 연관된 추천 키워드 리스트를 반환됩니다.

```js
{
    "requestId": "검색어에 대한 ID",
    "type": "KEYWORDS",
    "keywords": ["키워드1", "키워드2"]
}
```

<table data-full-width="false"><thead><tr><th width="151.2421875">항목</th><th width="79.3046875">타입</th><th width="79.578125">필수</th><th>설명</th></tr></thead><tbody><tr><td>requestId</td><td>string</td><td>필수</td><td>검색어에 대한 고유 요청 ID</td></tr><tr><td>type</td><td>string</td><td>필수</td><td>응답 타입(예: " KEYWORDS")</td></tr><tr><td>keywords</td><td>string[]</td><td>필수</td><td>추천 또는 연관 키워드 배열 (문자열 리스트)</td></tr></tbody></table>

#### 4. 제안 질문(QUESTIONS)

`제안 질문 설정`이 어드민에서 활성화된 경우, 사용자가 추가로 궁금해할 만한 질문 리스트를 반환합니다.

```js
{
    "requestId": "검색어에 대한 ID",
    "type": "QUESTIONS",
    "questions": [
        "질문 내용 1",
        "질문 내용 2"
    ]
}
```

<table data-full-width="false"><thead><tr><th width="151.2421875">항목</th><th width="79.3046875">타입</th><th width="79.578125">필수</th><th>설명</th></tr></thead><tbody><tr><td>requestId</td><td>string</td><td>필수</td><td>검색어에 대한 고유 요청 ID</td></tr><tr><td>type</td><td>string</td><td>필수</td><td>응답 타입(예: " QUESTIONS")</td></tr><tr><td>questions</td><td>string[]</td><td>필수</td><td>제안 질문 배열 (문자열 리스트)</td></tr></tbody></table>
{% endstep %}

{% step %}

## 로그 데이터 수집하기 (Analytics)

검색 품질 향상과 통계를 위해 사용자 행동 데이터를 수집합니다.

* **검색(SE):** `searchProducts` 함수 호출 시 자동으로 수집됩니다.
* **노출(DI) & 클릭(CL):** 아래 함수를 사용하여 직접 호출해야 합니다.

### 노출 (DI)

검색 결과 상품이 화면에 노출되었을 때 호출합니다.

```js
genser.call('DI', {
    instance: { key: 'instanceKey' }, // 인스턴스 키
    goods: [
      {
        code: '상품 코드', // searchProducts 결과의 code
        name: '상품 이름', // searchProducts 결과의 name
      },
      ...
    ], // 상품 정보
    requestId: '검색어에 대한 ID', // searchProducts 결과에서 응답 받은 requestId
  })
  .success((res) => {
    console.log(res);   // 정상 callback
  })
  
.error((err) => {
    console.error(err); // 오류 callback
  });

```

<table data-full-width="false"><thead><tr><th width="151.2421875">항목</th><th width="79.3046875">타입</th><th width="79.578125">필수</th><th>설명</th></tr></thead><tbody><tr><td>instance</td><td>object</td><td>필수</td><td>genser 어드민에서 생성한 인스턴스 정보</td></tr><tr><td>instance.key</td><td>string</td><td>필수</td><td>genser 어드민에서 생성한 인스턴스 키 (고유 식별자)</td></tr><tr><td>goods</td><td>array</td><td>필수</td><td>사용자에게 추천/선택된 상품 목록</td></tr><tr><td>goods[].code</td><td>string</td><td>필수</td><td>상품 코드 (<code>searchProducts</code> 응답의 상품 코드 사용)</td></tr><tr><td>goods[].name</td><td>string</td><td>필수</td><td>상품 이름 (<code>searchProducts</code> 응답의 상품 이름 사용)</td></tr><tr><td>requestId</td><td>string</td><td>필수</td><td>상품 검색 결과에서 받은 요청 ID (<code>searchProducts</code> 응답의 requestId 사용)</td></tr></tbody></table>

### 클릭 (CL)

사용자가 상품을 클릭했을 때 호출합니다.

```js
genser.call('CL', {
    instance: { key: 'instanceKey' }, // 인스턴스 키
    goods: [
      {
        code: '상품 코드', // searchProducts 결과의 code
        name: '상품 이름', // searchProducts 결과의 name
      },
      ...
    ], // 상품 정보
    requestId: '검색어에 대한 ID', // searchProducts 결과에서 응답 받은 requestId
  })
  .success((res) => {
    console.log(res);   // 정상 callback
  })
  
.error((err) => {
    console.error(err); // 오류 callback
  });

```

<table data-full-width="false"><thead><tr><th width="151.2421875">항목</th><th width="79.3046875">타입</th><th width="79.578125">필수</th><th>설명</th></tr></thead><tbody><tr><td>instance</td><td>object</td><td>필수</td><td>genser 어드민에서 생성한 인스턴스 정보</td></tr><tr><td>instance.key</td><td>string</td><td>필수</td><td>genser 어드민에서 생성한 인스턴스 키 (고유 식별자)</td></tr><tr><td>goods</td><td>array</td><td>필수</td><td>사용자에게 추천/선택된 상품 목록</td></tr><tr><td>goods[].code</td><td>string</td><td>필수</td><td>상품 코드 (<code>searchProducts</code> 응답의 상품 코드 사용)</td></tr><tr><td>goods[].name</td><td>string</td><td>필수</td><td>상품 이름 (<code>searchProducts</code> 응답의 상품 이름 사용)</td></tr><tr><td>requestId</td><td>string</td><td>필수</td><td>상품 검색 결과에서 받은 요청 ID (<code>searchProducts</code> 응답의 requestId 사용)</td></tr></tbody></table>
{% endstep %}
{% endstepper %}

<details>

<summary>React 코드 예시</summary>

```js
import React, { useState, useEffect } from 'react';

/**
 * Genser Search React Component
 * 전제조건: public/index.html의 <head>에 Genser SDK 스크립트가 로드되어 있어야 합니다.
 */
const GenserSearch = () => {
  const [query, setQuery] = useState('');
  const [products, setProducts] = useState([]);
  const [requestId, setRequestId] = useState(null);
  
  // 인스턴스 키 (환경변수나 상수로 관리 권장)
  const INSTANCE_KEY = 'YOUR_INSTANCE_KEY';

  // 1. 검색 핸들러
  const handleSearch = (e) => {
    e.preventDefault();
    if (!query.trim()) return;

    if (!window.genser) {
      console.error("Genser SDK가 로드되지 않았습니다.");
      return;
    }

    // searchProducts 호출
    window.genser.call('searchProducts', {
      instanceKey: INSTANCE_KEY,
      queryText: query
    })
    .success((res) => {
      if (res.type === 'SEARCH') {
        // 상태 업데이트 -> 리렌더링 유발
        setProducts(res.products);
        setRequestId(res.requestId);
      }
    })
    .error((err) => {
      console.error('검색 에러:', err);
    });
  };

  // 2. 노출(DI) 로그 전송
  // products나 requestId가 변경되면(즉, 검색 결과가 렌더링되면) 실행
  useEffect(() => {
    if (products.length > 0 && requestId) {
      window.genser.call('DI', {
        instance: { key: INSTANCE_KEY },
        goods: products.map(p => ({ code: p.code, name: p.name })),
        requestId: requestId
      });
      // console.log('DI(노출) 로그 전송 완료');
    }
  }, [products, requestId]);

  // 3. 클릭(CL) 로그 전송 핸들러
  const handleProductClick = (product) => {
    if (!requestId) return;

    window.genser.call('CL', {
      instance: { key: INSTANCE_KEY },
      goods: [{ code: product.code, name: product.name }],
      requestId: requestId
    });
    // console.log('CL(클릭) 로그 전송 완료:', product.name);

    // 실제 상품 페이지로 이동 로직
    // window.location.href = `/product/${product.code}`;
  };

  return (
    <div className="genser-search-container">
      {/* 검색 폼 */}
      <form onSubmit={handleSearch}>
        <input 
          type="text" 
          value={query}
          onChange={(e) => setQuery(e.target.value)}
          placeholder="검색어를 입력하세요"
        />
        <button type="submit">검색</button>
      </form>

      {/* 검색 결과 리스트 */}
      <div className="product-list">
        {products.map((product) => (
          <div 
            key={product.code} 
            className="product-item"
            onClick={() => handleProductClick(product)}
            style={{ cursor: 'pointer', margin: '10px 0', border: '1px solid #ddd', padding: '10px' }}
          >
            {/* 이미지 처리 (API 응답에 따라 필드명 조정 필요) */}
            {product.imageUrl && <img src={product.imageUrl} alt={product.name} width="100" />}
            <h3>{product.name}</h3>
            <p>{product.code}</p>
          </div>
        ))}
      </div>
    </div>
  );
};

export default GenserSearch;
```

</details>

<details>

<summary>Vue 코드 예시</summary>

```js
<template>
  <div class="genser-search">
    <div class="search-bar">
      <input 
        v-model="query" 
        @keyup.enter="handleSearch" 
        placeholder="상품을 검색하세요" 
      />
      <button @click="handleSearch">검색</button>
    </div>

    <ul v-if="products.length > 0">
      <li 
        v-for="product in products" 
        :key="product.code" 
        @click="handleProductClick(product)"
      >
        {{ product.name }}
      </li>
    </ul>
  </div>
</template>

<script setup>
import { ref, watch } from 'vue';

// 전제조건: public/index.html의 <head>에 Genser SDK 스크립트가 로드되어 있어야 합니다. [cite: 64, 239]

// 어드민에서 발급받은 인스턴스 키 [cite: 11]
const INSTANCE_KEY = 'YOUR_INSTANCE_KEY';

const query = ref('');
const products = ref([]);
const requestId = ref(null);

// 1. 검색 핸들러 [cite: 95]
const handleSearch = () => {
  if (!query.value.trim()) return;

  if (!window.genser) {
    console.error("Genser SDK가 로드되지 않았습니다.");
    return;
  }

  // genser 검색 API 호출
  window.genser.call('searchProducts', {
    instanceKey: INSTANCE_KEY, // [cite: 98]
    queryText: query.value     // [cite: 99]
  })
  .success((res) => {
    // 응답 타입이 SEARCH인 경우 데이터 업데이트 [cite: 118]
    if (res.type === 'SEARCH') {
      products.value = res.products;   // [cite: 119]
      requestId.value = res.requestId; // [cite: 117]
    }
  })
  .error((err) => {
    console.error('검색 에러:', err);
  });
};

// 2. 노출(DI) 로그 전송 [cite: 177]
// products 상태가 변경되어 화면에 렌더링된 후 호출
watch([products, requestId], ([newProducts, newRequestId]) => {
  if (newProducts.length > 0 && newRequestId) {
    window.genser.call('DI', {
      instance: { key: INSTANCE_KEY }, // [cite: 180]
      goods: newProducts.map(p => ({ 
        code: p.code, 
        name: p.name 
      })), // [cite: 181]
      requestId: newRequestId // [cite: 186]
    })
    .success((res) => {
       // console.log('DI 로그 전송 성공');
    });
  }
});

// 3. 클릭(CL) 로그 전송 핸들러 [cite: 200]
const handleProductClick = (product) => {
  if (!requestId.value) return;

  window.genser.call('CL', {
    instance: { key: INSTANCE_KEY }, // [cite: 206]
    goods: [{ 
      code: product.code, 
      name: product.name 
    }], // [cite: 207]
    requestId: requestId.value // [cite: 212]
  })
  .success((res) => {
    console.log('CL 로그 전송 성공, 상품 페이지로 이동 로직 수행');
  });
};
</script>
```

</details>

<details>

<summary>HTML/JS 코드 예시</summary>

```js
<!DOCTYPE html>
<html lang="ko">
<head>
    <meta charset="UTF-8">
    <title>Genser Search Example</title>
    </head>
<body>

    <div id="search-container">
        <input type="text" id="searchInput" placeholder="검색어를 입력하세요">
        <button id="searchBtn">검색</button>
    </div>

    <ul id="resultList"></ul>

    <script type="text/javascript">
        // 설정 값
        const INSTANCE_KEY = 'YOUR_INSTANCE_KEY'; // [cite: 11]
        
        // 상태 변수
        let currentRequestId = null;

        // DOM 요소 참조
        const searchInput = document.getElementById('searchInput');
        const searchBtn = document.getElementById('searchBtn');
        const resultList = document.getElementById('resultList');

        // 1. 검색 버튼 클릭 이벤트
        searchBtn.addEventListener('click', function() {
            const query = searchInput.value;
            if (!query.trim()) return;
            
            doSearch(query);
        });

        // 검색 실행 함수 [cite: 95]
        function doSearch(queryText) {
            if (!window.genser) return console.error("SDK 미로드");

            window.genser.call('searchProducts', {
                instanceKey: INSTANCE_KEY, // [cite: 98]
                queryText: queryText       // [cite: 99]
            })
            .success((res) => {
                if (res.type === 'SEARCH') {
                    currentRequestId = res.requestId; // [cite: 117]
                    renderProducts(res.products);
                    
                    // 렌더링 직후 노출(DI) 로그 전송
                    sendImpressionLog(res.products, res.requestId);
                }
            })
            .error((err) => {
                console.error("검색 실패:", err);
            });
        }

        // 화면 렌더링 함수
        function renderProducts(products) {
            resultList.innerHTML = ''; // 기존 목록 초기화

            products.forEach(product => {
                const li = document.createElement('li');
                li.textContent = product.name;
                li.style.cursor = 'pointer';
                
                // 클릭 이벤트 바인딩
                li.addEventListener('click', () => {
                    handleProductClick(product);
                });

                resultList.appendChild(li);
            });
        }

        // 2. 노출(DI) 로그 전송 함수 [cite: 177]
        function sendImpressionLog(products, reqId) {
            window.genser.call('DI', {
                instance: { key: INSTANCE_KEY }, // [cite: 180]
                goods: products.map(p => ({
                    code: p.code,
                    name: p.name
                })), // [cite: 181]
                requestId: reqId // [cite: 186]
            });
        }

        // 3. 클릭(CL) 로그 전송 함수 [cite: 200]
        function handleProductClick(product) {
            if (!currentRequestId) return;

            window.genser.call('CL', {
                instance: { key: INSTANCE_KEY }, // [cite: 206]
                goods: [{
                    code: product.code,
                    name: product.name
                }], // [cite: 207]
                requestId: currentRequestId // [cite: 212]
            })
            .success(() => {
                console.log('클릭 로그 전송 완료: ' + product.name);
                // 이후 상품 상세 페이지 이동 등의 로직 수행
            });
        }
    </script>
</body>
</html>
```

</details>


# genser 활용 제안

<figure><img src="/files/xAnRiurm9bygSKhtoEKE" alt=""><figcaption></figcaption></figure>

사용자에게 AI 검색 UX를 어떤 방식으로 제공하느냐에 따라 검색 서비스의 실제 활용도와 만족도가 달라집니다. 서비스의 아이덴티티와 페이지 구조를 고려하여, 가장 몰입감 있는 최적의 검색 패턴을 적용해 보세요.

## 탭 전환형 (Explicit Toggle)

<figure><img src="/files/Mirx2F90loHX2NpK6qHZ" alt=""><figcaption></figcaption></figure>

* 로그인 회원에게만 AI 검색을 제공하고 싶을 때 사용하면 좋습니다.&#x20;
* 일반 검색과 AI 검색을 구분하여 사용하도록 유도할 수 있습니다.&#x20;
* AI 검색에 대한 고객의 인지를 점층적으로 높이고, 검색 목적 별로 고객에게 선택권을 줄 수 있습니다.&#x20;

{% hint style="info" %}
**Tip**

탭 전환 시 Placeholder(입력 안내 문구)를 함께 변경하여, 사용자가 어떤 검색어를 입력해야 할지 가이드를 주는 것이 중요합니다.
{% endhint %}

<details>

<summary>React 코드 예시</summary>

```javascript
const TabSearchPattern = () => {
  const [mode, setMode] = useState('AI'); // 'AI' | 'GENERAL'
  const [query, setQuery] = useState('');
  const [products, setProducts] = useState([]);
  const [requestId, setRequestId] = useState(null); // 검색 요청 ID 저장

  // 노출(DI) 로그 전송
  // 상품 목록(products)이 업데이트되고 화면 렌더링이 완료된 시점에 호출합니다.
  useEffect(() => {
    if (products.length > 0 && requestId) {
      window.genser.call('DI', {
        instance: { key: 'YOUR_INSTANCE_KEY' },
        goods: products.map(p => ({ code: p.code, name: p.name })),
        requestId: requestId
      });
      // console.log('DI 전송 완료');
    }
  }, [products, requestId]);

  // 클릭(CL) 로그 전송
  const handleProductClick = (product) => {
    if (!requestId) return;
    
    window.genser.call('CL', {
      instance: { key: 'YOUR_INSTANCE_KEY' },
      goods: [{ code: product.code, name: product.name }],
      requestId: requestId
    });
    
    // 이후 상품 상세 페이지로 이동
    console.log('CL 전송 완료, 페이지 이동:', product.name);
  };

  const handleSearch = (e) => {
    e.preventDefault();
    if (mode === 'AI') {
      // genser AI 검색 호출
      window.genser.call('searchProducts', {
        instanceKey: 'YOUR_INSTANCE_KEY',
        queryText: query
      }).success((res) => {
        if (res.type === 'SEARCH') {
          // 상태 업데이트 -> 리렌더링 발생 -> useEffect 실행 -> DI 전송
          setProducts(res.products);
          setRequestId(res.requestId);
        }
      });
    } else {
      console.log('일반 키워드 검색 실행:', query);
    }
  };

  return (
    <div>
      <div className="tabs">
        <button onClick={() => setMode('AI')} className={mode === 'AI' ? 'active' : ''}>AI 검색</button>
        <button onClick={() => setMode('GENERAL')} className={mode === 'GENERAL' ? 'active' : ''}>일반 검색</button>
      </div>
      <form onSubmit={handleSearch}>
        <input
          type="text"
          value={query}
          onChange={(e) => setQuery(e.target.value)}
          placeholder={mode === 'AI' ? "결혼식에 입고 갈 30대 여자 네이비 자켓 추천해줘!" : "검색어를 입력하세요"}
        />
        <button type="submit">검색</button>
      </form>
      
      {/* 결과 리스트 예시 */}
      <ul>
        {products.map(p => (
          <li key={p.code} onClick={() => handleProductClick(p)}>
            {p.name}
          </li>
        ))}
      </ul>
    </div>
  );
};

```

</details>

<details>

<summary>Vue 코드 예시</summary>

```python
<template>
  <div class="search-container">
    <div class="tabs">
      <button :class="{ active: mode === 'AI' }" @click="mode = 'AI'">✨ AI 검색</button>
      <button :class="{ active: mode === 'GENERAL' }" @click="mode = 'GENERAL'">일반 검색</button>
    </div>
    <div class="input-wrapper">
      <input 
        v-model="query" 
        @keyup.enter="handleSearch"
        :placeholder="placeholderText" 
      />
      <button @click="handleSearch">검색</button>
    </div>
    
    <!-- 결과 리스트 -->
    <ul>
      <li 
        v-for="p in products" 
        :key="p.code" 
        @click="handleProductClick(p)"
      >
        {{ p.name }}
      </li>
    </ul>
  </div>
</template>

<script setup>
import { ref, computed, nextTick } from 'vue';

const mode = ref('AI');
const query = ref('');
const products = ref([]);
const requestId = ref(null);

const placeholderText = computed(() => 
  mode.value === 'AI' ? "결혼식에 입고 갈 30대 여자 네이비 자켓 추천해줘!" : "검색어를 입력하세요"
);

const handleSearch = () => {
  if (mode.value === 'AI') {
    // 검색 API 호출
    window.genser.call('searchProducts', {
      instanceKey: 'YOUR_INSTANCE_KEY',
      queryText: query.value
    }).success((res) => {
      products.value = res.products;
      requestId.value = res.requestId;
      
      // DI 로그 전송 
      nextTick(() => {
        window.genser.call('DI', {
          instance: { key: 'YOUR_INSTANCE_KEY' },
          goods: res.products.map(p => ({ code: p.code, name: p.name })),
          requestId: res.requestId
        });
      });
    });
  } else {
    console.log('일반 검색 실행');
  }
};

// 클릭(CL) 로그 전송
const handleProductClick = (product) => {
  if (!requestId.value) return;
  
  window.genser.call('CL', {
    instance: { key: 'YOUR_INSTANCE_KEY' },
    goods: [{ code: product.code, name: product.name }],
    requestId: requestId.value
  });
  
  console.log('CL 전송 및 이동', product.name);
};
</script>
```

</details>

<details>

<summary>HTML/JS 코드 예시</summary>

```js
<div class="search-wrapper">
  <div class="tab-group">
    <button onclick="setMode('AI')" id="btn-ai" class="active">✨ AI 검색</button>
    <button onclick="setMode('GENERAL')" id="btn-gen">일반 검색</button>
  </div>
  <input type="text" id="search-input" placeholder="결혼식에 입고 갈 30대 여자 네이비 자켓 추천해줘!">
  <button onclick="executeSearch()">검색</button>
  
  <!-- 결과 리스트 영역 -->
  <ul id="result-list"></ul>
</div>

<script>
let currentMode = 'AI';
let currentRequestId = null; // 전역 변수나 상태로 requestId 관리

function setMode(mode) {
  // ... (기존과 동일)
}

function executeSearch() {
  const query = document.getElementById('search-input').value;
  
  if(currentMode === 'AI') {
    // AI 검색 호출
    genser.call('searchProducts', {
      instanceKey: 'YOUR_INSTANCE_KEY',
      queryText: query
    }).success(function(res) {
      currentRequestId = res.requestId; // ID 저장
      
      // 결과 렌더링
      renderList(res.products);
      
      // DI 로그 전송 (렌더링 직후)
      genser.call('DI', {
        instance: { key: 'YOUR_INSTANCE_KEY' },
        goods: res.products.map(p => ({ code: p.code, name: p.name })),
        requestId: res.requestId
      });
    });
  }
}

function renderList(products) {
  const ul = document.getElementById('result-list');
  ul.innerHTML = '';
  products.forEach(p => {
    const li = document.createElement('li');
    li.textContent = p.name;
    // 클릭 이벤트 바인딩
    li.onclick = function() {
      handleProductClick(p);
    };
    ul.appendChild(li);
  });
}

function handleProductClick(product) {
  if (!currentRequestId) return;
  
  genser.call('CL', {
    instance: { key: 'YOUR_INSTANCE_KEY' },
    goods: [{ code: product.code, name: product.name }],
    requestId: currentRequestId
  });
  
  console.log('CL 전송 및 이동', product.name);
}
</script>
```

</details>

## AI 검색 버튼 유도형 (Dropdown Nudge)

<figure><img src="/files/6Dojmr1a05ZImHKDlPHo" alt=""><figcaption></figcaption></figure>

* 기존 검색 UX를 해치지 않으면서 자연스럽게 AI 검색을 유도하는 방식입니다.&#x20;
* 사용자가 검색창을 클릭했을 때(Focus), 하단 드롭다운에 AI 검색 버튼을 노출합니다.
* AI 검색에 대한 고객 인지를 확실히 한 후 검색 페이지로 유도가 가능합니다.&#x20;

<details>

<summary>React 코드 예시</summary>

```javascript
const DropdownNudgePattern = () => {
  const [isFocused, setIsFocused] = useState(false);
  
  const goToAiSearch = () => {
    alert("AI 검색 모드로 전환!");
    // window.location.href = '/ai-search';
  };

  return (
    <div className="relative">
      <input
        type="text"
        placeholder="검색어를 입력하세요"
        onFocus={() => setIsFocused(true)}
        // Blur 시 바로 닫히면 버튼 클릭이 안 될 수 있으므로 약간의 지연을 줍니다.
        onBlur={() => setTimeout(() => setIsFocused(false), 200)}
      />
      
      {isFocused && (
        <div className="dropdown">
          {/* AI 검색 유도 버튼 */}
          <button onClick={goToAiSearch} className="ai-nudge-btn">
            <strong>✨ 내가 찾는 옷, AI에게 질문해보세요!</strong>
            <span>"이번주 하객룩 추천해줘"</span>
          </button>
          <ul><li>최근 검색어...</li></ul>
        </div>
      )}
    </div>
  );
};
```

</details>

<details>

<summary>Vue 코드 예시</summary>

```python
<template>
  <div class="search-wrap">
    <input 
      @focus="isFocused = true" 
      @blur="handleBlur"
      placeholder="검색어를 입력하세요" 
    />
    <div v-if="isFocused" class="dropdown">
      <button class="ai-nudge-btn" @click="goToAiSearch">
        <strong>✨ 내가 찾는 옷, AI에게 질문해보세요!</strong>
        <span>"이번주 하객룩 추천해줘"</span>
      </button>
      <ul class="history"><li>최근 검색어...</li></ul>
    </div>
  </div>
</template>

<script setup>
import { ref } from 'vue';
// ... (이전과 동일)
</script>
```

</details>

<details>

<summary>HTML/JS 코드 예시</summary>

```js
<div class="search-box">
  <input type="text" id="inp-search" placeholder="검색어를 입력하세요">
  <!-- 기본적으로 숨겨져 있다가 Focus 시 노출 -->
  <div id="dropdown" class="dropdown-content hidden">
    <button class="ai-nudge-btn" onclick="goToAiSearch()">
      <strong>✨ 내가 찾는 옷, AI에게 질문해보세요!</strong>
      <span>"이번주 하객룩 추천해줘"</span>
    </button>
    <div class="history">최근 검색어...</div>
  </div>
</div>

<script>
  const input = document.getElementById('inp-search');
  const dropdown = document.getElementById('dropdown');

  input.addEventListener('focus', () => {
    dropdown.classList.remove('hidden'); // CSS .hidden { display: none; }
  });
  
  // blur 시 숨김 처리 (setTimeout으로 클릭 이벤트 허용 시간 확보)
  input.addEventListener('blur', () => {
    setTimeout(() => dropdown.classList.add('hidden'), 200);
  });

  function goToAiSearch() {
    alert("AI 검색 모드로 전환!");
    // location.href = '/ai-search';
  }
</script>
<style>
  .hidden { display: none; }
  .dropdown-content { position: absolute; /* 스타일 생략 */ }
</style>

```

</details>

## 검색 몰입형 (Immersive/Focus)

<figure><img src="/files/m6uKI3e0tP3GW0UDKxiM" alt=""><figcaption></figcaption></figure>

* ChatGPT나 Gemini와 유사한 스타일로, 검색 자체가 메인 기능인 페이지에서 사용합니다.&#x20;
* 긴 문장의 질문도 편하게 입력할 수 있도록 넓은 입력 영역을 제공합니다.
* 질의 예시를 노출하여 AI 검색 활성화를 자연스럽게 유도합니다.&#x20;

<details>

<summary>React 코드 예시</summary>

```javascript
const ImmersiveSearch = () => {
  const [query, setQuery] = useState('');
  const [products, setProducts] = useState([]);
  const [requestId, setRequestId] = useState(null);
  const textareaRef = useRef(null);

  // DI 로그 전송
  useEffect(() => {
    if (products.length > 0 && requestId) {
      window.genser.call('DI', {
        instance: { key: 'YOUR_INSTANCE_KEY' },
        goods: products.map(p => ({ code: p.code, name: p.name })),
        requestId: requestId
      });
    }
  }, [products, requestId]);
  
  // CL 로그 전송
  const handleProductClick = (product) => {
    if (!requestId) return;
    window.genser.call('CL', {
      instance: { key: 'YOUR_INSTANCE_KEY' },
      goods: [{ code: product.code, name: product.name }],
      requestId: requestId
    });
  };

  const handleInput = (e) => {
    setQuery(e.target.value);
    if (textareaRef.current) {
      textareaRef.current.style.height = 'auto';
      textareaRef.current.style.height = `${textareaRef.current.scrollHeight}px`;
    }
  };

  const executeSearch = () => {
    window.genser.call('searchProducts', {
      instanceKey: 'YOUR_INSTANCE_KEY',
      queryText: query
    }).success((res) => {
      if(res.type === 'SEARCH') {
        setProducts(res.products);
        setRequestId(res.requestId);
      }
    });
  };

  return (
    <div className="immersive-box">
      <textarea
        ref={textareaRef}
        value={query}
        onInput={handleInput}
        rows={1}
        placeholder="AI에게 무엇이든 물어보세요."
      />
      <button onClick={executeSearch}>Send</button>
      
      {/* 결과 리스트 */}
      <ul>
          {products.map(p => (
            <li key={p.code} onClick={() => handleProductClick(p)}>{p.name}</li>
          ))}
      </ul>
    </div>
  );
};

```

</details>

<details>

<summary>Vue 코드 예시</summary>

```python
<template>
  <div class="immersive-box">
    <textarea
      ref="textarea"
      v-model="query"
      @input="resize"
      rows="1"
      placeholder="AI에게 무엇이든 물어보세요."
    ></textarea>
    <button @click="executeSearch">Send</button>

    <!-- 결과 리스트 -->
    <ul>
      <li v-for="p in products" :key="p.code" @click="handleProductClick(p)">
        {{ p.name }}
      </li>
    </ul>
  </div>
</template>

<script setup>
import { ref, nextTick } from 'vue';

const query = ref('');
const textarea = ref(null);
const products = ref([]);
const requestId = ref(null);

const resize = () => {
  const el = textarea.value;
  el.style.height = 'auto';
  el.style.height = el.scrollHeight + 'px';
};

const executeSearch = () => {
  window.genser.call('searchProducts', {
    instanceKey: 'YOUR_INSTANCE_KEY',
    queryText: query.value
  }).success((res) => {
    if (res.type === 'SEARCH') {
      products.value = res.products;
      requestId.value = res.requestId;

      // DI 로그 전송
      nextTick(() => {
        window.genser.call('DI', {
          instance: { key: 'YOUR_INSTANCE_KEY' },
          goods: res.products.map(p => ({ code: p.code, name: p.name })),
          requestId: res.requestId
        });
      });
    }
  });
};

// CL 로그 전송
const handleProductClick = (product) => {
  if (!requestId.value) return;
  window.genser.call('CL', {
    instance: { key: 'YOUR_INSTANCE_KEY' },
    goods: [{ code: product.code, name: product.name }],
    requestId: requestId.value
  });
};
</script>
```

</details>

<details>

<summary>HTML/JS 코드 예시</summary>

```js
<div class="immersive-box">
  <textarea id="ai-input" rows="1" placeholder="AI에게 무엇이든 물어보세요."></textarea>
  <button onclick="doSearch()">Send</button>
  <ul id="immersive-results"></ul>
</div>

<script>
  const tx = document.getElementById('ai-input');
  let currentRequestId = null;
  
  tx.addEventListener("input", function() {
    this.style.height = 'auto';
    this.style.height = (this.scrollHeight) + "px";
  });

  function doSearch() {
    const query = tx.value;
    genser.call('searchProducts', {
      instanceKey: 'YOUR_INSTANCE_KEY',
      queryText: query
    }).success(function(res) {
      if (res.type === 'SEARCH') {
        currentRequestId = res.requestId;
        renderImmersiveList(res.products);
        
        // DI 로그 전송
        genser.call('DI', {
          instance: { key: 'YOUR_INSTANCE_KEY' },
          goods: res.products.map(p => ({ code: p.code, name: p.name })),
          requestId: res.requestId
        });
      }
    });
  }

  function renderImmersiveList(products) {
    const ul = document.getElementById('immersive-results');
    ul.innerHTML = '';
    products.forEach(p => {
      const li = document.createElement('li');
      li.textContent = p.name;
      // CL 로그 전송 바인딩
      li.onclick = function() {
        if (currentRequestId) {
          genser.call('CL', {
            instance: { key: 'YOUR_INSTANCE_KEY' },
            goods: [{ code: p.code, name: p.name }],
            requestId: currentRequestId
          });
        }
      };
      ul.appendChild(li);
    });
  }
</script>
```

</details>

## 기존 검색창 연동형 (Simple Integration)

<figure><img src="/files/5mFGEx9zSdLUilWg7YVa" alt=""><figcaption></figcaption></figure>

* 별도의 UI/UX 변경 없이, 현재 사용 중인 검색창 로직에 genser 검색 엔진만 연결하는 방식입니다.
* 기존 검색창 UI를 그대로 유지함으로 UX에 대한 학습 등을 고객에게 요구하지 않고, AI 검색을 제공할 수 있습니다.&#x20;

<details>

<summary>React 코드 예시</summary>

```javascript
const SimpleSearch = () => {
  const [query, setQuery] = useState('');
  const [products, setProducts] = useState([]);
  const [requestId, setRequestId] = useState(null);

  // DI 로그 전송 (렌더링 직후)
  useEffect(() => {
    if (products.length > 0 && requestId) {
      window.genser.call('DI', {
        instance: { key: 'YOUR_INSTANCE_KEY' },
        goods: products.map(p => ({ code: p.code, name: p.name })),
        requestId: requestId
      });
    }
  }, [products, requestId]);

  // CL 로그 전송
  const handleProductClick = (product) => {
    if (!requestId) return;
    window.genser.call('CL', {
      instance: { key: 'YOUR_INSTANCE_KEY' },
      goods: [{ code: product.code, name: product.name }],
      requestId: requestId
    });
    // 이후 기존 상품 상세 페이지 이동 로직 실행
  };

  const handleSearch = (e) => {
    e.preventDefault();
    if (!query) return;

    // 기존 API 호출 대신 genser 호출
    window.genser.call('searchProducts', {
      instanceKey: 'YOUR_INSTANCE_KEY',
      queryText: query
    }).success((res) => {
      if (res.type === 'SEARCH') {
        // 기존 상태 업데이트 (변수명만 매핑)
        setProducts(res.products);
        setRequestId(res.requestId);
      }
    });
  };

  return (
    <div>
      <form onSubmit={handleSearch}>
        <input 
          type="text" 
          value={query}
          onChange={(e) => setQuery(e.target.value)}
          placeholder="결혼식에 입고 갈 30대 여자 네이비 자켓 추천해줘!"
        />
        <button type="submit">검색</button>
      </form>

      {/* 기존 결과 리스트 UI 유지 */}
      <ul>
        {products.map(p => (
          <li key={p.code} onClick={() => handleProductClick(p)}>
            {p.name}
          </li>
        ))}
      </ul>
    </div>
  );
};

```

</details>

<details>

<summary>Vue 코드 예시</summary>

```python
<template>
  <div class="search-container">
    <!-- 기존 검색 폼 -->
    <form @submit.prevent="handleSearch">
      <input v-model="query" placeholder="결혼식에 입고 갈 30대 여자 네이비 자켓 추천해줘!" />
      <button type="submit">검색</button>
    </form>

    <!-- 기존 결과 리스트 UI -->
    <ul>
      <li v-for="p in products" :key="p.code" @click="handleProductClick(p)">
        {{ p.name }}
      </li>
    </ul>
  </div>
</template>

<script setup>
import { ref, nextTick } from 'vue';

const query = ref('');
const products = ref([]);
const requestId = ref(null);

const handleSearch = () => {
  if (!query.value) return;

  // 기존 검색 로직을 genser 호출로 변경
  window.genser.call('searchProducts', {
    instanceKey: 'YOUR_INSTANCE_KEY',
    queryText: query.value
  }).success((res) => {
    if (res.type === 'SEARCH') {
      products.value = res.products;
      requestId.value = res.requestId;

      // DI 로그 전송 (DOM 업데이트 직후)
      nextTick(() => {
        window.genser.call('DI', {
          instance: { key: 'YOUR_INSTANCE_KEY' },
          goods: res.products.map(p => ({ code: p.code, name: p.name })),
          requestId: res.requestId
        });
      });
    }
  });
};

// CL 로그 전송
const handleProductClick = (product) => {
  if (!requestId.value) return;
  window.genser.call('CL', {
    instance: { key: 'YOUR_INSTANCE_KEY' },
    goods: [{ code: product.code, name: product.name }],
    requestId: requestId.value
  });
};
</script>
```

</details>

<details>

<summary>HTML/JS 코드 예시</summary>

```js
<div class="search-box">
  <input type="text" id="searchInput" placeholder="결혼식에 입고 갈 30대 여자 네이비 자켓 추천해줘!">
  <button onclick="executeSearch()">검색</button>
</div>
<ul id="resultList"></ul>

<script>
let currentRequestId = null;

function executeSearch() {
  const query = document.getElementById('searchInput').value;
  if (!query) return;

  // 기존 AJAX 호출 부분을 genser 호출로 교체
  genser.call('searchProducts', {
    instanceKey: 'YOUR_INSTANCE_KEY',
    queryText: query
  }).success(function(res) {
    if (res.type === 'SEARCH') {
      currentRequestId = res.requestId;
      renderList(res.products); // 기존 렌더링 함수 재사용

      // DI 로그 전송 (렌더링 직후)
      genser.call('DI', {
        instance: { key: 'YOUR_INSTANCE_KEY' },
        goods: res.products.map(p => ({ code: p.code, name: p.name })),
        requestId: res.requestId
      });
    }
  });
}

function renderList(products) {
  const ul = document.getElementById('resultList');
  ul.innerHTML = '';
  products.forEach(p => {
    const li = document.createElement('li');
    li.textContent = p.name;
    // CL 로그 전송 바인딩
    li.onclick = function() {
      handleProductClick(p);
    };
    ul.appendChild(li);
  });
}

function handleProductClick(product) {
  if (!currentRequestId) return;
  
  genser.call('CL', {
    instance: { key: 'YOUR_INSTANCE_KEY' },
    goods: [{ code: product.code, name: product.name }],
    requestId: currentRequestId
  });
  // 페이지 이동
}
</script>
```

</details>


# 사용자 행동 데이터 수집하기

<figure><img src="/files/v09TqPhwtIxIP6jlo8nA" alt=""><figcaption></figcaption></figure>

검색 이후 발생하는 사용자의 다양한 행동(클릭, 장바구니, 구매 등)을 genser로 전송하는 절차를 안내합니다. 수집된 데이터는 AI 모델의 고도화 학습에 사용되며, CVR(전환율) 및 CTR(클릭률) 등 주요 서비스 성과를 측정하고 평가하는 데 활용됩니다.

{% hint style="info" %}
**왜 행동 데이터를 연동해야 하나요?**

genser의 AI는 사용자가 어떤 상품을 클릭하고 구매했는지 학습하여, **검색 결과의 정확도를 높이고 개인화된 상품을 추천**합니다. 특히 **'구매 완료'** 데이터는 AI 학습에 가장 큰 가중치를 가지므로 반드시 연동되어야 합니다.
{% endhint %}

#### **✅ 수집 대상 이벤트 체크리스트**

개발 연동 전, 아래 표를 참고하여 우리 사이트에서 수집할 이벤트를 정의해 주세요.

<table><thead><tr><th width="82.65234375" data-type="checkbox">체크</th><th width="170.31640625">이벤트 명</th><th width="354.59765625">사용자 행동 시점 (Trigger)</th><th>문서 내 바로가기</th><th data-hidden>비고</th></tr></thead><tbody><tr><td>false</td><td>구매 완료</td><td>결제 완료 페이지 로딩 시</td><td><a href="https://docs.genser.ai/integration/action-data/action-data-integration#purchase">바로가기</a></td><td>최우선 필수 연동</td></tr><tr><td>false</td><td>결제 시작</td><td>주문서 작성 페이지 진입 시</td><td><a href="https://docs.genser.ai/integration/action-data/action-data-integration#purchase">바로가기</a></td><td></td></tr><tr><td>false</td><td>결제 취소</td><td>주문 취소 또는 환불 완료 시</td><td><a href="https://docs.genser.ai/integration/action-data/action-data-integration#purchase">바로가기</a></td><td></td></tr><tr><td>false</td><td>장바구니 담기</td><td>'장바구니 담기' 버튼 클릭 시</td><td><a href="https://docs.genser.ai/integration/action-data/action-data-integration#cart">바로가기</a></td><td></td></tr><tr><td>false</td><td>장바구니 제거</td><td>장바구니 페이지에서 상품 삭제 시</td><td><a href="https://docs.genser.ai/integration/action-data/action-data-integration#cart">바로가기</a></td><td></td></tr><tr><td>false</td><td>상품 클릭</td><td>검색 결과 리스트에서 상품 클릭 시</td><td><a href="https://docs.genser.ai/integration/action-data/action-data-integration#product">바로가기</a></td><td></td></tr><tr><td>false</td><td>위시리스트 추가</td><td>'찜하기(하트)' 버튼 클릭 시</td><td><a href="https://docs.genser.ai/integration/action-data/action-data-integration#wishlist">바로가기</a></td><td></td></tr><tr><td>false</td><td>검색어 제출</td><td>검색창에서 검색 실행 시</td><td><a href="https://docs.genser.ai/integration/action-data/action-data-integration#search">바로가기</a></td><td></td></tr></tbody></table>


# 행동 데이터 연동 가이드

<figure><img src="/files/MaIJgjHvajWHZ2CHUhWJ" alt=""><figcaption></figcaption></figure>

{% stepper %}
{% step %}

## 연동 준비하기 (Prepare)

API를 호출하기 위해 필요한 기본 정보입니다.

* **API Endpoint:** `https://statistics.genser.app`
* **Method:** `POST`
* **Content-Type:** `application/json` (또는 `application/ld+json`)
* **Service Key:** genser 어드민 \[설정] 메뉴에서 발급받은 `apiKey`

{% endstep %}

{% step %}

## 인증하기 (Authenticate)

준비된 키를 HTTP 요청 헤더(Header)에 설정합니다. 모든 API 요청 시 아래 헤더가 반드시 포함되어야 합니다.

<table><thead><tr><th width="180.8515625">필드명</th><th width="78.05859375">구분</th><th>설명</th></tr></thead><tbody><tr><td>Content-Type</td><td>필수</td><td>데이터 전송 형식을 JSON으로 지정합니다.</td></tr><tr><td>serviceKey</td><td>필수</td><td><strong>[인증키]</strong> genser 어드민 <code>설정</code>에서 발급받은 서비스 식별 키입니다. (비밀번호처럼 관리해주세요)</td></tr><tr><td>requestId</td><td>필수</td><td><strong>[추적키]</strong> 매 요청마다 새로 생성하는 고유 식별자입니다. (오류 추적용)</td></tr><tr><td>Idempotency-Key</td><td>필수</td><td><strong>[중복방지키]</strong> 네트워크 오류 등으로 인한 중복 처리를 막기 위한 키입니다.</td></tr></tbody></table>

{% hint style="success" %}
**Idempotency Key 포맷 상세 기준**

genser API는 UUID Version 4 표준 사용을 권장합니다.&#x20;

* **권장 형식:** 하이픈(-)이 포함된 표준 형식
* **글자 수 길이:**
  * **표준 (권장):** 하이픈 포함 시 총 36자 (예: `550e8400-e29b-41d4-a716-446655440000`)
  * **대체:** 하이픈 제거 시 총 32자 (예: `550e8400e29b41d4a716446655440000`)
    {% endhint %}

**HTTP 요청 헤더 예시:**

```
POST /actions/cart/add HTTP/1.1
Host: statistics.genser.app
Content-Type: application/json
serviceKey: cb37cce9d6ae434fa366151b3420a9af
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
requestId: req-20260112-001
```

{% endstep %}

{% step %}

## 데이터 전송하기 (Send Data)

사용자의 행동이 발생한 시점(버튼 클릭, 페이지 로드 등)에 맞춰 해당 API를 호출합니다. 아래 상황별 JSON 예시를 참고하여 데이터를 전송해 주세요. 상세한 필드 규격은 각 항목의 [**\[API 레퍼런스\]**](https://docs.genser.ai/integration/action-data/api-references)에서 확인하실 수 있습니다.

#### **장바구니 (Cart)**

**장바구니 추가 (Add to Cart)**

사용자가 '장바구니 담기' 버튼을 클릭했을 때 호출합니다.

**Path**: `/actions/cart/add`

[API 레퍼런스 확인하기](https://docs.genser.ai/integration/action-data/api-references/cart#post-actions-cart-add)

<details>

<summary><strong>본문(Body) 코드 샘플</strong></summary>

```js
{
  "specversion": "1.0.0",
  "id": "EVT-ADD-TO-CART-001",
  "type": "add_to_cart",
  "time": "2025-12-02T10:00:00Z",
  "source": "[https://shop.groobee.com](https://shop.groobee.com)",
  "data": {
    "@context": "[https://schema.org/](https://schema.org/)",
    "@type": "AddAction",
    "agent": {
      "@type": "Person",
      "identifier": [
        { "@type": "PropertyValue", "propertyID": "memberId", "value": "user1234" },
        { "@type": "PropertyValue", "propertyID": "userId", "value": "2aa9a562..." }
      ]
    },
    "object": {
      "@type": "OrderItem",
      "orderQuantity": 2,
      "orderedItem": {
        "@type": "Product",
        "sku": "131776",
        "name": [{ "@value": "소이 3인소파", "@language": "ko" }],
        "offers": { "@type": "Offer", "price": 1285000, "priceCurrency": "KRW" }
      }
    },
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "[https://www.groobee.com/cart](https://www.groobee.com/cart)"
    }
  }
}
```

</details>

**장바구니 제거 (Remove from Cart)**

사용자가 장바구니에서 상품을 삭제했을 때 호출합니다.

**Path**: `/actions/cart/remove`

[API 레퍼런스 확인하기](https://docs.genser.ai/integration/action-data/api-references/cart#post-actions-cart-remove)

<details>

<summary><strong>본문(Body) 코드 샘플</strong></summary>

```js
{
  "specversion": "1.0.0",
  "id": "EVT-REMOVE-FROM-CART-001",
  "type": "remove_from_cart",
  "time": "2025-12-02T10:10:00Z",
  "source": "[https://shop.groobee.com](https://shop.groobee.com)",
  "data": {
    "@context": "[https://schema.org/](https://schema.org/)",
    "@type": "DeleteAction",
    "agent": {
      "@type": "Person",
      "identifier": [
        { "@type": "PropertyValue", "propertyID": "memberId", "value": "user1234" }
      ]
    },
    "object": {
      "@type": "OrderItem",
      "orderQuantity": 1,
      "orderedItem": {
        "@type": "Product",
        "sku": "131776",
        "name": [{ "@value": "소이 3인소파", "@language": "ko" }],
        "offers": { "@type": "Offer", "price": 1285000, "priceCurrency": "KRW" }
      }
    },
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "[https://shop.groobee.com/cart](https://shop.groobee.com/cart)"
    }
  }
}
```

</details>

#### 주문/결제 (Purchase)

**결제 시작 (Start Checkout)**

사용자가 주문서 작성 페이지에 진입했을 때 호출합니다.

**Path**: `/actions/purchase/checkout`

[API 레퍼런스 확인하기](https://docs.genser.ai/integration/action-data/api-references/purchase#post-actions-purchase-checkout)

<details>

<summary><strong>본문(Body) 코드 샘플</strong></summary>

```js
{
  "specversion": "1.0.0",
  "id": "EVT-START-CHECKOUT-001",
  "type": "start_checkout",
  "time": "2025-12-02T10:20:00Z",
  "source": "[https://shop.groobee.com](https://shop.groobee.com)",
  "data": {
    "@context": "[https://schema.org/](https://schema.org/)",
    "@type": "CheckoutAction",
    "agent": {
      "@type": "Person",
      "identifier": [
        { "@type": "PropertyValue", "propertyID": "memberId", "value": "user1234" }
      ]
    },
    "object": {
      "@type": "OrderItem",
      "orderQuantity": 1,
      "orderedItem": {
        "@type": "Product",
        "sku": "131776",
        "name": [{ "@value": "소이 3인소파", "@language": "ko" }],
        "offers": { "@type": "Offer", "price": 1285000, "priceCurrency": "KRW" }
      }
    },
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "[https://shop.groobee.com/purchase/checkout](https://shop.groobee.com/purchase/checkout)"
    }
  }
}
```

</details>

**결제 완료 (Complete Purchase)**

결제가 성공적으로 완료된 시점(주문 완료 페이지)에 호출합니다. **가장 중요한 데이터**입니다.

**Path**: `/actions/purchase/complete`

[API 레퍼런스 확인하기](https://docs.genser.ai/integration/action-data/api-references/purchase#post-actions-purchase-complete)

<details>

<summary><strong>본문(Body) 코드 샘플</strong></summary>

```js
{
  "specversion": "1.0.0",
  "id": "EVT-COMPLETE-PURCHASE-001",
  "type": "complete_purchase",
  "time": "2025-12-02T10:25:00Z",
  "source": "[https://shop.groobee.com](https://shop.groobee.com)",
  "data": {
    "@context": "[https://schema.org/](https://schema.org/)",
    "@type": "OrderAction",
    "agent": {
      "@type": "Person",
      "identifier": [
        { "@type": "PropertyValue", "propertyID": "memberId", "value": "user1234" }
      ]
    },
    "object": [
      {
        "@type": "OrderItem",
        "orderQuantity": 1,
        "orderedItem": {
          "@type": "Product",
          "sku": "131776",
          "name": [{ "@value": "소이 3인소파", "@language": "ko" }],
          "offers": { "@type": "Offer", "price": 1285000, "priceCurrency": "KRW" }
        }
      }
    ],
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "[https://shop.groobee.com/purchase/complete](https://shop.groobee.com/purchase/complete)"
    }
  }
}
```

</details>

**결제 취소 (Cancel Purchase)**

사용자가 결제를 취소하거나 주문을 철회했을 때 호출합니다.

**Path**: `/actions/purchase/cancel`

[API 레퍼런스 확인하기](https://docs.genser.ai/integration/action-data/api-references/purchase#post-actions-purchase-cancel)

<details>

<summary><strong>본문(Body) 코드 샘플</strong></summary>

```js
{
  "specversion": "1.0.0",
  "id": "EVT-CANCEL-PURCHASE-001",
  "type": "cancel_purchase",
  "time": "2025-12-02T11:00:00Z",
  "source": "[https://shop.groobee.com](https://shop.groobee.com)",
  "data": {
    "@context": "[https://schema.org/](https://schema.org/)",
    "@type": "CancelAction",
    "agent": {
      "@type": "Person",
      "identifier": [
        { "@type": "PropertyValue", "propertyID": "memberId", "value": "user1234" }
      ]
    },
    "object": {
      "@type": "OrderItem",
      "orderQuantity": 1,
      "orderedItem": {
        "@type": "Product",
        "sku": "131776",
        "name": [{ "@value": "소이 3인소파", "@language": "ko" }],
        "offers": { "@type": "Offer", "price": 1285000, "priceCurrency": "KRW" }
      }
    },
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "[https://shop.groobee.com/purchase/cancel](https://shop.groobee.com/purchase/cancel)"
    }
  }
}

```

</details>

#### 검색 (Search)

**검색어 제출 (Search Submitted)**

사용자가 검색창에 검색어를 입력하고 엔터키를 치거나 돋보기 아이콘을 눌렀을 때 호출합니다.

**Path**: `/actions/search/submitted`

[API 레퍼런스 확인하기](https://docs.genser.ai/integration/action-data/api-references/search#post-actions-search-submitted)

<details>

<summary><strong>본문(Body) 코드 샘플</strong></summary>

```js
{
  "specversion": "1.0.0",
  "id": "EVT-SEARCH-SUBMITTED-001",
  "type": "search_submitted",
  "time": "2025-11-28T10:00:00Z",
  "source": "[https://shop.groobee.com](https://shop.groobee.com)",
  "data": {
    "@context": "[https://schema.org/](https://schema.org/)",
    "@type": "SearchAction",
    "agent": {
      "@type": "Person",
      "identifier": [
        { "@type": "PropertyValue", "propertyID": "memberId", "value": "user1234" }
      ],
      "gender": "Female",
      "additionalProperty": [
        { "@type": "PropertyValue", "propertyID": "age", "value": 18 }
      ]
    },
    "query": "편안한 소파 찾아줘",
    "object": {
      "@type": "Thing",
      "actionOption": [
        { "@type": "PropertyValue", "propertyID": "search_type", "value": "AI" },
        { "@type": "PropertyValue", "propertyID": "color", "value": "검정" }
      ]
    },
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "[https://shop.groobee.com/search?color=검정](https://shop.groobee.com/search?color=검정)"
    }
  }
}
```

</details>

**검색 결과 조회 (View Search Result)**

검색 결과 리스트 페이지가 로딩되었을 때 호출합니다.

**Path**: `/actions/search/result`

[API 레퍼런스 확인하기](https://docs.genser.ai/integration/action-data/api-references/search#post-actions-search-result)

<details>

<summary><strong>본문(Body) 코드 샘플</strong></summary>

```js
{
  "specversion": "1.0.0",
  "id": "EVT-VIEW-SEARCH-RESULT-001",
  "type": "view_search_result",
  "time": "2025-11-28T10:00:00Z",
  "source": "[https://shop.groobee.com](https://shop.groobee.com)",
  "data": {
    "@context": "[https://schema.org/](https://schema.org/)",
    "@type": "ViewAction",
    "agent": {
      "@type": "Person",
      "identifier": [
        { "@type": "PropertyValue", "propertyID": "memberId", "value": "user1234" }
      ]
    },
    "object": {
      "@type": "ItemList",
      "numberOfItems": 1,
      "itemListElement": {
        "@type": "ListItem",
        "item": {
          "@type": "Product",
          "sku": "131776",
          "name": "소이 3인소파"
        },
        "position": 1
      }
    },
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "[https://shop.groobee.com/search](https://shop.groobee.com/search)"
    }
  }
}
```

</details>

#### 상품 (Product)

**상품 상세 조회 (View Product)**

상품 상세 페이지(PDP)에 진입했을 때 호출합니다.

**Path**: `/actions/view/product`

[API 레퍼런스 확인하기](https://docs.genser.ai/integration/action-data/api-references/view#post-actions-view-product)

<details>

<summary><strong>본문(Body) 코드 샘플</strong></summary>

```js
{
  "specversion": "1.0.0",
  "id": "EVT-VIEW-PRODUCT-001",
  "type": "view_product",
  "time": "2025-11-28T10:00:00Z",
  "source": "[https://shop.groobee.com](https://shop.groobee.com)",
  "data": {
    "@context": "[https://schema.org/](https://schema.org/)",
    "@type": "ViewAction",
    "agent": {
      "@type": "Person",
      "identifier": [
        { "@type": "PropertyValue", "propertyID": "memberId", "value": "user1234" }
      ]
    },
    "object": {
      "@type": "Product",
      "sku": "131776",
      "name": [{ "@value": "소이 3인소파", "@language": "ko" }]
    },
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "[https://shop.groobee.com/product/131776](https://shop.groobee.com/product/131776)"
    }
  }
}
```

</details>

**상품 클릭 (Click Product)**

리스트에서 특정 상품을 클릭했을 때 호출합니다.

**Path**: `/actions/click/product`

[API 레퍼런스 확인하기](https://docs.genser.ai/integration/action-data/api-references/product#post-actions-click-product)

<details>

<summary><strong>본문(Body) 코드 샘플</strong></summary>

```js
{
  "specversion": "1.0.0",
  "id": "EVT-CLICK-PRODUCT-001",
  "type": "click_product",
  "time": "2025-11-28T10:00:00Z",
  "source": "[https://shop.groobee.com](https://shop.groobee.com)",
  "data": {
    "@context": "[https://schema.org/](https://schema.org/)",
    "@type": "ChooseAction",
    "agent": {
      "@type": "Person",
      "identifier": [
        { "@type": "PropertyValue", "propertyID": "memberId", "value": "user1234" }
      ]
    },
    "object": {
      "@type": "ItemList",
      "itemListElement": {
        "@type": "ListItem",
        "position": 1,
        "item": {
          "@type": "Product",
          "sku": "131776",
          "name": [{ "@value": "소이 3인소파", "@language": "ko" }]
        }
      }
    },
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "[https://shop.groobee.com/product/131776](https://shop.groobee.com/product/131776)"
    }
  }
}
```

</details>

#### 위시리스트 (Wishlist)

**위시리스트 등록 (Add to Wishlist)**

'찜하기' 또는 '위시리스트 추가' 버튼 클릭 시 호출합니다.

**Path**: `/actions/wishlist/add=`

[API 레퍼런스 확인하기](https://docs.genser.ai/integration/action-data/api-references/wishlist#post-actions-wishlist-add)

<details>

<summary><strong>본문(Body) 코드 샘플</strong></summary>

```js
{
  "specversion": "1.0.0",
  "id": "EVT-ADD-TO-WISHLIST-001",
  "type": "add_to_wishlist",
  "time": "2025-12-02T10:00:00Z",
  "source": "[https://shop.groobee.com](https://shop.groobee.com)",
  "data": {
    "@context": "[https://schema.org/](https://schema.org/)",
    "@type": "AddAction",
    "agent": {
      "@type": "Person",
      "identifier": [
        { "@type": "PropertyValue", "propertyID": "memberId", "value": "user1234" }
      ]
    },
    "object": {
      "@type": "OrderItem",
      "orderedItem": {
        "@type": "Product",
        "sku": "131776",
        "name": [{ "@value": "소이 3인소파", "@language": "ko" }],
        "offers": { "@type": "Offer", "price": 1285000, "priceCurrency": "KRW" }
      }
    },
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "[https://shop.groobee.com/wishlist](https://shop.groobee.com/wishlist)"
    }
  }
}

```

</details>

**위시리스트 제거 (Remove from Wishlist)**

위시리스트에서 상품을 삭제할 때 호출합니다.

**Path**: `/actions/wishlist/remove`

[API 레퍼런스 확인하기](https://docs.genser.ai/integration/action-data/api-references/wishlist#post-actions-wishlist-remove)

<details>

<summary><strong>본문(Body) 코드 샘플</strong></summary>

```js
{
  "specversion": "1.0.0",
  "id": "EVT-REMOVE-FROM-WISHLIST-001",
  "type": "remove_from_wishlist",
  "time": "2025-12-02T10:05:00Z",
  "source": "[https://shop.groobee.com](https://shop.groobee.com)",
  "data": {
    "@context": "[https://schema.org/](https://schema.org/)",
    "@type": "DeleteAction",
    "agent": {
      "@type": "Person",
      "identifier": [
        { "@type": "PropertyValue", "propertyID": "memberId", "value": "user1234" }
      ]
    },
    "object": {
      "@type": "OrderItem",
      "orderedItem": {
        "@type": "Product",
        "sku": "131776",
        "name": [{ "@value": "소이 3인소파", "@language": "ko" }],
        "offers": { "@type": "Offer", "price": 1285000, "priceCurrency": "KRW" }
      }
    },
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "[https://shop.groobee.com/wishlist](https://shop.groobee.com/wishlist)"
    }
  }
}
```

</details>

{% endstep %}

{% step %}

## 응답 확인하기 (Check Response)

API 호출 후 HTTP 상태 코드를 확인하여 전송 성공 여부를 판단합니다.

<table><thead><tr><th width="166.3515625">상태 코드</th><th width="117.9609375">결과</th><th>설명</th></tr></thead><tbody><tr><td>200 OK</td><td>성공</td><td>성공입니다. 다음날 00:15am 배치를 통해 반영됩니다.</td></tr><tr><td>400 Bad Request</td><td>요청 형식 오류</td><td>JSON 문법이 틀렸거나, 필수 값(<code>sku</code>, <code>name</code> 등)이 누락되었는지 확인하세요.</td></tr><tr><td>401 Unauthorized</td><td>인증 실패</td><td><code>serviceKey</code>가 유효하지 않거나 누락되었습니다.</td></tr><tr><td>500 Internal Error</td><td>서버 오류</td><td>일시적인 장애일 수 있습니다. 잠시 후 재시도(Retry) 로직을 실행하세요.</td></tr></tbody></table>

{% endstep %}

{% step %}

## 연동 결과 확인하기 (Verify)

API 연동 후 데이터가 정상적으로 쌓이고 있는지 genser 어드민에서 확인할 수 있습니다.&#x20;

1. [대시보드 화면](/ai-search/dash-old)의 통계 지표를 통해 이벤트 건수가 정상적으로 집계되는지 확인합니다.
2. [검색 인사이트 화면](/ai-search/analytics)의 통계 지표를 통해 이벤트 건수가 정상적으로 집계되는지 확인합니다.&#x20;

#### 데이터 반영 및 갱신 시점 안내

genser는 데이터의 성격에 따라 실시간 반영과 정기 업데이트(Batch)를 구분하여 운영합니다. 확인하고자 하는 데이터 종류에 따른 갱신 시점과 기준 시간대를 참고해 주십시오.

<table><thead><tr><th width="115.78125">데이터 구분</th><th width="215.25390625">조회 대상</th><th width="220.6328125">갱신 시점</th><th>기준 시간대</th></tr></thead><tbody><tr><td>검색 로그</td><td>전체 검색 이력 목록</td><td>실시간 (Real-time)</td><td>UTC</td></tr><tr><td>통계/분석</td><td>'오늘(Today)' 조회 시</td><td>매 시간 5분 (예: 11:05)</td><td>KST (한국 시간)</td></tr><tr><td>통계/분석</td><td>'어제' 및 과거 기간 조회 시</td><td>매일 00시 (자정)</td><td>KST (한국 시간)</td></tr></tbody></table>
{% endstep %}
{% endstepper %}


# API 레퍼런스

<figure><img src="/files/lNDw13re4aIPGyeS9m9m" alt=""><figcaption></figcaption></figure>

#### genser 이벤트 수집 API 규격

genser의 이벤트 수집 API는 시스템 간 호환성과 명확한 데이터 의미 전달을 위해 글로벌 표준 기술을 기반으로 설계되었습니다. 이벤트의 최상위 전송 규격은 **CNCF의 CloudEvents 1.0을 준수**하여 다양한 클라우드 환경에서의 표준화된 처리를 보장합니다.&#x20;

또한, 실제 사용자 행동 데이터는 **Schema.org의 Action 모델**을 채택하여 '행위자(Agent)-대상(Object)-목표(Target)'의 문맥을 구조적으로 정의합니다. 이러한 표준화된 설계를 통해 개발자는 예측 가능한 구조로 손쉽게 연동할 수 있으며, 비즈니스 환경에 맞는 데이터의 투명성과 확장성을 확보할 수 있습니다.

**주요 준수 규격:**

* 전송 포맷: CloudEvents 1.0 (이벤트 라우팅 및 메타데이터 식별)
* 데이터 모델: Schema.org Actions (사용자 행동의 구조적 표현)


# 장바구니 (Cart)

장바구니 관련 사용자 행동 수집 API

## 사용자 행동수집 - 장바구니 추가

> 장바구니 추가 수집 API

```json
{"openapi":"3.1.0","info":{"title":"젠서 이벤트 수집 API (기본)","version":"1.0.0"},"tags":[{"name":"장바구니 (Cart)","description":"장바구니 관련 사용자 행동 수집 API"}],"servers":[{"url":"https://statistics.genser.app","description":"Production"},{"url":"http://localhost","description":"Local Development (포트 80)"},{"url":"http://localhost:8080","description":"Local Development (포트 8080)"}],"paths":{"/actions/cart/add":{"post":{"summary":"사용자 행동수집 - 장바구니 추가","description":"장바구니 추가 수집 API","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)"},{"name":"serviceKey","in":"header","required":true,"schema":{"type":"string"},"description":"서비스키"},{"name":"requestId","in":"header","required":true,"schema":{"type":"string"},"description":"리퀘스트 아이디"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionsCartAddEvent"}}}},"responses":{"200":{"description":"수집 성공"},"400":{"description":"잘못된 요청"},"503":{"description":"서비스 일시 불가"}}}}},"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.genser.app/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":"행위자 아이디 속성명"},"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":"추가 속성 필드명"},"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)"}}}}}}
```

## 사용자 행동수집 - 장바구니 제거

> 장바구니 제거 수집 API

```json
{"openapi":"3.1.0","info":{"title":"젠서 이벤트 수집 API (기본)","version":"1.0.0"},"tags":[{"name":"장바구니 (Cart)","description":"장바구니 관련 사용자 행동 수집 API"}],"servers":[{"url":"https://statistics.genser.app","description":"Production"},{"url":"http://localhost","description":"Local Development (포트 80)"},{"url":"http://localhost:8080","description":"Local Development (포트 8080)"}],"paths":{"/actions/cart/remove":{"post":{"summary":"사용자 행동수집 - 장바구니 제거","description":"장바구니 제거 수집 API","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)"},{"name":"serviceKey","in":"header","required":true,"schema":{"type":"string"},"description":"서비스키"},{"name":"requestId","in":"header","required":true,"schema":{"type":"string"},"description":"리퀘스트 아이디"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionsCartRemoveEvent"}}}},"responses":{"200":{"description":"수집 성공"},"400":{"description":"잘못된 요청"},"503":{"description":"서비스 일시 불가"}}}}},"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.genser.app/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":"행위자 아이디 속성명"},"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":"추가 속성 필드명"},"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)"}}}}}}
```


# 상품 (Product)

상품 관련 사용자 행동 수집 API

## 사용자 행동수집 - 상품 클릭

> 상품 클릭 수집 API

```json
{"openapi":"3.1.0","info":{"title":"젠서 이벤트 수집 API (기본)","version":"1.0.0"},"tags":[{"name":"상품 (Product)","description":"상품 관련 사용자 행동 수집 API"}],"servers":[{"url":"https://statistics.genser.app","description":"Production"},{"url":"http://localhost","description":"Local Development (포트 80)"},{"url":"http://localhost:8080","description":"Local Development (포트 8080)"}],"paths":{"/actions/click/product":{"post":{"summary":"사용자 행동수집 - 상품 클릭","description":"상품 클릭 수집 API","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)"},{"name":"serviceKey","in":"header","required":true,"schema":{"type":"string"},"description":"서비스키"},{"name":"requestId","in":"header","required":true,"schema":{"type":"string"},"description":"리퀘스트 아이디"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionsClickProductEvent"}}}},"responses":{"200":{"description":"수집 성공"},"400":{"description":"잘못된 요청"},"503":{"description":"서비스 일시 불가"}}}}},"components":{"schemas":{"ActionsClickProductEvent":{"title":"사용자 행동수집 - 상품 클릭","description":"사용자가 상품을 클릭한 행동을 수집하는 API","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.genser.app/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":"행위자 아이디 속성명"},"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":"추가 속성 필드명"},"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":{"type":"object","required":["itemListElement"],"properties":{"@type":{"type":"string","enum":["ItemList"]},"itemListElement":{"$ref":"#/components/schemas/ActionsClickProductListItem"}}},"ActionsClickProductListItem":{"type":"object","required":["position","item"],"properties":{"@type":{"type":"string","enum":["ListItem"]},"item":{"$ref":"#/components/schemas/ActionsClickProductProduct"},"position":{"type":"number"}}},"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":"언어 코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"언어 코드","enum":["ko","en","ja"]}}}}]}}}}}}
```


# 결제 (Purchase)

결제 관련 사용자 행동 수집 API

## 사용자 행동수집 - 결제취소

> 결제취소 수집 API

```json
{"openapi":"3.1.0","info":{"title":"젠서 이벤트 수집 API (기본)","version":"1.0.0"},"tags":[{"name":"결제 (Purchase)","description":"결제 관련 사용자 행동 수집 API"}],"servers":[{"url":"https://statistics.genser.app","description":"Production"},{"url":"http://localhost","description":"Local Development (포트 80)"},{"url":"http://localhost:8080","description":"Local Development (포트 8080)"}],"paths":{"/actions/purchase/cancel":{"post":{"summary":"사용자 행동수집 - 결제취소","description":"결제취소 수집 API","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)"},{"name":"serviceKey","in":"header","required":true,"schema":{"type":"string"},"description":"서비스키"},{"name":"requestId","in":"header","required":true,"schema":{"type":"string"},"description":"리퀘스트 아이디"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionsPurchaseCancelEvent"}}}},"responses":{"200":{"description":"수집 성공"},"400":{"description":"잘못된 요청"},"503":{"description":"서비스 일시 불가"}}}}},"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.genser.app/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":"행위자 아이디 속성명"},"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":"추가 속성 필드명"},"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)"}}}}}}
```

## 사용자 행동수집 - 결제시작

> 결제시작 수집 API

```json
{"openapi":"3.1.0","info":{"title":"젠서 이벤트 수집 API (기본)","version":"1.0.0"},"tags":[{"name":"결제 (Purchase)","description":"결제 관련 사용자 행동 수집 API"}],"servers":[{"url":"https://statistics.genser.app","description":"Production"},{"url":"http://localhost","description":"Local Development (포트 80)"},{"url":"http://localhost:8080","description":"Local Development (포트 8080)"}],"paths":{"/actions/purchase/checkout":{"post":{"summary":"사용자 행동수집 - 결제시작","description":"결제시작 수집 API","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)"},{"name":"serviceKey","in":"header","required":true,"schema":{"type":"string"},"description":"서비스키"},{"name":"requestId","in":"header","required":true,"schema":{"type":"string"},"description":"리퀘스트 아이디"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionsPurchaseCheckoutEvent"}}}},"responses":{"200":{"description":"수집 성공"},"400":{"description":"잘못된 요청"},"503":{"description":"서비스 일시 불가"}}}}},"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.genser.app/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":"행위자 아이디 속성명"},"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":"추가 속성 필드명"},"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)"}}}}}}
```

## 사용자 행동수집 - 결제완료

> 결제완료 수집 API

```json
{"openapi":"3.1.0","info":{"title":"젠서 이벤트 수집 API (기본)","version":"1.0.0"},"tags":[{"name":"결제 (Purchase)","description":"결제 관련 사용자 행동 수집 API"}],"servers":[{"url":"https://statistics.genser.app","description":"Production"},{"url":"http://localhost","description":"Local Development (포트 80)"},{"url":"http://localhost:8080","description":"Local Development (포트 8080)"}],"paths":{"/actions/purchase/complete":{"post":{"summary":"사용자 행동수집 - 결제완료","description":"결제완료 수집 API","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)"},{"name":"serviceKey","in":"header","required":true,"schema":{"type":"string"},"description":"서비스키"},{"name":"requestId","in":"header","required":true,"schema":{"type":"string"},"description":"리퀘스트 아이디"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionsPurchaseCompleteEvent"}}}},"responses":{"200":{"description":"수집 성공"},"400":{"description":"잘못된 요청"},"503":{"description":"서비스 일시 불가"}}}}},"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.genser.app/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":"행위자 아이디 속성명"},"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":"추가 속성 필드명"},"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)"}}}}}}
```


# 검색 (Search)

검색 관련 사용자 행동 수집 API

## 사용자 행동수집 - 검색 결과

> 검색 결과 수집 API

```json
{"openapi":"3.1.0","info":{"title":"젠서 이벤트 수집 API (기본)","version":"1.0.0"},"tags":[{"name":"검색 (Search)","description":"검색 관련 사용자 행동 수집 API"}],"servers":[{"url":"https://statistics.genser.app","description":"Production"},{"url":"http://localhost","description":"Local Development (포트 80)"},{"url":"http://localhost:8080","description":"Local Development (포트 8080)"}],"paths":{"/actions/search/result":{"post":{"summary":"사용자 행동수집 - 검색 결과","description":"검색 결과 수집 API","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)"},{"name":"serviceKey","in":"header","required":true,"schema":{"type":"string"},"description":"서비스키"},{"name":"requestId","in":"header","required":true,"schema":{"type":"string"},"description":"리퀘스트 아이디"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionsSearchResultEvent"}}}},"responses":{"200":{"description":"수집 성공"},"400":{"description":"잘못된 요청"},"503":{"description":"서비스 일시 불가"}}}}},"components":{"schemas":{"ActionsSearchResultEvent":{"title":"사용자 행동수집 - 검색 결과","description":"사용자에게 검색결과가 노출된 행동을 수집하는 API","type":"object","required":["time","source","data"],"properties":{"specversion":{"type":"string","description":"스펙 버전","enum":["1.0.0"]},"id":{"type":"string","description":"이벤트 고유 식별자","enum":["EVT-SEARCH-RESULT"]},"type":{"type":"string","description":"이벤트 유형","enum":["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.genser.app/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":"행위자 아이디 속성명"},"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":"추가 속성 필드명"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"추가 속성 필드 값"}}},"type":"array","description":"행위자 추가 속성 (회원등급, 연령 등)"}}},"object":{"oneOf":[{"$ref":"#/components/schemas/ActionsSearchResultItemList"},{"type":"array","items":{"$ref":"#/components/schemas/ActionsSearchResultItemList"}}]},"target":{"type":"object","description":"검색 엔드포인트 정보","required":["urlTemplate"],"properties":{"@type":{"type":"string","enum":["EntryPoint"]},"urlTemplate":{"type":"string","description":"검색 URL"}}}}}}},"ActionsSearchResultItemList":{"type":"object","required":["numberOfItems","itemListElement"],"properties":{"@type":{"type":"string","enum":["ItemList"]},"numberOfItems":{"type":"number"},"itemListElement":{"$ref":"#/components/schemas/ActionsSearchResultListItem"}}},"ActionsSearchResultListItem":{"type":"object","required":["position","item"],"properties":{"@type":{"type":"string","enum":["ListItem"]},"item":{"$ref":"#/components/schemas/ActionsSearchResultProduct"},"position":{"type":"number"}}},"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":"언어 코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"언어 코드","enum":["ko","en","ja"]}}}}]},"position":{"type":"number","description":"검색결과 내 순위"}}}}}}
```

## 사용자 행동수집 - 검색 제출

> 검색 제출 수집 API

```json
{"openapi":"3.1.0","info":{"title":"젠서 이벤트 수집 API (기본)","version":"1.0.0"},"tags":[{"name":"검색 (Search)","description":"검색 관련 사용자 행동 수집 API"}],"servers":[{"url":"https://statistics.genser.app","description":"Production"},{"url":"http://localhost","description":"Local Development (포트 80)"},{"url":"http://localhost:8080","description":"Local Development (포트 8080)"}],"paths":{"/actions/search/submitted":{"post":{"summary":"사용자 행동수집 - 검색 제출","description":"검색 제출 수집 API","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)"},{"name":"serviceKey","in":"header","required":true,"schema":{"type":"string"},"description":"서비스키"},{"name":"requestId","in":"header","required":true,"schema":{"type":"string"},"description":"리퀘스트 아이디"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionsSearchSubmittedEvent"}}}},"responses":{"200":{"description":"수집 성공"},"400":{"description":"잘못된 요청"},"503":{"description":"서비스 일시 불가"}}}}},"components":{"schemas":{"ActionsSearchSubmittedEvent":{"title":"사용자 행동수집 - 검색 제출","description":"사용자가 검색어를 제출한 행동을 수집하는 API","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.genser.app/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":"행위자 아이디 속성명"},"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":"추가 속성 필드명"},"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":"검색 필터 속성명"},"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"}}}}}}}}}}
```


# 조회 (View)

상품 조회 관련 사용자 행동 수집 API

## 사용자 행동수집 - 상세조회

> 상품 상세조회 수집 API

```json
{"openapi":"3.1.0","info":{"title":"젠서 이벤트 수집 API (기본)","version":"1.0.0"},"tags":[{"name":"조회 (View)","description":"상품 조회 관련 사용자 행동 수집 API"}],"servers":[{"url":"https://statistics.genser.app","description":"Production"},{"url":"http://localhost","description":"Local Development (포트 80)"},{"url":"http://localhost:8080","description":"Local Development (포트 8080)"}],"paths":{"/actions/view/product":{"post":{"summary":"사용자 행동수집 - 상세조회","description":"상품 상세조회 수집 API","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)"},{"name":"serviceKey","in":"header","required":true,"schema":{"type":"string"},"description":"서비스키"},{"name":"requestId","in":"header","required":true,"schema":{"type":"string"},"description":"리퀘스트 아이디"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionsViewProductEvent"}}}},"responses":{"200":{"description":"수집 성공"},"400":{"description":"잘못된 요청"},"503":{"description":"서비스 일시 불가"}}}}},"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.genser.app/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":"행위자 아이디 속성명"},"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":"추가 속성 필드명"},"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":"언어 코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"언어 코드","enum":["ko","en","ja"]}}}}]}}}}}}
```


# 위시리스트 (Wishlist)

위시리스트 관련 사용자 행동 수집 API

## 사용자 행동수집 - 위시리스트 등록

> 위시리스트 등록 수집 API

```json
{"openapi":"3.1.0","info":{"title":"젠서 이벤트 수집 API (기본)","version":"1.0.0"},"tags":[{"name":"위시리스트 (Wishlist)","description":"위시리스트 관련 사용자 행동 수집 API"}],"servers":[{"url":"https://statistics.genser.app","description":"Production"},{"url":"http://localhost","description":"Local Development (포트 80)"},{"url":"http://localhost:8080","description":"Local Development (포트 8080)"}],"paths":{"/actions/wishlist/add":{"post":{"summary":"사용자 행동수집 - 위시리스트 등록","description":"위시리스트 등록 수집 API","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)"},{"name":"serviceKey","in":"header","required":true,"schema":{"type":"string"},"description":"서비스키"},{"name":"requestId","in":"header","required":true,"schema":{"type":"string"},"description":"리퀘스트 아이디"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionsWishlistAddEvent"}}}},"responses":{"200":{"description":"수집 성공"},"400":{"description":"잘못된 요청"},"503":{"description":"서비스 일시 불가"}}}}},"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.genser.app/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":"행위자 아이디 속성명"},"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":"추가 속성 필드명"},"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)"}}}}}}
```

## 사용자 행동수집 - 위시리스트 제거

> 위시리스트 제거 수집 API

```json
{"openapi":"3.1.0","info":{"title":"젠서 이벤트 수집 API (기본)","version":"1.0.0"},"tags":[{"name":"위시리스트 (Wishlist)","description":"위시리스트 관련 사용자 행동 수집 API"}],"servers":[{"url":"https://statistics.genser.app","description":"Production"},{"url":"http://localhost","description":"Local Development (포트 80)"},{"url":"http://localhost:8080","description":"Local Development (포트 8080)"}],"paths":{"/actions/wishlist/remove":{"post":{"summary":"사용자 행동수집 - 위시리스트 제거","description":"위시리스트 제거 수집 API","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)"},{"name":"serviceKey","in":"header","required":true,"schema":{"type":"string"},"description":"서비스키"},{"name":"requestId","in":"header","required":true,"schema":{"type":"string"},"description":"리퀘스트 아이디"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionsWishlistRemoveEvent"}}}},"responses":{"200":{"description":"수집 성공"},"400":{"description":"잘못된 요청"},"503":{"description":"서비스 일시 불가"}}}}},"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.genser.app/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":"행위자 아이디 속성명"},"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":"추가 속성 필드명"},"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)"}}}}}}
```


# 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.genser.app/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":"행위자 아이디 속성명"},"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":"추가 속성 필드명"},"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.genser.app/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":"행위자 아이디 속성명"},"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":"추가 속성 필드명"},"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":"사용자가 상품을 클릭한 행동을 수집하는 API","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.genser.app/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":"행위자 아이디 속성명"},"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":"추가 속성 필드명"},"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":{"type":"object","required":["itemListElement"],"properties":{"@type":{"type":"string","enum":["ItemList"]},"itemListElement":{"$ref":"#/components/schemas/ActionsClickProductListItem"}}},"ActionsClickProductListItem":{"type":"object","required":["position","item"],"properties":{"@type":{"type":"string","enum":["ListItem"]},"item":{"$ref":"#/components/schemas/ActionsClickProductProduct"},"position":{"type":"number"}}},"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":"언어 코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"언어 코드","enum":["ko","en","ja"]}}}}]}}}}}}
```

## The ActionsClickProductItemList object

```json
{"openapi":"3.1.0","info":{"title":"젠서 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsClickProductItemList":{"type":"object","required":["itemListElement"],"properties":{"@type":{"type":"string","enum":["ItemList"]},"itemListElement":{"$ref":"#/components/schemas/ActionsClickProductListItem"}}},"ActionsClickProductListItem":{"type":"object","required":["position","item"],"properties":{"@type":{"type":"string","enum":["ListItem"]},"item":{"$ref":"#/components/schemas/ActionsClickProductProduct"},"position":{"type":"number"}}},"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":"언어 코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"언어 코드","enum":["ko","en","ja"]}}}}]}}}}}}
```

## The ActionsClickProductListItem object

```json
{"openapi":"3.1.0","info":{"title":"젠서 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsClickProductListItem":{"type":"object","required":["position","item"],"properties":{"@type":{"type":"string","enum":["ListItem"]},"item":{"$ref":"#/components/schemas/ActionsClickProductProduct"},"position":{"type":"number"}}},"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":"언어 코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"언어 코드","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":"언어 코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"언어 코드","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.genser.app/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":"행위자 아이디 속성명"},"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":"추가 속성 필드명"},"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.genser.app/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":"행위자 아이디 속성명"},"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":"추가 속성 필드명"},"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.genser.app/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":"행위자 아이디 속성명"},"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":"추가 속성 필드명"},"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":"사용자에게 검색결과가 노출된 행동을 수집하는 API","type":"object","required":["time","source","data"],"properties":{"specversion":{"type":"string","description":"스펙 버전","enum":["1.0.0"]},"id":{"type":"string","description":"이벤트 고유 식별자","enum":["EVT-SEARCH-RESULT"]},"type":{"type":"string","description":"이벤트 유형","enum":["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.genser.app/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":"행위자 아이디 속성명"},"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":"추가 속성 필드명"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"추가 속성 필드 값"}}},"type":"array","description":"행위자 추가 속성 (회원등급, 연령 등)"}}},"object":{"oneOf":[{"$ref":"#/components/schemas/ActionsSearchResultItemList"},{"type":"array","items":{"$ref":"#/components/schemas/ActionsSearchResultItemList"}}]},"target":{"type":"object","description":"검색 엔드포인트 정보","required":["urlTemplate"],"properties":{"@type":{"type":"string","enum":["EntryPoint"]},"urlTemplate":{"type":"string","description":"검색 URL"}}}}}}},"ActionsSearchResultItemList":{"type":"object","required":["numberOfItems","itemListElement"],"properties":{"@type":{"type":"string","enum":["ItemList"]},"numberOfItems":{"type":"number"},"itemListElement":{"$ref":"#/components/schemas/ActionsSearchResultListItem"}}},"ActionsSearchResultListItem":{"type":"object","required":["position","item"],"properties":{"@type":{"type":"string","enum":["ListItem"]},"item":{"$ref":"#/components/schemas/ActionsSearchResultProduct"},"position":{"type":"number"}}},"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":"언어 코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"언어 코드","enum":["ko","en","ja"]}}}}]},"position":{"type":"number","description":"검색결과 내 순위"}}}}}}
```

## The ActionsSearchResultItemList object

```json
{"openapi":"3.1.0","info":{"title":"젠서 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsSearchResultItemList":{"type":"object","required":["numberOfItems","itemListElement"],"properties":{"@type":{"type":"string","enum":["ItemList"]},"numberOfItems":{"type":"number"},"itemListElement":{"$ref":"#/components/schemas/ActionsSearchResultListItem"}}},"ActionsSearchResultListItem":{"type":"object","required":["position","item"],"properties":{"@type":{"type":"string","enum":["ListItem"]},"item":{"$ref":"#/components/schemas/ActionsSearchResultProduct"},"position":{"type":"number"}}},"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":"언어 코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"언어 코드","enum":["ko","en","ja"]}}}}]},"position":{"type":"number","description":"검색결과 내 순위"}}}}}}
```

## The ActionsSearchResultListItem object

```json
{"openapi":"3.1.0","info":{"title":"젠서 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsSearchResultListItem":{"type":"object","required":["position","item"],"properties":{"@type":{"type":"string","enum":["ListItem"]},"item":{"$ref":"#/components/schemas/ActionsSearchResultProduct"},"position":{"type":"number"}}},"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":"언어 코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"언어 코드","enum":["ko","en","ja"]}}}}]},"position":{"type":"number","description":"검색결과 내 순위"}}}}}}
```

## 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":"언어 코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"언어 코드","enum":["ko","en","ja"]}}}}]},"position":{"type":"number","description":"검색결과 내 순위"}}}}}}
```

## The ActionsSearchSubmittedEvent object

```json
{"openapi":"3.1.0","info":{"title":"젠서 이벤트 수집 API (기본)","version":"1.0.0"},"components":{"schemas":{"ActionsSearchSubmittedEvent":{"title":"사용자 행동수집 - 검색 제출","description":"사용자가 검색어를 제출한 행동을 수집하는 API","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.genser.app/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":"행위자 아이디 속성명"},"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":"추가 속성 필드명"},"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":"검색 필터 속성명"},"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.genser.app/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":"행위자 아이디 속성명"},"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":"추가 속성 필드명"},"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":"언어 코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"언어 코드","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":"언어 코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"언어 코드","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.genser.app/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":"행위자 아이디 속성명"},"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":"추가 속성 필드명"},"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.genser.app/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":"행위자 아이디 속성명"},"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":"추가 속성 필드명"},"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)"}}}}}}
```


# AI 코멘트

<figure><img src="/files/GjzUn3Ne6vTOthC5eGM7" alt=""><figcaption></figcaption></figure>

#### AI 코멘트 (의도 데이터 콘텐츠)

상품 상세 화면에 노출될 '의도 데이터 기반 AI 코멘트'를 미리 확인할 수 있습니다. 단순한 상품 스펙 나열이 아닌, 검색어 이면에 숨겨진 고객의 진짜 의도(Intent)를 분석하여 구매 결정에 확신을 주는 메시지입니다.

**주요 확인 내용**

* **구매 의도 요약 (Reasoning):** "이 상품, 남들은 왜 샀을까?" 수많은 검색어 데이터를 분석하여 고객들이 이 상품을 선택한 핵심 이유(소재, 핏, 가성비 등)를 문장으로 보여줍니다.
* **지금 뜨는 트렌드 (Trending):** '졸업식', '크리스마스' 등 현재 시즌이나 이슈에 맞춰 급상승하는 검색 관심사를 포착해 알려줍니다.
* **구매자 팩트 체크 (Fact Check):** "겨울에도 따뜻할까요?"와 같은 잠재 고객의 불안 요소를 AI가 감지하고, 실제 리뷰와 데이터에 기반한 명쾌한 답변을 제공합니다.

{% hint style="info" %}
**참고 (운영 안내)**

AI 코멘트는 별도의 어드민 설정 없이 API 연동만으로 자동 구현되는 프리미엄 확장 기능입니다. genser 엔진이 실시간으로 데이터를 분석하여 콘텐츠를 생성하며, 사용을 원하실 경우 [genser 담당자에게 문의](https://genser.ai/)하여 기능을 활성화할 수 있습니다.
{% endhint %}


# 대시보드

<figure><img src="/files/twEp6WxNNrGy8TffNI1G" alt=""><figcaption></figcaption></figure>

### 대시보드란?

대시보드는 검색 성과와 운영 현황을 한눈에 확인할 수 있는 페이지입니다. 오늘/주간/월간 단위로 검색량, 노출수, 클릭 전환율 등의 핵심 지표를 빠르게 파악할 수 있습니다.

{% hint style="success" %}
데이터는 한 시간 단위로 확인하실 수 있습니다
{% endhint %}

<figure><img src="/files/zg0GeyrWulO8k19rOonn" alt=""><figcaption></figcaption></figure>

### 사이트 현황

<figure><img src="/files/kNAUXZqaJXcO6MWcHQI6" alt=""><figcaption></figcaption></figure>

* **검색 수**\
  사용자가 입력한 모든 검색 요청의 총합입니다.
* **노출 수**\
  검색 결과가 실제로 사용자에게 표시된 횟수입니다.
* **클릭 전환율**\
  검색 후 결과를 클릭한 비율을 나타냅니다.\
  → 검색 품질과 고객 경험 개선 여부를 가늠하는 핵심 지표입니다.

### 검색 데이터 추이

<figure><img src="/files/TzuTxKxx3JRHkrxNOcuO" alt=""><figcaption></figcaption></figure>

시간대별 검색수 현황을 그래프로 보여줍니다.

👉 언제 검색이 활발하게 일어나는지 확인하고, 운영/마케팅 전략에 반영할 수 있습니다.

### 크레딧 사용량

<figure><img src="/files/iDcVVPyyi2vZNTvc3SmY" alt=""><figcaption></figcaption></figure>

**크레딧 사용량**\
통합된 과금 기준에 따라 소진된 총 크레딧을 보여줍니다. (검색 + 데이터 갱신 + AI 콘텐츠 생성 합산)

### 활용 팁 ✨

* 클릭 전환율이 낮다면? → 검색 품질을 개선하거나, 자동완성/패싯 옵션을 조정해보세요.


# 대시보드

<figure><img src="/files/twEp6WxNNrGy8TffNI1G" alt=""><figcaption></figcaption></figure>

### genser 대시보드란?

복잡한 데이터 분석 없이도 '서비스가 건강하게 돌아가고 있는지'를 한눈에 파악할 수 있는 페이지입니다. 불필요한 정보는 배제하고, 검색 서비스 운영에 꼭 필요한 핵심 지표만을 선별하여 구성했습니다.&#x20;

#### 주요 용도 ✨

대시보드는 다음과 같은 핵심 질문에 대한 답을 한눈에 파악할 수 있습니다.&#x20;

* 어제 검색량이 평소보다 급감하지 않았나?
* 검색 결과가 없는 검색 실패 경우가 갑자기 튀진 않았나?

{% hint style="info" %}
**출근 직후 3분, 한눈에 우리 서비스의 건강을 체크해 보세요!**
{% endhint %}

***

<figure><img src="/files/17Z6G2dQCltUVdBx7Yw0" alt=""><figcaption></figcaption></figure>

### 1. 인스턴스 선택하기

대시보드는 생성된 '인스턴스' 별로 따로 확인할 수 있습니다.&#x20;

### 2. 기간 조회하기

보고 싶은 데이터의 날짜 범위를 자유롭게 선택할 수 있습니다. 어제 하루의 성과가 궁금하거나, 지난달의 전체적인 흐름을 파악하고 싶을 때 기간을 설정하여 확인해 보세요.&#x20;

* **간편한 기간 선택**
  * 기본적으로 '최근 7일' 데이터가 먼저 표시됩니다.
  * 목적에 따라 오늘 / 어제 / 최근 7일 / 최근 28일 / 이번 달 / 지난 달 중 원하는 기간을 선택할 수 있습니다.&#x20;
* **원하는 기간 직접 선택**
  * '직접 설정'을 선택하면 우측에 직접 설정할 수 있는 달력 선택기가 나타납니다.
  * 최대 12개월까지 원하는 기간을 자유롭게 지정하여 장기적인 추이를 분석할 수 있습니다.
* **실시간 업데이트**
  * 기간을 변경하는 즉시, 아래쪽의 모든 차트와 지표가 해당 날짜 기준으로 자동으로 변경됩니다.&#x20;
  * 선택한 메뉴 우측에 정확한 날짜(예: 2025.12.01 \~ 2025.12.10)가 함께 표시되므로 혼동 없이 데이터를 확인할 수 있습니다.&#x20;

### 3. 최근 활동 내역

어드민에서 일어난 주요 활동 내역을 확인할 수 있습니다.\
활동이 일어난 일시, 활동 내용, 활동한 관리자를 확인할 수 있으며, 특정 관리자의 활동 내용을 검색할 수 있습니다.

<figure><img src="/files/IyOgpApoTZUktkS2pfdS" alt=""><figcaption></figcaption></figure>

<details>

<summary>✅ 확인 가능한 활동 내역</summary>

<table><thead><tr><th width="171.01171875">메뉴</th><th>활동 내용</th></tr></thead><tbody><tr><td>검색 인사이트</td><td>👀 검색 인사이트를 조회했습니다.</td></tr><tr><td>인스턴스 설정</td><td>🌱 인스턴스를 생성했습니다.</td></tr><tr><td></td><td>✨ 인스턴스를 수정했습니다.</td></tr><tr><td></td><td>⬇️ 업로드 파일을 다운로드 했습니다.</td></tr><tr><td>용어 사전</td><td>🌱 전문 용어를 생성했습니다.</td></tr><tr><td></td><td>✨ 전문 용어를 수정했습니다.</td></tr><tr><td></td><td>🗑️ 전문 용어를 삭제했습니다. </td></tr></tbody></table>

</details>

### 4. 비즈니스 성과 요약

**genser 검색이 우리 사이트 매출에 얼마나 기여하고 있을까요?**

genser 기능이 실제 돈이 되는 성과로 이어지고 있는지, genser 검색이 고객들이 만족할 수 있는 결과를 얼마나 보여주고 있는지 핵심 지표로 확인할 수 있습니다.&#x20;

<figure><img src="/files/Luw5H4TL2MbMIzgNu0Vw" alt=""><figcaption></figcaption></figure>

#### 주요 지표 살펴보기

* **총 매출 기여액 (Total Revenue Contribution)**
  * 고객이 검색 기능을 이용한 후 실제로 주문까지 완료한 총금액입니다. 매출의 성격에 따라 두 가지로 나누어 집계합니다.&#x20;
  * **직접 기여 (Direct):** 검색 결과에서 상품을 클릭하여 즉시 구매한 경우입니다.
  * **간접 기여 (Indirect):** 검색 후 상품을 장바구니에 담아두었다가, **30일 이내**에 구매를 완료한 경우까지 포함하여 성과를 측정합니다.&#x20;
* **총 구매 전환율 (Total CVR)**
  * 고객이 시도한 검색 요청 중, 실제 구매로 이어진 비율(%)입니다. 이 수치가 높을수록 검색 결과가 고객의 의도를 잘 파악하여 구매를 성공적으로 유도했다는 뜻입니다.
  * 매출 기여액과 마찬가지로 '직접 전환율(Direct CVR)'과 '간접 전환율(Indirect CVR)'을 합산하여 계산합니다.&#x20;
* **장바구니 전환율 (Add to Cart Rate, ACR)**
  * 검색 결과에 노출된 상품이 장바구니에 얼마나 담겼는지 비율로 나타냅니다. 실제 구매 전 단계에서 고객의 관심도를 확인할 수 있는 지표입니다.&#x20;
* **클릭률 (Click Through Rate, CTR)**
  * 검색 결과에 노출된 상품을 고객이 얼마나 클릭했는지 보여줍니다. 상품의 이미지가 매력적인지, 검색 의도에 맞는 결과가 잘 나왔는지 판단할 때 유용합니다.&#x20;
  * **집계 기준**
    * **중복 클릭 제외:** 한 고객이 동일한 상품을 여러 번 클릭해도 **'1회(Unique Click)'**&#xB85C;만 계산하여 데이터 거품을 방지합니다.&#x20;
    * **다중 클릭 인정:** 한 번의 검색 결과에서 **서로 다른 여러 상품(A,B,C)을 클릭하는 것**은 검색 품질이 좋아 고객의 관심을 여러 번 끌었다는 긍정적 신호이므로, **클릭 수에 모두 포함**됩니다.&#x20;
    * **페이지/스크롤 반영:** 페이지를 넘기거나 스크롤을 내려서 추가로 노출된 상품 수(분모)와 그에 따른 클릭 수(분자)를 모두 합산하여 정확한 비율을 계산합니다.
* **상세 조회율 (Product View Rate, PVR)**
  * 상품을 클릭한 후, 상세 페이지가 오류 없이 정상적으로 열려 고객이 내용을 확인한 비율입니다.

#### 성과 그래프 활용하기

숫자만으로는 알 수 없는 데이터의 흐름을 시각적인 그래프로 확인해보세요.

* **매출 기여액과 전환율 (복합 차트)**
  * 막대 그래프: 매출이 어디서 나왔는지(직접 기여, 간접 기여) 상세 금액을 보여줍니다.
  * 선 그래프: 전체적인 매출 기여 총액과 전환율의 흐름을 한눈에 파악할 수 있습니다. (직접 기여+간접 기여)
* **장바구니 전환율, 클릭률, 상세 조회율 (선 그래프)**
  * 조회하신 시간 혹은 날짜에 맞게 지표의 흐름을 한눈에 파악할 수 있습니다.&#x20;

### 5. 서비스 이용 현황

**고객들이 검색 기능을 얼마나 활발하게 쓰고 있나요?**

genser가 얼마나 바쁘게 움직이고 있는지, 사용량은 적절한지 확인할 수 있는 현황판입니다.&#x20;

<figure><img src="/files/79Th63mNin9zA2NvqlSe" alt=""><figcaption></figcaption></figure>

#### 주요 지표 살펴보기

* **크레딧 사용량**
  * 검색 사용에 따른 비용(크레딧) 소모 현황입니다. 사용량이 갑자기 늘었다면 마케팅 이벤트 등의 영향이 있었는지 확인해보세요.&#x20;
* **검색 수**
  * 사용자들이 검색창에 의도를 입력하고 검색한 총 횟수입니다. 우리 사이트 고객의 검색 활동량을 알 수 있습니다.&#x20;
* **노출 수**
  * 검색 결과 페이지에 상품이 고객에게 실제로 보여진 횟수입니다.&#x20;

#### 이용 현황 추세 확인하기

* **검색 수와 노출 수:** 선 그래프로 제공되어, 주말이나 특정 요일에 검색량이 늘어나거나 줄어드는 패턴을 쉽게 발견할 수 있습니다.&#x20;
* **크레딧:** 막대그래프로 표시되어 사용량 흐름을 직관적으로 비교할 수 있습니다.&#x20;


# 검색 인사이트

<figure><img src="/files/A5kXZHj26EGey8j3vH6v" alt=""><figcaption></figcaption></figure>

### 검색 인사이트란?

단순히 숫자를 보는 것을 넘어, 고객이 '구체적으로 무엇을 찾고 있는지' 파악하는 공간입니다. 검색 의도, 카테고리, 브랜드, 상품 단위로 데이터를 쪼개보고 비교하여 상품 소싱과 마케팅 전략의 힌트를 얻을 수 있습니다.&#x20;

#### 주요 용도 ✨

검색 인사이트는 다음과 같은 핵심 질문에 대한 답을 한눈에 파악할 수 있습니다.&#x20;

* 요즘 우리 고객들이 무엇을 가장 많이 검색하지? 트렌드가 바뀌었나?&#x20;
* 검색 속도가 느려지진 않았나? 최신 상품이 제대로 연동되고 있나?
* 실제로 검색했을 때 결과가 어떻게 나왔지? 제대로 나왔나?&#x20;

{% hint style="info" %}
**알기 어려운 고객의 마음속, 진짜 '검색 의도'를 확인해 보세요.**
{% endhint %}

***

<figure><img src="/files/sdXvKJigIFAxTboSAcjb" alt=""><figcaption></figcaption></figure>

### 1. 인스턴스 선택하기

검색 인사이트는 생성된 '인스턴스' 별로 따로 확인할 수 있습니다.&#x20;

### 2. 기간 조회하기

보고 싶은 데이터의 날짜 범위를 자유롭게 선택할 수 있습니다. 어제 하루의 성과가 궁금하거나, 지난달의 전체적인 흐름을 파악하고 싶을 때 기간을 설정하여 확인해 보세요.&#x20;

* **간편한 기간 선택**
  * 기본적으로 '최근 7일' 데이터가 먼저 표시됩니다.
  * 목적에 따라 오늘 / 어제 / 최근 7일 / 최근 28일 / 이번 달 / 지난 달 중 원하는 기간을 선택할 수 있습니다.&#x20;
* **원하는 기간 직접 선택**
  * '직접 설정'을 선택하면 우측에 직접 설정할 수 있는 달력 선택기가 나타납니다.
  * 최대 12개월까지 원하는 기간을 자유롭게 지정하여 장기적인 추이를 분석할 수 있습니다.
* **실시간 업데이트**
  * 기간을 변경하는 즉시, 아래쪽의 지표가 해당 날짜 기준으로 자동으로 변경됩니다.&#x20;
  * 선택한 메뉴 우측에 정확한 날짜(예: 2025.12.01 \~ 2025.12.10)가 함께 표시되므로 혼동 없이 데이터를 확인할 수 있습니다.&#x20;
  * 검색 분석 탭의 '최근 7일 트렌드 분석' 영역은 상단의 기간 설정과 무관하게 오늘 날짜 기준 최근 7일 간의 데이터를 반영합니다.&#x20;

### 3. 검색 분석

고객의 검색 행동을 데이터로 시각화하여 비즈니스 인사이트를 제공합니다.&#x20;

<figure><img src="/files/gNr4Vxp7CNCPi7DQKj8p" alt=""><figcaption></figcaption></figure>

#### 성과 오버뷰

* **검색 수**
  * 사용자들이 검색창에 의도를 입력하고 검색한 총 횟수입니다. 우리 사이트 고객의 검색 활동량을 알 수 있습니다.
* **클릭률 (Click Through Rate, CTR)**
  * 검색 결과에 노출된 상품을 고객이 얼마나 클릭했는지 보여줍니다. 상품의 이미지가 매력적인지, 검색 의도에 맞는 결과가 잘 나왔는지 판단할 때 유용합니다.&#x20;
  * **집계 기준**
    * **중복 클릭 제외:** 한 고객이 동일한 상품을 여러 번 클릭해도 **'1회(Unique Click)'**&#xB85C;만 계산하여 데이터 거품을 방지합니다.&#x20;
    * **다중 클릭 인정:** 한 번의 검색 결과에서 **서로 다른 여러 상품(A,B,C)을 클릭하는 것**은 검색 품질이 좋아 고객의 관심을 여러 번 끌었다는 긍정적 신호이므로, **클릭 수에 모두 포함**됩니다.&#x20;
    * **페이지/스크롤 반영:** 페이지를 넘기거나 스크롤을 내려서 추가로 노출된 상품 수(분모)와 그에 따른 클릭 수(분자)를 모두 합산하여 정확한 비율을 계산합니다.
* **상세 조회율 (Product View Rate, PVR)**
  * 상품을 클릭한 후, 상세 페이지가 오류 없이 정상적으로 열려 고객이 내용을 확인한 비율입니다.
* **장바구니 전환율 (Add to Cart Rate, ACR)**
  * 검색 결과에 노출된 상품이 장바구니에 얼마나 담겼는지 비율로 나타냅니다. 실제 구매 전 단계에서 고객의 관심도를 확인할 수 있는 지표입니다.&#x20;
* **구매 전환율 (Total CVR)**
  * 고객이 시도한 검색 요청 중, 실제 구매로 이어진 비율(%)입니다. 이 수치가 높을수록 검색 결과가 고객의 의도를 잘 파악하여 구매를 성공적으로 유도했다는 뜻입니다.
  * '직접 전환율(Direct CVR)'과 '간접 전환율(Indirect CVR)'을 합산하여 계산합니다.
* **진단 및 관심 지표**
  * **검색 결과 없음 비율 (Zero Results Rate)**
    * 전체 검색 횟수 중 검색 결과가 '0건'으로 반환된 검색의 비율을 의미합니다. 놓치고 있는 상품 수요를 파악할 수 있습니다.
    * 검색 결과가 없는 비율이 높으면 고객이 사이트를 이탈할 확률이 비약적으로 상승합니다. 상품은 있지만 고객이 '오타'를 냈거나, '다른 용어(유의어)'로 검색했을 가능성이 있습니다.&#x20;
* **찜하기 전환율 (Wishlist Rate)**
  * 검색된 상품이 '찜(위시리스트)'에 담긴 비율입니다. 당장 구매하진 않았지만, 쿠폰이나 세일 트리거가 있다면 구매할 '잠재 고객'이 얼마나 되는지 보여줍니다.

{% hint style="info" %}
**검색 결과 없음 비율 Tip**

이 수치가 갑자기 크게 오른다면, 최근 유행하는 신조어나 경쟁사의 상품명이 우리 사이트에서 검색되고 있는지 확인해 보세요!&#x20;
{% endhint %}

{% hint style="info" %}
**구매 전환율 Tip**

클릭률(CTR)과 찜하기 전환율은 높은데 구매 전환율(CVR)이 낮다면, 상품의 매력도는 충분하나 가격 경쟁력이나 리뷰 부족이 원인일 수 있습니다. 점검해 보세요!&#x20;
{% endhint %}

#### 최근 7일 트렌드 분석

**지난 일주일, 고객의 관심사는 어떻게 움직였을까요?**

주요 검색 의도와 상품의 최근 7일간의 인기 흐름을 꺾은선 그래프로 시각화하여, 상승세인지 하락세인지 패턴을 한눈에 파악할 수 있습니다.&#x20;

* **그래프 보는 법**
  * **기간 기준:** 오늘을 제외한 **최근 7일 간의 데이터**가 자동으로 표시됩니다. (상단에서 설정한 조회 기간과 무관하게, 트렌드 분석은 항상 최근 일주일 흐름을 보여줍니다.)
  * **기기별 데이터:** 페이지 상단에서 선택한 **디바이스(전체/PC/모바일)** 설정에 따라 데이터도 함께 변경됩니다.
  * **기본 설정:** 처음 메뉴에 들어오면, 가장 인기 있는 **상위 5개**의 검색 의도가 자동으로 그래프에 그려집니다.&#x20;
* **내 맘대로 비교하기**
  * 궁금한 키워드나 브랜드를 직접 검색하고 선택해서 그래프에 띄워볼 수 있습니다. 경쟁 상품끼리 비교하거나, 연관된 카테고리끼리 비교할 수 있습니다.
  * 하단 테이블의 탭 별로 비교할 수 있습니다.&#x20;
  * **최대 5개 선택이 가능합니다.**
    * 하단 테이블의 체크박스를 클릭하면 그래프 하단의 '비교 항목'으로 추가되어 그래프에서 추이를 비교할 수 있습니다.&#x20;
  * **편리하게 비교 항목을 추가하고 제외할 수 있습니다.**
    * 비교 항목 영역에서 칩의 'X' 버튼을 클릭하여 개별적으로 제외하거나 '전체 선택 해제' 버튼을 클릭하여 비교 항목 영역을 한 번에 비울 수 있습니다.&#x20;
* **4가지 분석 관점**
  * **검색 의도:** 고객이 실제로 입력한 검색 의도의 인기 흐름을 볼 수 있습니다.&#x20;
  * **카테고리:** 카페고리 단위로 묶어서 인기의 흐름을 볼 수 있습니다.&#x20;
  * **브랜드:** 어떤 브랜드가 검색 점유율이 높은지 확인할 수 있습니다.&#x20;
  * **상품:** 특정 상품의 검색 추이를 정밀하게 추적할 수 있습니다.&#x20;

{% hint style="info" %}
**검색 의도란?**

고객이 문장으로 검색할 경우, genser의 AI가 이를 분석하여 최대 5개의 핵심 의도로 추출해 집계합니다.&#x20;
\\

\
**문장형 검색 의도의 통계 집계 기준**&#x20;

단순한 단어의 나열이 아닙니다. AI가 조사나 불필요한 표현을 걸러내고, **고객의 검색 의도(Intent)가 담긴 '의미 단위'**&#xB9CC;을 남긴 것입니다.
\\

\
**추출 예시**

"30대 남자가 입기 좋은 따뜻한 겨울 코트"로 검색할 경우 키워드는 '30대 남자', '따뜻한 코트', '겨울 코트' 등 입니다.
{% endhint %}

### 4. 운영 현황

**우리 검색 인스턴스, 건강하게 숨 쉬고 있을까요?**&#x20;

검색 결과가 아무리 좋아도 속도가 느리거나 최신 상품이 안 나온다면 큰 문제입니다. 운영 현황 탭에서는 검색 인스턴스의 '기술적인 건강 상태'를 실시간으로 점검할 수 있습니다.&#x20;

<figure><img src="/files/vB7lPoJuRSCNamH6Tu5Q" alt=""><figcaption></figcaption></figure>

#### 운영 현황 지표

* **사용 크레딧**
  * 설정한 기간 동안 사용된 크레딧의 총량입니다. 비용 관리 차원에서 급격하게 늘어나지 않는지 체크해 보세요.
* **검색 속도(평균)**
  * 고객이 검색 버튼을 누른 후 결과가 화면에 뜰 때까지 걸리는 평균 시간입니다.&#x20;
  * 단위는 ms(밀리초)이며, 숫자가 작을수록 속도가 빠르다는 뜻입니다. (예: 342ms = 0.34초)
* **데이터 연동**
  * 쇼핑몰에 새로 등록한 상품이 검색 인스턴스에 잘 반영되고 있는지 보여줍니다.
  * **정상 vs 비정상:** 최신 상품 정보의 연동 실패율이 5% 이상이면 '비정상' 경고가 뜹니다. 이때는 개발팀이나 시스템 관리자에게 문의해 주세요.
  * **최근 업데이트:** 우측 하단에서 마지막으로 데이터가 동기화된 정확한 시간을 확인할 수 있습니다.

#### 추세 그래프

* 숫자만으로는 알 수 없는 데이터의 흐름을 시각적인 그래프로 확인해보세요.
* 조회하신 시간 혹은 날짜에 맞게 지표의 흐름을 한눈에 파악할 수 있습니다.&#x20;

### 5. 검색 로그

**모든 검색 기록을 초 단위로 추적합니다.**

누가, 언제, 어떤 검색을 했는지 낱낱이 기록된 '검색 내역서'입니다. 특정 고객의 불만 접수(CS)를 처리하거나, 검색 결과가 의도대로 나오고 있는지 검증할 때 가장 강력한 도구입니다.&#x20;

<figure><img src="/files/BbUTpfwH0qp7IuLYpQUh" alt=""><figcaption></figcaption></figure>

#### 검색 로그 상세 내역

* **검색 일시(Date)**
  * 검색이 발생한 정확한 날짜와 시간(초 단위)입니다. 기본적으로 가장 최근 검색 기록이 맨 위에 오도록 정렬됩니다.&#x20;
* **회원 ID**
  * 로그인한 고객의 경우, 해당 고객의 ID가 표시됩니다.
  * 로그인 하지 않은 방문자는 '비로그인'으로 표시됩니다.
* **쿠키 ID**
  * 사용자의 쿠키 ID가 표시됩니다.
* **검색 질문(Query)**
  * 고객이 검색창에 실제로 입력한 질문입니다. 오타가 있거나 띄어쓰기가 틀린 내용도 그대로 기록되므로 고객의 '생생한 언어'를 확인할 수 있습니다.&#x20;

#### 스마트 검색 및 필터

* **검색 조건 선택:** 검색창 왼쪽의 드롭다운 메뉴를 눌러 '회원 ID', '쿠키 ID', '검색 질문' 중 찾고 싶은 기준을 선택해서 검색할 수 있습니다.&#x20;
* **전체 기간 검색:** 현재 보고 있는 페이지뿐만 아니라, 설정된 조회 기간 내의 모든 데이터를 뒤져서 결과를 찾을 수 있습니다.&#x20;

#### 실전 활용 가이드 🌱

* **CS 문의 해결:** "어제 2시쯤에 '소파'를 검색했는데 결과가 이상해요"라는 문의가 왔다면?
  * 검색창에서 \[회원 ID]를 선택하고 고객 ID를 입력해 보세요. 해당 고객의 검색 기록만 모아서 문제를 파악할 수 있습니다.
* **비로그인 고객 검색 패턴 분석**
  * 검색창에 '비로그인'이라고 검색하면, 로그인하지 않은 방문자들의 검색 패턴만 따로 모아볼 수 있습니다.


# 검색 결과 미리보기

<figure><img src="/files/ra3HhiELAoBOrYOv450F" alt=""><figcaption></figcaption></figure>

## 검색 결과 미리보기란? <a href="#d01" id="d01"></a>

* ‘검색 결과 미리보기’는 검색 인스턴스를 선택해서 실제 검색 결과가 어떻게 나오는지 미리 볼 수 있는 페이지입니다.
* 이 페이지에서는 검색어를 입력하면, 설정해둔 검색 조건에 따라 어떤 상품들이 보이는지 확인할 수 있습니다. 예를 들어 "코트"를 검색하면 코트 관련 상품들이 어떤 순서로, 어떤 설명과 함께 보여지는지 직접 확인해볼 수 있습니다.

<figure><img src="/files/kH8Njkp2rEdfZoil3g4o" alt=""><figcaption></figcaption></figure>

### 화면 구성과 사용 방법 <a href="#d02" id="d02"></a>

<figure><img src="/files/BMFq73Kx12fCdZ76y95z" alt=""><figcaption></figcaption></figure>

#### 1. 인스턴스 선택하기

* 먼저 어떤 검색 인스턴스로 테스트할지 골라야합니다.
* ‘인스턴스 선택하기’ 버튼 클릭 시 오른쪽 영역에서 인스턴스 리스트 노출
* 원하는 인스턴스를 클릭
* 선택된 인스턴스 이름을 클릭

<figure><img src="/files/DIM8PZ1CeKdQcACV8lDE" alt=""><figcaption></figcaption></figure>

#### 2. 검색어 입력하기

* 인스턴스를 선택하면 검색어를 입력하여 검색 결과를 미리 확인해볼 수 있습니다.
* 예: “봄 원피스”, “캐시미어 코트”
* 입력 후 **검색 버튼**을 누르거나 Enter 키를 누르면 결과를 확인할 수 있습니다.
* 한 개의인스턴스를 비교하여 확인하거나, 두 개의 인스턴스를 선택해 비교 검색도 할 수 있습니다.

#### 3. 검색 결과 확인창

<figure><img src="/files/4Fwy6oDCr8yC0yZmUooU" alt=""><figcaption></figcaption></figure>

1. 설정: 선택한 인스턴스의 설정 사항을 확인할 수 있고, 검색 설정을 조정해볼 수 있습니다.
2. 창 제어: 창을 키우거나 나눠서 여러 인스턴스 결과를 비교할 수 있습니다. (모바일에선 항상 분할 보기)
3. 닫기: 해당 미리보기 결과 영역의 창을 닫을 수 있습니다

### 검색 결과 화면에서 볼 수 있는 사항 <a href="#d03" id="d03"></a>

<figure><img src="/files/B35bDN3dOz1k3c7wjFEF" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="55.951416015625">No.</th><th width="173.392822265625">항목</th><th>설명</th></tr></thead><tbody><tr><td>1</td><td><strong>검색 결과 설명</strong></td><td>하단의 상품 검색 결과에 대한 AI 설명입니다. </td></tr><tr><td>2</td><td><strong>연관 키워드</strong></td><td>상품 결과의 메타 데이터에서 추출한 연관 키워드입니다. </td></tr><tr><td>3</td><td><strong>제안 질문</strong></td><td>사용자의 검색 의도를 파악하여 다음 질문을 제안합니다. </td></tr><tr><td>4</td><td><strong>AI 코멘트</strong></td><td>검색 결과에 대한 AI 분석 리포트를 미리 볼 수 있습니다. </td></tr><tr><td>5</td><td><strong>상품 검색 결과</strong></td><td>입력한 검색어에 맞는 상품들이 보여집니다.</td></tr></tbody></table>

***

미리보기 화면 우측의 설정 패널에서 검색 로직과 화면 구성을 통합하여 조정할 수 있습니다.

<figure><img src="/files/DdEfdFeC7eqnNLTs9C3b" alt=""><figcaption></figcaption></figure>

* 모든 확인 버튼 클릭 시 적용되어 검색 결과 미리보기 화면에 반영됩니다.
* 설정을 변경한 후, 동일한 검색어로 다시 검색해보면 차이를 바로 확인할 수 있습니다.
* 변경 사항은 실제 인스턴스에 저장되지 않으며 참고용으로 확인해볼 수 있습니다.

### 참고 <a href="#d05" id="d05"></a>

* 인스턴스를 선택하지 않으면 검색이 되지 않습니다.
* 항상 ‘아이템명’은 검색 결과에 필수 항목으로 표기됩니다.
* 항목이 비어있으면 데이터 없음 또는 공란으로 표시됩니다.
* 변경 사항은 실제 인스턴스에 저장되지 않으며 참고용으로 확인해볼 수 있습니다.
* 설정을 변경한 후, 동일한 검색어로 다시 검색해보면 차이를 바로 확인할 수 있습니다.

**검색 결과가 없을 때**

* “상품이 없습니다. 다른 검색어를 입력해 주세요.” 라는 안내를 확인할 수 있습니다.
* 대신 **연관 키워드**를 추천해 확인할 수 있습니다.\
  예: “봄옷” 검색 시 → “봄 자켓”, “봄 원피스” 등


# 데이터 연동 현황

<figure><img src="/files/OkdVJ2kFCt3yuS13egSE" alt=""><figcaption></figcaption></figure>

## 데이터 연동 현황

Genser에서 생성한 '검색 인스턴스'별로 데이터가 연동되는 현황을 실시간으로 모니터링할 수 있습니다.

전체 아이템 수, 최근 접수된 아이템, 연동 성공 및 품질 현황 등 핵심 지표를 한눈에 파악하여 데이터 파이프라인의 상태를 신속하게 점검할 수 있습니다.

<figure><img src="/files/dcEGZy1UUevcvdJUVllb" alt=""><figcaption></figcaption></figure>

### 1. 연동 현황 조회하기

데이터 현황은 생성된 '인스턴스' 별로 따로 볼 수 있습니다.

1. 페이지 상단에 위치한 \[인스턴스 A] 메뉴를 클릭합니다.
2. 데이터 현황을 보고 싶은 '인스턴스'의 이름을 목록에서 선택합니다.
3. 선택한 인스턴스의 최신 데이터 현황이 화면에 바로 나타납니다.

{% hint style="info" %}
최근 업데이트 시간은 현재 화면에 보이는 데이터 현황 정보가 언제 기준으로 집계된 것인지 표시합니다.
{% endhint %}

### 2. 연동 현황 대시보드 이해하기

연동 현황 대시보드는 4가지 중요한 연동 현황 데이터를 나타냅니다.

<figure><img src="/files/q8myj2g8totIFxmej7en" alt=""><figcaption></figcaption></figure>

a. 전체 아이템 수: 해당 인스턴스에서 검색 가능한 모든 아이템의 총 개수입니다.

b. 최근 접수 된 아이템 수: 최근에 연동을 위해 접수된 아이템 개수입니다. 전날 등록한 신규 아이템들을 새벽 1시에 한번에 접수합니다.

c. 연동 성공 아이템 수: 접수된 아이템 중에 성공적으로 연동에 성공한 아이템 개수입니다.

d. 품절 아이템 수: 품절되어 검색이 되지 않는 아이템 개수입니다.


# 검색 인스턴스

<figure><img src="/files/lyJM2JKk39omixU8zsxX" alt=""><figcaption></figcaption></figure>

## 사용자가 검색한 내역을 확인해 보세요.

{% content-ref url="/pages/nR5Cl7S8UTSKYPGM1WUq" %}
[분석 리포트](/ai-search/genser-instance/analytics-old)
{% endcontent-ref %}


# 인스턴스 목록

<figure><img src="/files/WAkVvfnMjkQd6LLZQhKH" alt=""><figcaption></figcaption></figure>

## 어떤 것을 확인할 수 있나요?

인스턴스 목록 화면은 인스턴스를 만들거나, 지금까지 만든 검색 인스턴스들을 한눈에 볼 수 있는 공간입니다.\
이 화면에서는 내가 만든 검색 인스턴스의 이름, 유형, 작성일, 수정일, 상태 등을 확인할 수 있고, 필요하다면 복사하거나 수정할 수도 있어요.

### 목록에서 볼 수 있는 정보

<table><thead><tr><th width="145.0286865234375">항목</th><th>설명</th></tr></thead><tbody><tr><td>인스턴스명</td><td>내가 만든 검색 인스턴스의 이름이에요. 클릭하면 상세 수정 화면으로 이동해요.</td></tr><tr><td>검색 유형</td><td>어떤 검색 방식(genser S/G)으로 만든 인스턴스인지 보여줘요.</td></tr><tr><td>작성일</td><td>인스턴스를 처음 만든 날짜입니다.</td></tr><tr><td>최종 수정일</td><td>마지막으로 수정한 날짜로 가장 최신 것이 위에 노출됩니다.</td></tr><tr><td>처리 현황</td><td><p>현재 인스턴스 진행 상태를 알 수 있습니다.</p><p>- 대기: 아직 준비 중이에요<br>- 진행 중: 설정이 반영되고 있어요<br>- 완료: 검색 인스턴스를 바로 사용할 수 있어요</p></td></tr></tbody></table>


# 인스턴스 만들기

{% columns %}
{% column %}

<figure><img src="/files/MEHnYWuVlZV8sMsOReiI" alt=""><figcaption></figcaption></figure>

{% endcolumn %}

{% column %}

<figure><img src="/files/2VGKX9XDYCZvsybm4HHS" alt=""><figcaption></figcaption></figure>

{% endcolumn %}
{% endcolumns %}

## 인스턴스 만들기 및 관리

genser를 시작하기 위해 검색 설정을 담은 '인스턴스'를 생성합니다. 하나의 인스턴스가 키워드 검색과 자연어 검색을 모두 통합 관리합니다.

1. **인스턴스 생성:** \[새 인스턴스 만들기] 버튼을 클릭합니다. (유형 선택 단계 없음)
2. **기본 설정:** 인스턴스 명을 입력하고 기본 검색 옵션을 설정합니다.
3. **통합 설정:** 키워드 검색 설정과 AI 답변 톤앤매너 설정을 한 화면에서 통합 관리합니다.
4. **인스턴스 목록:** 생성된 인스턴스는 유형 구분 없이 목록에 표시되며, 상태(준비중/완료)를 확인할 수 있습니다.

## 검색 설정

### 검색 결과 <a href="#tab01" id="tab01"></a>

<figure><img src="/files/p7kIWHMxWzIB2X6DmxUO" alt=""><figcaption></figcaption></figure>

#### 호출 데이터 단위&#x20;

데이터 호출 단위는 검색된 상품 데이터를 서버에서 나눠 가져오는 기준 수량으로, 실제 화면에 보여지는 결과 개수와는 다릅니다.

{% hint style="info" %}
**데이터 호출 단위를  50으로 설정 시**

* 검색 시 서버는 한 번의 요청마다 최대 50개의 item 데이터를 전달
* 화면에서는 이 중 일부만 노출하거나, 추가 요청으로 이어서 데이터를 표시 가능
  {% endhint %}

<figure><img src="/files/60QFnVMkCqq6PFZPGviW" alt=""><figcaption></figcaption></figure>

#### 검색 결과 설명  <a href="#srd" id="srd"></a>

사용자가 입력한 검색어에 대한 결과가 왜 나오게 되었는지 보여주는 기능입니다. 이 기능을 활성화 하면 사용자가 단순히 상품만 나열하면 “왜 이게 나왔지?”라는 의문이 생길 수 있는데, 설명이 있으면 결과의 맥락을 이해하고 신뢰할 수 있습니다.

#### 톤 앤 스타일 <a href="#ton" id="ton"></a>

고객에게 제공하는 검색 응답의 말투, 분위기, 전문성을 제어하는 설정입니다. 이를 통해 고객 경험에 맞는 자연스러운 검색 결과를 제공할 수 있습니다.

#### 연관 키워드 <a href="#synonyms" id="synonyms"></a>

고객이 입력한 검색어와 연결된 다른 검색어를 함께 보여주는 기능이에요. 검색 결과와 같이 노출되어, 고객이 더 많은 상품을 쉽게 탐색할 수 있도록 도와줍니다.

{% hint style="info" %}
검색어가 `크림`일 경우 → “피부 장벽 강화 크림”, “수분 진정 크림”, “비건 크림” 같은 연관 키워드가 함께 뜹니다.
{% endhint %}

#### 제안 질문 <a href="#totalitem" id="totalitem"></a>

사용자의 질문 맥락을 분석하여, 고객이 추가로 검색하면 좋을 만한 질문을 AI가 역으로 제안하는 기능입니다. 단순히 키워드를 나열하는 것이 아니라, 고객이 "다음에 무엇을 궁금해할지" 예측한 질문 텍스트를 제공함으로써 자연스러운 검색 경험을 돕습니다.

* 최대 제안 질문 수: AI가 생성할 질문의 '최대 개수'를 설정합니다. (최대 8개, 권장 3\~5개) 단, 무조건 설정한 개수만큼 생성되는 것은 아닙니다. AI가 자동으로 최적화하여 검색 맥락에 적합한 질문이 없다면, 설정된 개수보다 적게 생성되거나 생성되지 않을 수 있습니다.&#x20;
* 질문 유형 선택: 우리 사이트의 특성에 맞춰, AI가 어떤 전략으로 질문을 생성할지 선택할 수 있습니다. 각 유형은 아래의 우선순위에 따라 생성됩니다.&#x20;
  * 구매 의도 확인: "집들이용", "선물용", "캠핑용" 등과 같이 고객이 검색한 질문 뒤에 숨겨진 고객의 "진짜 의도"를 예측합니다. 구체적인 상황이나 핵심 키워드를 AI가 먼저 제안하여, 고객이 자연스럽게 추가적인 탐색을 이어가도록 유도합니다.&#x20;
  * 브랜드 좁히기: 검색 결과 내 주요 브랜드가 있다면 "나이키 제품으로 보여줘"와 같이 특정 브랜드로 제품 결과 필터링을 유도합니다.
  * 속성 좁히기: "10만원 이하 가격대로 보여줘", "파란색만 모아서 보여줘" 등 상품의 상세 스펙(가격, 색상, 사이즈 등)을 좁혀줍니다.&#x20;
  * 리뷰/랭킹 기반 추천: "평점 높은 등산화 보여줘", "가장 많이 팔린 캠핑용품 보여줘" 등 고객들의 선호도와 신뢰도 데이터를 기반으로 제안합니다.&#x20;

{% hint style="info" %}
**알아두세요!**

노출 로직과 우선순위 제안 질문은 시스템 백단에서 파악된 **실제 검색 결과의 풍부함**에 따라 3단계(최소형, 표준형, 확장형)로 나뉘어 다르게 작동합니다. 검색 결과가 적을 때는 가장 중요한 질문 유형부터, 결과가 많을 때는 다양한 질문 유형을 보여줍니다.
{% endhint %}

{% hint style="warning" %}
**설정 시 주의사항**

질문 유형의 우선순위가 가장 높은 **'구매 의도 확인'을 체크 해제할 경우,** 검색 결과가 적은(최소형) 상품 검색 시에는 **'제안 질문' 기능을 켜두더라도 제안 질문이 노출되지 않을 수 있습니다.**
{% endhint %}

#### 전체 검색 결과 수 <a href="#totalitem" id="totalitem"></a>

고객이 입력한 검색어로 검색했을 때, 조건에 맞는 상품(또는 item)이 총 몇 개 검색되었는지를 알려주는 숫자예요.&#x20;

### 제한 용어 <a href="#tab02" id="tab02"></a>

<figure><img src="/files/ecdefGM7jSsKHkUnBgms" alt=""><figcaption></figcaption></figure>

#### 제한 용어 <a href="#rk" id="rk"></a>

검색 시 특정 단어나 조건을 제한하여 결과에 포함되지 않도록 설정하는 기능입니다. 예를 들어, ‘중고’를 제한 용어로 등록하면 검색 결과에서 중고 상품은 자동으로 제외됩니다.

### 자동 완성 <a href="#autocomplete" id="autocomplete"></a>

<figure><img src="/files/vthNLObZHzc95CfD1Zfq" alt=""><figcaption></figcaption></figure>

#### 자동 완성 <a href="#autocomplete2" id="autocomplete2"></a>

자동완성은 사용자가 검색어를 입력하는 순간, 예상 검색어와 추천 결과를 실시간으로 보여주는 기능입니다.

#### 자동 완성 금지어 <a href="#aek" id="aek"></a>

자동 완성 금지어는 특정 단어가 자동완성 제안에 노출되지 않도록 차단하는 기능입니다.\
민감하거나 불필요한 키워드를 등록해 고객이 입력했을 때 자동 완성 제안창에 표시되지 않게 설정할 수 있습니다.

{% hint style="info" %}
예시

* **브랜드/경쟁사명 제어**\
  예: 경쟁사 브랜드명은 자동완성 추천에서 제외
* **내부 관리용 코드/상품명 제외**\
  예: 운영자만 아는 `SKU-1234` 같은 관리용 상품명이 고객에게 보이지 않도록 설정
* **재고 소진/단종 상품 제외**\
  이미 판매가 종료된 상품명이 추천으로 뜨지 않도록 관리
  {% endhint %}

### 패싯(Facet) <a href="#tab03" id="tab03"></a>

<figure><img src="/files/uYmR3boj8Ik5oyO4doSm" alt=""><figcaption></figcaption></figure>

#### 패싯(Facet)  <a href="#facet" id="facet"></a>

**패싯**은 고객이 검색한 결과를 다양한 기준(카테고리, 브랜드, 가격, 색상 등)으로 세분화해서 필터링할 수 있도록 돕는 기능입니다. 쉽게 말해, 검색 후 노출된 수많은 상품 속에서 고객이 원하는 조건에 맞춰 결과를 좁혀갈 수 있는 기능이라고 보시면 됩니다.

### 고급 설정 <a href="#tab04" id="tab04"></a>

<figure><img src="/files/5eGKvqitsOd4BrA36FNh" alt=""><figcaption></figcaption></figure>

고급 설정은 기본 검색 결과 세팅 외에, 검색 품질 조건을 적용할 수 있는 영역입니다. 운영자는 이곳에서 검색 결과 노출 방식, 순서 제어, 추천 로직 등을 직접 컨트롤할 수 있습니다.

#### 이미지 기반 후속 검색  <a href="#ifs" id="ifs"></a>

{% hint style="warning" %}
이미지 기반 후속 검색은 기본으로 제공되지 않으며, 사용을 원하실 경우 별도 문의가 필요합니다.
{% endhint %}

사용자가 선택한 상품 이미지를 기반으로 유사한 상품을 다시 검색하는 기능입니다. 텍스트로 설명하기 어려운 경우에도, 이미지 검색을 통해 직관적으로 원하는 결과를 찾을 수 있습니다.

#### 검색 결과 순서 제어  <a href="#srrank" id="srrank"></a>

검색 결과의 노출 순서를 조정할 수 있는 기능입니다. 운영자가 특정 상품 정보를 우선적으로 보여주거나, 사용자 경험에 맞춰 정렬 기준을 설정할 수 있습니다.

### 확인해 주세요! 🔍

검색어를 입력하고 결과가 표시되기 전까지는 **검색자가 검색이 되고 있는지 알기 어렵습니다.** 이때 아무런 화면이나 메시지가 없으면 서비스가 멈췄다고 오해할 수 있고, 불필요하게 새로고침을 시도하거나 검색을 포기할 수 있습니다.

따라서 <mark style="background-color:orange;">**검색 중임을 명확하게 알려주는 전용 페이지(로딩 상태 페이지)**</mark>가 필요합니다. 이 페이지에는 진행 중임을 시각적으로 보여주는 스피너, 스켈레톤 UI, 또는 “검색 결과를 준비하고 있습니다”와 같은 안내 문구를 포함해야 검색자가 검색 결과 페이지가 나올 때 까지 기다릴 수 있습니다.


# 분석 리포트

## 검색 인스턴스 분석 리포트란? <a href="#anal" id="anal"></a>

해당 인스턴스의 검색 결과 내역과 크레딧 사용량을 확인할 수 있는 페이지입니다.

<figure><img src="/files/5W9nNXkI9UQn9GF4oMAs" alt=""><figcaption></figcaption></figure>

1. 조회 기간: 6시간(default), 12시간, 기간 조회
2. 인스턴스 정보: 해당 인스턴스의 정보를 확인할 수 있습니다.
3. 모니터링 지표: 사용 크레딧과 검색 속도를 확인할 수 있습니다.
4. 분석 리포트 구분
   1. 검색 분석: 요약 지표, 인기 키워드 비율, 검색 데이터 그래프, 인기 TOP100을 확인할 수 있는 지표로 구성되어 있습니다.
   2. 검색 내역: 어떤 키워드가 검색 됐는지, 어떤 키워드가 클릭 됐는지 등의 키워드 내역과 검색 내역을 확인할 수 있는 데이터 테이블로 구성되어 있습니다.
5. 접속 디바이스 구분
   1. 분석 리포트 데이터를 디바이스 구분별로 확인할 수 있습니다.
   2. 전체: 모바일, PC 각각 수집된 데이터 모두 확인할 수 있습니다.
   3. 모바일: 모바일에서 수집된 데이터입니다. (SDK, Native 제외)
   4. PC: PC에서 수집된 데이터입니다.

## 모니터링 지표

<figure><img src="/files/41Ig0EShyM4rIOSQtwhi" alt=""><figcaption></figcaption></figure>

### 사용 크레딧 <a href="#anal-1" id="anal-1"></a>

해당 인스턴스가 사용되는 크레딧 현황을 확인할 수 있습니다.

1. 사용자가 검색한 시점 기준으로 카운팅 됩니다.
2. genser S는 1 크레딧, genser g는 5 크레딧 씩 카운팅 됩니다.

### 검색 속도(평균) <a href="#anal-2" id="anal-2"></a>

검색 속도(평균): 검색 결과의 속도를 모니터링할 수 있습니다.

## 요약 지표와 그래프 <a href="#anal-3" id="anal-3"></a>

<figure><img src="/files/dgFF8mjTNJMoHmnbKwwK" alt=""><figcaption></figcaption></figure>

### **요약 지표** <a href="#anal-3-1" id="anal-3-1"></a>

<table><thead><tr><th width="150.8740234375">항목</th><th>설명</th></tr></thead><tbody><tr><td>검색 수(전체)</td><td>사용자가 입력한 모든 검색어의 발생 횟수로, 검색 결과 유무와 관계없이 포함된 총 검색 수</td></tr><tr><td>노출 수</td><td>사용자의 검색에 대해 결과가 있고 노출된 횟수로, 결과 없음 수까지 포함한 전체 노출 횟수</td></tr><tr><td>검색 결과 없음 수</td><td>사용자가 검색했지만 결과가 없어 ‘검색 결과 없음’ 페이지가 노출된 횟수</td></tr><tr><td>클릭 수</td><td>검색 결과 노출 후 사용자가 아이템을 클릭한 총 횟수, 하나의 검색에서 여러 클릭이 발생할 수 있음</td></tr><tr><td>클릭 수 없음 수</td><td>검색 결과가 노출되었으나 사용자가 아무 아이템도 클릭하지 않은 횟수</td></tr><tr><td>클릭 전환율 </td><td>전체 검색 중 클릭이 발생한 비율로, <code>(클릭 수 ÷ 전체 검색 수) × 100</code>으로 계산된 수치</td></tr></tbody></table>

### **인기 키워드 비율** <a href="#anal-3-2" id="anal-3-2"></a>

최근 사용자 검색에서 자주 사용된 키워드의 비율을 그래프로 확인할 수 있습니다.

각 색상은 서로 다른 키워드를 나타내며, 도넛의 면적이 클수록 해당 키워드가 더 많이 검색되었음을 의미합니다. 어떤 키워드가 현재 인기 있는지 한눈에 파악할 수 있습니다.

#### 검색 데이터

검색부터 클릭까지의 주요 지표를 단계별로 시각화한 것입니다. 검색 수, 노출 수, 클릭 수 등을 비교하여 사용자 행동 흐름과 전환 손실 구간을 쉽게 파악할 수 있습니다.

## 인기 검색 TOP100 <a href="#anal-4" id="anal-4"></a>

<figure><img src="/files/I6Q4Bl7Ml1U2el310Cg2" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="158.2529296875">항목</th><th>설명</th></tr></thead><tbody><tr><td> 순위</td><td>사용자들이 검색한 키워드 기준 검색 수와 클릭 수를 집계한 상위 100개의 데이터</td></tr><tr><td>키워드</td><td>사용자가 입력한 검색어의 키워드</td></tr><tr><td>검색 수</td><td>해당 키워드가 입력된 총 횟수</td></tr><tr><td>클릭 수</td><td>검색 결과에서 사용자가 해당 키워드의 아이템을 클릭한 횟수</td></tr></tbody></table>

## 검색 내역 <a href="#anal-5" id="anal-5"></a>

해당 인스턴스의 검색 내역을 키워드별 상세하게 확인할 수 있습니다.

### 키워드 <a href="#anal-5-1" id="anal-5-1"></a>

키워드별 검색 지표를 통해 사용자의 관심도를 파악할 수 있습니다.\
검색 수가 많은 키워드는 현재 주목받고 있는 관심사이며, 클릭 수가 많은 키워드는 실제 행동으로 이어진 키워드입니다.\
클릭 없음이나 검색 결과 없음이 많은 키워드는 검색 품질 개선이나 콘텐츠 보완이 필요한 영역으로 해석할 수 있습니다.

<figure><img src="/files/F2oeEkvmLZ2iSC2U6k8z" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="158.23828125">항목</th><th>설명</th></tr></thead><tbody><tr><td>순위</td><td>검색, 클릭, 클릭 없음, 검색 결과 없음의 검색이 많은 수를 집계한 상위 100개의 데이터</td></tr><tr><td>키워드</td><td>사용자가 입력한 검색어의 키워드</td></tr><tr><td>검색 수</td><td>해당 키워드가 입력된 총 횟수</td></tr></tbody></table>

### 데이터 테이블 <a href="#anal-5-2" id="anal-5-2"></a>

사용자별 검색 이력 데이터 테이블로, 각 검색 이벤트의 상세 정보를 확인할 수 있는 테이블입니다.

<figure><img src="/files/cB7SSHGtfpIdFh68jgRm" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="157.8916015625">항목</th><th>설명</th></tr></thead><tbody><tr><td>검색 일시</td><td>사용자가 검색을 실행한 날짜와 시간 정보</td></tr><tr><td>회원 ID</td><td>로그인한 사용자의 식별 ID입니다. 비로그인 사용자의 경우 비로그인으로 표기</td></tr><tr><td>쿠키 ID</td><td>사용자 기기 또는 브라우저에 할당된 고유 식별값</td></tr><tr><td>검색어</td><td>사용자가 검색창에 직접 입력한 실제 검색어</td></tr><tr><td>키워드</td><td>사용자가 입력한 검색어의 키워드</td></tr></tbody></table>

{% hint style="info" %}
**키워드란?**

고객이 문장으로 검색할 경우, genser의 AI가 이를 분석하여 최대 5개의 핵심 키워드로 추출해 집계합니다.&#x20;
\\

\
**문장형 검색어의 통계 집계 기준**&#x20;

단순한 단어의 나열이 아닙니다. AI가 조사나 불필요한 표현을 걸러내고, **고객의 검색 의도(Intent)가 담긴 '의미 단위'**&#xB9CC;을 남긴 것입니다.
\\

\
**추출 예시**

"30대 남자가 입기 좋은 따뜻한 겨울 코트"로 검색할 경우 키워드는 '30대 남자', '따뜻한 코트', '겨울 코트' 등 입니다.
{% endhint %}


# 용어 사전

<figure><img src="/files/AbOHK68PWdYzaW3XNP3n" alt=""><figcaption></figcaption></figure>

### 용어 사전 이란?

용어 사전은 AI가 기본적으로 잘 이해하지 못할 수 있는 단어나 문구를 미리 정의해두는 공간입니다.

* 고객이 특정 표현으로 검색했을 때(예: “연예인 효소”), 시스템이 해당 용어를 인식하고 알맞은 상품을 보여줄 수 있도록 설정합니다.
* AI가 바로 이해하기 어려운 표현(마케팅/별칭/유행어 등)을 운영자가 설명으로 풀어서 작성할 수 있습니다.

{% hint style="info" %}
예시로, `에그팩`처럼 SNS에서만 통용되는 마케팅 표현이 들어오면, 운영자가 “달걀 성분을 함유한 모공 케어 마스크팩” 같은 설명을 직접 써줘야 고객이 그 검색어를 쳤을 때 올바른 상품과 연결되도록 할 수 있습니다.
{% endhint %}

<figure><img src="/files/FBn2nvcstaVi5N3GsF6C" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/TKVgVLwnh5OHlJgEGMJU" alt=""><figcaption></figcaption></figure>

1\. 새 용어: 버튼을 클릭하면 새로운 전문 용어를 등록할 수 있는 창이 나타납니다.

2\. 용어 목록: 등록한 용어와 정의, 등록 일시를 확인할 수 있습니다.

<figure><img src="/files/KwF9CKglS7YeySoJ7ZlB" alt=""><figcaption></figcaption></figure>

3\. 용어: 새롭게 등록할 용어를 입력할 수 있습니다. \ <sub>- 최대 60자까지 입력 가능</sub>

4\. 정의: 새롭게 등록할 용어 정의를 입력할 수 있습니다.\ <sub>- 최대 120자까지 입력 가능</sub>

{% hint style="info" %}
**글자수 카운팅 안내**

문자 형태(전각/반각)나 언어 종류에 관계없이 입력된 글자 개수 1개를 1자로 카운팅합니다. (예: 'a', '가', 'あ', 'ｱ' 모두 1자로 계산)
{% endhint %}


# 설정

<figure><img src="/files/RK53Kx6PsPG9WCOslIEw" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/VNsk5Kk76hIVlQMKW4Y4" alt=""><figcaption></figcaption></figure>

### 서비스 키

* **서비스 키**는 현재 계정을 식별하는 고유 값으로, API 연동이나 서비스 운영 시 참조됩니다.
* 일반 사용자에게 공유되지 않도록 주의하세요.

### 알림 안내 받기

* 인스턴스를 새로 만들고 전처리 과정이 진행될 때, 사용자가 매번 화면에 들어와 확인하지 않아도 됩니다.
* 전처리 작업이 완료되는 시점에 지정한 이메일 주소로 알림 메일을 발송합니다.


# 자주 묻는 질문 (FAQ)

성공적인 genser 이용을 위해 자주 묻는 질문들을 정리했습니다.

## 설치 및 연동

**Q. genser는 어떻게 설치하나요?**

> **제공되는 가이드를 통해 개발 연동을 진행합니다.** genser 도입이 확정되면 제공되는 **'상품 API 연동 가이드'**&#xC640; **'스크립트 가이드'**&#xB97C; 참고하여 설치를 진행합니다. 백엔드에서 상품 데이터를 API로 연동하고, 프론트엔드에 검색 스크립트를 삽입하면 기본적인 사용 준비 단계가 완료됩니다.

**Q. 여러 개의 검색창(PC/Mobile 등)에 각각 다른 검색 엔진을 적용할 수 있나요?**

> **네, 멀티 인스턴스 기능을 통해 가능합니다.** 하나의 프로젝트 내에서도 인스턴스를 여러 개 생성하여 각각 다른 검색창이나 매체(PC, 모바일, 키오스크 등)에 독립적인 검색 엔진을 설치할 수 있습니다. 이를 통해 매체별로 다른 검색 정책을 운영하는 것도 가능합니다.

## **검색 품질 및 데이터**

**Q. 기존 키워드 검색과 결과 순서가 다른데 오류인가요?**

> **오류가 아닌 '미션 베이스드 서치(Mission Based Search)'의 특성입니다.** genser는 단순 단어 매칭(Exact Match)이 아니라 고객이 해결하고자 하는 '과제(Mission)'와 '맥락'을 이해하여 결과를 제공하므로, 기존 키워드 검색과는 결과 노출 순서가 다를 수 있습니다.

**Q. 상품 속성(Attribute) 데이터가 비어있어도 검색이 잘 되나요?**

> **AI 추론이 가능하지만, 정확한 필터링을 위해선 속성 데이터가 중요합니다.** genser는 AI가 상품 정보를 추론할 수 있지만, '브랜드', '성별', '사이즈' 같은 명확한 필터 기능을 사용하려면 해당 메타 데이터(Attribute)가 입력되어 있는 것이 좋습니다.

**Q. 상품 상세 설명이 텍스트 없이 '통이미지'로만 되어 있는데 괜찮나요?**

> **네, genser의 OCR 기술 등을 통해 AI 학습이 가능합니다.** 상품 상세 정보가 이미지로만 구성되어 있어도 걱정하지 않으셔도 됩니다. genser는 이미지 내 텍스트를 추출(OCR)하거나 이미지를 분석하는 기술을 갖추고 있어, AI가 이를 텍스트 데이터로 변환하여 학습하고 검색에 활용할 수 있도록 처리합니다.

**Q. 고객의 행동 데이터(클릭, 장바구니 등)를 꼭 연동해야 하나요?**

> **필수는 아니지만, 검색 랭킹 최적화 및 분석을 위해 적극 권장합니다.** 초기에는 상품 정보만으로도 검색 서비스 이용이 가능하지만, 고객들이 어떤 상품을 클릭하고 구매했는지에 대한 행동 데이터를 연동하면 대시보드와 분석 페이지를 통해 검색 내역과 이용 패턴을 상세하게 확인하고 분석할 수 있어 운영에 도움이 됩니다.

## **운영 및 설정 제어**

**Q. 특정 상품의 검색 결과 순서를 바꿀 수 있나요?**

> **네, 검색 설정에서 우선순위를 조정할 수 있습니다.** 특정 브랜드, PB 상품, 프로모션 상품 등 전략적으로 중요한 상품군이 검색 결과에서 우선순위를 갖도록 '검색 결과 우선순위(Boosting)' 조건을 설정할 수 있습니다.

**Q. genser에서 검색 결과 페이지의 디자인(UI)을 수정할 수 있나요?**

> **아니요, UI는 고객사에서 직접 개발해야 합니다.** genser는 검색 엔진 기능(SaaS)을 제공하는 솔루션입니다. 검색 결과 데이터를 API로 전달해 드리지만, 이를 화면에 보여주는 프론트엔드 UI/UX 디자인 에디터는 제공하지 않습니다. 자사몰의 디자인 가이드에 맞춰 직접 연동 개발을 진행하셔야 합니다.

**Q. AI가 설명하는 멘트의 말투를 우리 브랜드 톤에 맞출 수 있나요?**

> **네, 가능합니다. (톤앤매너 설정)** 검색 결과에 노출되는 설명문의 길이(글자 수)와 표현의 톤앤매너(Tone & Manner)를 설정할 수 있어 브랜드 이미지에 맞는 응대가 가능합니다.

## **기술 및 연동**

**Q. 상품 데이터 실시간 API 연동 시 데이터 반영 속도는 어느 정도인가요?**

> 일반적인 상품 정보는 일 단위 배치(Batch) 작업을 통해 하루에 한 번 업데이트됩니다. 데이터의 양이 많을 경우 반영에 시간이 조금 더 소요될 수 있습니다. 다만, 구매에 중요한 '품절 여부(재고 상태)'는 지연 없이 실시간으로 즉시 반영됩니다.

**Q. 검색 요청 시 데이터가 genser 서버로 전송될 때 보안은 안전한가요?**

> **네, 고객사의 웹사이트에서 genser 엔진으로 전송되는 모든 데이터는 HTTPS(TLS/SSL)를 통해 보호됩니다.** HTTPS는 일반 HTTP에 암호화 기술인 **TLS(Transport Layer Security)**&#xB97C; 결합한 것으로, genser는 이 중에서도 가장 안전한 최신 버전인 금융권 수준의 보안 표준인 TLS 1.2/1.3을 채택하고 있습니다. 이는 마치 외부와 완전히 차단된 **'전용 보안 터널'**&#xC744; 통해 데이터를 수송하는 것과 같아서, 별도의 이중 암호화 없이도 데이터가 전송되는 모든 구간에서 정보 유출이나 변조를 원천적으로 차단합니다.

**Q. 방화벽 설정을 위해 서버의 아웃바운드 IP를 등록해야 하나요?**

> 기본적으로 젠서 API는 보안을 위해 HTTPS(TLS 1.2 이상) 프로토콜을 통한 통신만을 허용합니다.
>
> * 고객사의 내부 보안 정책상 아웃바운드 IP 화이트리스트 등록이 필요한 경우, [젠서 기술 지원팀](https://genser.ai/)에 문의해 주시면 현재 사용 중인 서버의 IP 대역 정보를 제공해 드립니다.

**Q. 데이터 보안은 안전한가요?**

> 네, 안심하셔도 됩니다. genser는 **'기업용(Enterprise)' 클라우드 기반에서 동작하며**, 일반 무료 AI와는 설계부터 다릅니다. 비유하자면, 일반 무료 AI가 누구나 오가는 **'광장'**&#xC774;라면, 기업용 클라우드와 AI는 철저한 보안 장치가 마련된 **'밀폐 실험실'**&#xC785;니다. 구글 등 글로벌기업의 **데이터 거버넌스(Data Governance) 정책**에 따라 이 클라우드에서 오가는 모든 데이터는 외부로 유출되거나 AI 학습 재료로 재사용되지 않도록 **기술적으로 엄격히 격리(Isolation)**&#xB418;어 있습니다.

## **확장 기능**

**Q. 상품 외에 기획전이나 이벤트 페이지도 같이 검색되게 할 수 있나요?**

> **네, 가능하지만 별도의 연동 및 테스트 과정이 필요합니다.** 상품 DB와는 달리 이벤트나 기획전 데이터를 별도로 연동해야 하며, 검색어 입력 시 관련 이벤트 페이지가 정상적으로 노출되는지 테스트하고 확인하는 절차를 거쳐야 합니다.

**Q. 검색된 상품 이미지와 비슷한 다른 상품을 찾아볼 수 있나요?**

> **네, '이미지 기반 후속 검색' 기능을 지원합니다.** 사용자가 검색 결과에서 마음에 들지만 약간 다른 스타일을 원할 때, 해당 상품 이미지를 기반으로 시각적으로 유사한 상품을 이어서 찾아볼 수 있는 기능을 제공합니다.

## **비용**

**Q. 크레딧(Credit)이란 무엇이며, 언제 차감되나요?**

> 크레딧은 genser 서비스 이용량을 측정하는 과금 단위입니다. 상품 검색을 포함하여 상품 데이터 관리 및 AI 콘텐츠 생성 시에 차감됩니다. 서비스 이용 항목별 정확한 크레딧 차감 기준과 요금제(Plan) 정책은 **요금제 안내 페이지**를 참고해 주시기 바랍니다.

**Q. 크레딧은 페이지를 열 때마다 차감되나요?**

> **실제 '검색 요청'이 발생할 때만 크레딧이 차감됩니다.** 단순히 페이지를 로딩하는 것은 과금되지 않으며, 사용자가 검색어를 입력하여 실제 검색 쿼리가 엔진으로 전송될 때 크레딧이 차감되는 구조입니다.

## PoC(Proof of Concept) 문의

**Q. PoC(Proof of Concept)를 진행하고 싶은데, 어떻게 하면 되나요?**

> **genser는 빠르고 간편한 연동을 통해 즉시 도입이 가능**하므로, 별도의 PoC(Proof of Concept) 과정을 권장하지 않습니다. 단, 고객사의 특수한 요구사항이나 데이터 환경에 대한 사전 검증이 반드시 필요한 경우에 한해 예외적으로 유상 PoC를 진행할 수 있습니다.

<details>

<summary>PoC(Proof of Concept) 진행 절차</summary>

**Step 1. 사전 협의 및 범위 설정 (Kick-off)**

* **목표 설정**: 검색 품질 향상, 특정 카테고리(예: 가구, 패션) 집중 테스트 등 PoC의 주 목적을 정의합니다.
* **비용 산정**: 연동 대상 상품 수와 비즈니스 목적에 따른 AI 모델 튜닝 및 커스터마이징 비용을 견적합니다.

**Step 2. 데이터 준비 및 전달**

* **상품 데이터 연동**: 상품명, 가격, 브랜드, 카테고리 코드, 상세페이지 이미지 URL 등 주요 정보가 누락 없이 정확하게 연동될수록 검색 품질과 결과의 정확도가 향상됩니다.

**Step 3. 데이터 엔진 적용 및 설정**

* **엔진 적용**: 전달받은 상품 데이터를 genser 엔진이 학습하고 검색 가능한 상태로 준비합니다.
* **OCR 및 속성 추출**: 이미지 내 텍스트를 추출(OCR)하거나, AI가 상품 이미지를 분석하여 캡션(Caption)을 생성하는 과정을 수행합니다.
* **기본 설정**: 동의어 용어사전 등록, 제한용어 처리 등 기본적인 검색 환경을 구성합니다.

**Step 4. 테스트 및 품질 고도화**

* **검색 품질 테스트**: 실제 검색어를 입력해보며 의도한 대로 결과가 노출되는지 확인합니다.
  * *체크 포인트: 자연어 검색("넷플릭스 보기 좋은 소파 찾아줘") 처리 정확도, 필터 작동 여부*
* **랭킹/정렬 보정**: 특정 상품군(예: PB상품, 프로모션 상품)의 노출 순서를 조정하거나, 검색 결과의 우선순위를 점검합니다.
* **피드백 반영**: 테스트 과정에서 발견된 이슈(예: 특정 브랜드 검색 시 오매칭)를 수정하고 재반영합니다.

**Step 5. 최종 리포트 및 본계약**

* **결과 분석**: PoC 기간 동안의 검색 정확도, 응답 속도 등의 지표를 분석합니다.
* **비용 확정**: 실제 처리된 데이터 양(OCR 건수 등)에 기반하여 최종 비용을 정산하고 본 도입 계약을 논의합니다.

</details>

**원하는 답변이 없나요?** [기술 지원팀에 문의하기](https://genser.ai/)


# 에러 코드

{% hint style="info" %}
젠서에서 사용하는 에러 코드입니다.
{% endhint %}

| ⁠대분류 코드(분류명)    | 코드  | 설명                | 상세 설명                     |
| --------------- | --- | ----------------- | ------------------------- |
| 001 (파일 에러)     | 001 | 파일 확장자            | 지원하지 않는 파일 확장자입니다.        |
| ​               | 002 | 파일 인코딩            | 지원하지 않는 파일 인코딩 형식입니다.     |
| ​               | 003 | 파일 용량             | 지원하는 파일 용량을 초과하였습니다.      |
| ​               | 004 | 파일명               | 지원하는 파일명의 길이를 초과하였습니다.    |
| ​               | 005 | 손상된 파일            | 손상된 파일입니다.                |
| 100 (데이터 처리 에러) | 100 | 데이터 건수            | 지원하는 데이터 건수를 초과하였습니다.     |
| ​               | 101 | 필수 값 입력되지 않음      | 필수 값이 입력되지 않았습니다.         |
| ​               | 102 | 전화번호 양식 불일치       | 전화번호 양식이 일치하지 않습니다.       |
| ​               | 103 | 전화번호 중복           | 중복된 전화번호가 존재합니다.          |
| ​               | 104 | 숫자 이외의 값 입력       | 전화번호는 숫자만 입력가능합니다.        |
| ​               | 105 | 회원 ID 중복          | 중복된 회원 ID가 존재합니다.         |
| ​               | 106 | 템플릿 형식 불일치        | 템플릿 형식에 맞지 않는 파일입니다.      |
| ​               | 107 | 템플릿에 데이터가 입력되지 않음 | 업로드한 파일에 데이터가 존재하지 않습니다.  |
| 200 (이미지 파일 에러) | 200 | 이미지 사이즈           | 업로드한 이미지의 사이즈는 지원되지 않습니다. |
| ​               | 201 | 이미지 비율            | 업로드한 이미지의 비율은 지원되지 않습니다.  |
| 900 (서버 에러)     | 900 | 서버 에러             | 예기치 못한 에러가 발생했습니다.        |

​


# GMC(Google Merchant Center) 연동 가이드

## **연동 방식**

* GMC 연동은 고객사 환경에 따라 두 가지 방식 중 선택할 수 있습니다.

<table><thead><tr><th width="111.3828125">구분</th><th width="301.65234375">1. 파일 피드 연동</th><th>2. Merchant API 연동</th></tr></thead><tbody><tr><td>방식</td><td>어드민에 파일 URL 등록<br>(구글·유튜브 쇼핑 등에 사용 중인 Feed URL을 통해 상품을 연동)</td><td>GMC Merchant API 호출 방식으로 정해진 엔드포인트로 전송</td></tr><tr><td>수집 방식</td><td>스케줄 기반 자동 수집</td><td>실시간 연동</td></tr></tbody></table>

{% hint style="info" %}
**API 연동 방식:** Google Merchant API 규격의 요청 body를 그대로 정해진 전용 엔드포인트로 전송하면 됩니다. \
상세 엔드포인트는 하위 안내 문서를 참조해 주세요.
{% endhint %}

### **1. 파일 피드 연동**

#### Step 1. URL 등록 및 스케줄 설정

**관리자 화면에서 URL 등록**

* 관리자 화면의 \[상품 연동 관리 > GMC Feed] 화면에서 연동 설정 버튼을 눌러 아래 항목을 입력합니다. &#x20;
* 자사 서버에 피드 파일을 업로드한 후, 해당 파일의 URL을 관리자 화면에 등록합니다.

<figure><img src="/files/LkAIc1Q0VPVVdGJKkt1W" alt=""><figcaption></figcaption></figure>

**URL 형식 조건**

* `http://` 또는 `https://`를 포함한 완전한 URL이어야 합니다.
* 외부에서 접근 가능한 공개 URL이어야 합니다.
* 최대 파일 크기: 4GB

올바른 URL 예시

```
https://example.com/feed/products.tsv
https://cdn.example.com/gmc/feed.xml
```

잘못된 URL 예시

```
www.example.com/feed.tsv       ← http:// 또는 https:// 누락
/products/feed.tsv             ← 상대 경로 불가
```

#### **스케줄 설정**

연동 스케줄: 매일 정해진 시간에 1회 피드 파일을 자동 수집합니다.

* 오늘 예정된 수집이 아직 완료되지 않은 경우 → 당일부터 반영
* 오늘 예정된 수집이 이미 완료된 경우 → 다음 날 00시 이후부터 반영

{% hint style="info" %}
연동 요청이 집중되는 시간대에는 수집 완료까지 다소 시간이 소요될 수 있습니다. \
안정적인 수집을 위해 새벽 시간대 설정을 권장합니다.
{% endhint %}

#### **즉시 연동**&#x20;

스케줄과 별개로 즉시 수집을 실행할 수 있습니다.

* 제공 횟수: 월 3회&#x20;
* 초기화 주기: 매월 1일 자동 초기화
* 실행 방법: \[상품 연동 관리 > GMC Feed > 즉시 연동] 버튼 클릭

#### **Step 2. 저장 및 활성화**

저장 버튼 클릭 시 URL 유효성 검사가 수행되며 이상이 없으면 연동이 활성화됩니다.

* 우측 상단 토글을 ON 상태로 유지해야 스케줄 연동이 정상 동작합니다.
* 설정 완료 후 화면에서 다음 연동 예정 시각을 확인할 수 있습니다.

<figure><img src="/files/tfPKlKhqNGXSHlLM9GeE" alt=""><figcaption></figcaption></figure>

### **2. Merchant API 연동 방법**

GMC Merchant API 규격의 요청 body를 그대로 전용 엔드포인트로 전송하면 됩니다. 별도의 데이터 변환 없이 GMC 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)를 참고해 주세요.&#x20;
{% endhint %}

**GMC API 엔드포인트**

* 요청 주소: <https://gateway.gelatto.ai>

<table><thead><tr><th width="234.796875">Endpoint</th><th>Method</th><th>Header</th><th></th></tr></thead><tbody><tr><td>/collector/google/products</td><td>POST</td><td>Api-Key: 발급받은 API KEY</td><td>Merchant API 바디와 동일</td></tr><tr><td>/collector/google/products/{productInputsName}</td><td>PATCH</td><td>Api-Key: 발급받은 API KEY</td><td>Merchant API 바디와 동일</td></tr><tr><td>/collector/google/products/{productInputsName}</td><td>DELETE</td><td>Api-Key: 발급받은 API KEY</td><td></td></tr></tbody></table>

***

## FAQ

**Q. 파일 피드 연동 시 사전에 필요한 설정이 있나요?**

구글 쇼핑 규격에 맞는 TSV 또는 XML 피드 파일을 준비합니다. 준비된 피드 파일을 자사 서버에 업로드하고, 외부 접근 가능한 URL을 확인합니다.

* Google Merchant Center 피드 규격을 준수해야 하며 파일 크기는 최대 4GB 입니다.
* 파일은 저희 서버에서 HTTP GET 요청으로 접근 가능해야 합니다.

**Q. 피드 파일이 업데이트될 때마다 URL을 다시 등록해야 하나요?**

아닙니다. URL은 한 번만 등록하면 됩니다. 이후에는 동일한 URL 경로에 파일을 덮어쓰기 업로드하면 스케줄에 따라 최신 파일이 자동으로 수집됩니다.

**Q. 스케줄 연동 시각을 변경하면 언제부터 적용되나요?**

오늘 예정된 수집이 아직 완료되지 않은 경우 당일부터 반영되며, 이미 완료된 경우에는 다음 날부터 적용됩니다.

**Q. API 연동 방식은 어떻게 진행하나요?**

GMC Merchant API 규격 그대로 전용 엔드포인트에 요청하시면 됩니다. GMC 공식 문서를 참고해 주세요.


# GMC（Google Merchant Center）連携ガイド

## **連携方式**

* GMC連携は、お客様の環境に応じて2つの方式からお選びいただけます。

<table><thead><tr><th width="111.3828125">区分</th><th width="301.65234375">1. ファイルフィード連携</th><th>2. Merchant API連携</th></tr></thead><tbody><tr><td>方式</td><td>管理画面にファイルURLを登録（Google・YouTubeショッピング等で使用中のFeed URLを通じて商品を連携）</td><td>GMC Merchant APIの呼び出し方式で、指定のエンドポイントへ送信</td></tr><tr><td>収集方式</td><td>スケジュールベースの自動収集</td><td>リアルタイム連携</td></tr></tbody></table>

{% hint style="info" %}
**API連携方式**：Google Merchant APIの仕様に基づいたリクエストbodyを、そのまま専用エンドポイントへ送信してください。詳細なエンドポイントについては、下位の案内ドキュメントをご参照ください。
{% endhint %}

### **1. ファイルフィード連携**

#### Step 1. URL登録およびスケジュール設定

**管理画面でのURL登録**

* 管理画面の【連携商品管理 > GMC Feed】画面で連携設定ボタンを押し、以下の項目を入力します。&#x20;
* 自社サーバーにフィードファイルをアップロードした後、該当ファイルのURLを画面に登録します。

<figure><img src="/files/X8YRJy6w8aA1vvK44rmm" alt=""><figcaption></figcaption></figure>

**URL形式の条件**

* `http://` または `https://` を含む完全なURLである必要があります。
* 外部からアクセス可能な公開URLである必要があります。
* 最大ファイルサイズ：4GB

正しいURLの例

```
https://example.com/feed/products.tsv
https://cdn.example.com/gmc/feed.xml
```

誤ったURLの例

```
www.example.com/feed.tsv       ← http:// または https:// が欠落している
/products/feed.tsv             ← 相対パスは使用不可
```

#### **スケジュール設定**

連携スケジュール：毎日決まった時間に1回、フィードファイルを自動収集します。

* 当日予定の収集がまだ完了していない場合 → 当日から反映
* 当日予定の収集がすでに完了している場合 → 翌日0時以降から反映

{% hint style="info" %}
連携リクエストが集中する時間帯は、収集完了までに時間がかかる場合があります。\
安定した収集のため、深夜時間帯の設定を推奨します。
{% endhint %}

#### 即時連携&#x20;

スケジュールとは別に、即時収集を実行することができます。

* 提供回数：月3回
* リセット周期：毎月1日に自動リセット
* 実行方法：【連携商品管理 > GMC Feed > 即時連携】ボタンをクリック

#### Step 2. 保存および有効化

【保存】ボタンをクリックするとURLの有効性チェックが実行され、問題がなければ連携が有効化されます。

* 右上のトグルをON状態に維持することで、スケジュール連携が正常に動作します。
* 設定完了後、画面から次回の連携予定時刻を確認できます。

<figure><img src="/files/p3TY9QBaJejtMz7doiay" alt=""><figcaption></figcaption></figure>

### **2. Merchant API連携方法**

GMC Merchant APIの仕様に基づいたリクエストbodyを、そのまま専用エンドポイントへ送信してください。別途データ変換を行うことなく、GMC API標準の方式をそのままご利用いただけます。

{% hint style="info" %}
GMC Merchant APIの仕様については、[Google公式ドキ](https://developers.google.com/merchant/api/reference/rest/products_v1/accounts.productInputs?_gl=1*1vgo8gg*_up*MQ..*_ga*MTE4OTkwOTY4NC4xNzcyNzEyNzM0*_ga_SM8HXJ53K2*czE3NzI3MTI3MzQkbzEkZzAkdDE3NzI3MTI3MzQkajYwJGwwJGgw#ProductInput)ュメントをご参照ください。
{% endhint %}

**GMC APIエンドポイント**

* リクエスト先：[https://gateway.gelatto.jp](https://gateway.gelatto.ai)

<table><thead><tr><th width="234.796875">Endpoint</th><th width="114.9921875">Method</th><th width="175.58984375">Header</th><th></th></tr></thead><tbody><tr><td>/collector/google/products</td><td>POST</td><td>Api-Key：発行済みのAPI KEY</td><td>Merchant APIのbodyと同一</td></tr><tr><td>/collector/google/products/{productInputsName}</td><td>PATCH</td><td>Api-Key：発行済みのAPI KEY</td><td>Merchant APIのbodyと同一</td></tr><tr><td>/collector/google/products/{productInputsName}</td><td>DELETE</td><td>Api-Key：発行済みのAPI KEY</td><td></td></tr></tbody></table>

***

## FAQ

**Q. ファイルフィード連携の際、事前に必要な設定はありますか？**

Googleショッピングの仕様に準拠したTSVまたはXMLのフィードファイルを準備します。準備したフィードファイルを自社サーバーにアップロードし、外部からアクセス可能なURLを確認します。

* Google Merchant Centerのフィード仕様に準拠する必要があり、ファイルサイズは最大4GBです。
* ファイルは弊社サーバーからHTTP GETリクエストでアクセス可能である必要があります。

**Q. フィードファイルが更新されるたびにURLを再登録する必要がありますか？**

いいえ。URLは一度登録するだけで構いません。以降は同じURLパスにファイルを上書きアップロードすることで、スケジュールに従って最新ファイルが自動的に収集されます。

**Q. スケジュール連携の時刻を変更した場合、いつから反映されますか？**

当日予定の収集がまだ完了していない場合は当日から反映され、すでに完了している場合は翌日から適用されます。

**Q. API連携方式はどのように進めればよいですか？**

GMC Merchant APIの仕様のまま、弊社の専用エンドポイントへリクエストしてください。GMC公式ドキュメントをご参照ください。