Genser Search Example

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

프론트엔드에서 genser 검색 엔진을 연동하는 전체 과정을 안내합니다. 복잡한 개발 없이, **스크립트 설치**와 **함수 호출**만으로 AI 검색을 구현할 수 있습니다. {% stepper %} {% step %} ## 연동 키 준비하기 (Setup) #### 서비스 키 및 인스턴스 키 확인 스크립트 연동에 필요한 두 가지 필수 키(Key) 값을 genser 어드민에서 미리 확보해야 합니다.

키 이름	설명	용도
서비스 키(Service Key)	서비스 연동을 위한 고유 인증 키	초기화 스크립트(`head` 영역) 설정용
인스턴스 키(Instance Key)	생성된 검색 인스턴스의 고유 식별자	검색 API(`searchProducts`) 및 로그 수집 호출용

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

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

#### 기능 활성화 확인 API 응답에 특정 데이터를 포함받으려면 어드민의 인스턴스 설정에서 해당 기능을 미리 '활성화(ON)' 상태로 변경해야 합니다. {% endstep %} {% step %} ## 스크립트 설치하기 (Install) genser 서비스를 이용하기 위해서는 모든 페이지의 공통 레이아웃에 기본 스크립트를 삽입해야 합니다. {% hint style="warning" %} 공통 레이아웃이 적용되지 않는 페이지가 있다면 해당 페이지에도 개별적으로 스크립트를 삽입해야 합니다. {% endhint %} * **위치:** HTML 문서의 `` 태그 종료 직전. * **주의사항:** * 공통 레이아웃이 적용되지 않는 페이지가 있다면 해당 페이지에도 개별적으로 삽입해야 합니다. * `발급 받은 서비스 키` 부분에 실제 할당받은 키 값을 입력해야 합니다. ```js ``` {% endstep %} {% step %} ## 검색 결과 호출하기 (Search) 기본 스크립트 모든 페이지에 삽입되어 있다는 가정 하에 해당 페이지 내에서 아래와 같은 자바스크립트 함수를 사용할 수 있습니다. 아래의 함수에 타입에 맞는 데이터를 넣어 호출하면 상품 검색 결과 데이터를 받을 수 있습니다. ### 검색 호출(searchProducts) ```js genser.call('searchProducts', { instanceKey: 'instanceKey', // 필수: 어드민에서 생성한 인스턴스 키 queryText: '상품 검색어', // 필수: 사용자 입력 검색어 }) .success((res) => { console.log(res); // 검색 결과 데이터 반환 (아래 응답 구조 참고) }) .error((err) => { console.error(err); // 오류 발생 시 }); ```

항목	타입	필수	설명
instanceKey	string	필수	genser 어드민에서 생성한 인스턴스 키(고유 식별자)
queryText	string	필수	사용자가 입력한 상품 검색어
...		선택	기타 확장 필드 (사용 목적에 따라 추가 가능)

### 응답 데이터 구조(Response) `success` 콜백을 통해 반환되는 데이터는 `type`에 따라 4가지 형태로 구분됩니다. #### 1. 상품 정보(SEARCH) 검색된 상품 목록입니다. ```js { "requestId": "검색어에 대한 ID", "type": "SEARCH", "products": [ { "code": "상품 코드", "name": "상품 이름", ... }, { "code": "상품 코드", "name": "상품 이름", ... }, ], "facet": {}, "nextPageToken": '' } ```

항목	타입	필수	설명
requestId	string	필수	검색어에 대한 고유 요청 ID
type	string	필수	응답 타입(예: " SEARCH")
products	array	필수	상품 목록 배열
products[].code	string	필수	상품 코드
products[].name	string	필수	상품 이름
facet	object	선택	-
nextPageToken	string	선택	-

#### 2. 검색 결과 설명(SUMMARY) `검색 결과 설명 설정`이 어드민에서 활성화된 경우, 검색 결과에 대한 요약 텍스트를 반환합니다. ```js { "requestId": "검색어에 대한 ID", "type": "SUMMARY", "summary": "요약 내용 텍스트" } ```

항목	타입	필수	설명
requestId	string	필수	검색어에 대한 고유 요청 ID
type	string	필수	응답 타입(예: " SUMMARY")
summary	string	필수	검색어 또는 결과에 대한 요약 내용 텍스트

#### 3. 연관 키워드(KEYWORDS) `연관 키워드 설정`이 어드민에서 활성화된 경우, 연관된 추천 키워드 리스트를 반환됩니다. ```js { "requestId": "검색어에 대한 ID", "type": "KEYWORDS", "keywords": ["키워드1", "키워드2"] } ```

항목	타입	필수	설명
requestId	string	필수	검색어에 대한 고유 요청 ID
type	string	필수	응답 타입(예: " KEYWORDS")
keywords	string[]	필수	추천 또는 연관 키워드 배열 (문자열 리스트)

#### 4. 제안 질문(QUESTIONS) `제안 질문 설정`이 어드민에서 활성화된 경우, 사용자가 추가로 궁금해할 만한 질문 리스트를 반환합니다. ```js { "requestId": "검색어에 대한 ID", "type": "QUESTIONS", "questions": [ "질문 내용 1", "질문 내용 2" ] } ```

항목	타입	필수	설명
requestId	string	필수	검색어에 대한 고유 요청 ID
type	string	필수	응답 타입(예: " QUESTIONS")
questions	string[]	필수	제안 질문 배열 (문자열 리스트)

{% 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 }); ```

항목	타입	필수	설명
instance	object	필수	genser 어드민에서 생성한 인스턴스 정보
instance.key	string	필수	genser 어드민에서 생성한 인스턴스 키 (고유 식별자)
goods	array	필수	사용자에게 추천/선택된 상품 목록
goods[].code	string	필수	상품 코드 (`searchProducts` 응답의 상품 코드 사용)
goods[].name	string	필수	상품 이름 (`searchProducts` 응답의 상품 이름 사용)
requestId	string	필수	상품 검색 결과에서 받은 요청 ID (`searchProducts` 응답의 requestId 사용)

### 클릭 (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 }); ```

항목	타입	필수	설명
instance	object	필수	genser 어드민에서 생성한 인스턴스 정보
instance.key	string	필수	genser 어드민에서 생성한 인스턴스 키 (고유 식별자)
goods	array	필수	사용자에게 추천/선택된 상품 목록
goods[].code	string	필수	상품 코드 (`searchProducts` 응답의 상품 코드 사용)
goods[].name	string	필수	상품 이름 (`searchProducts` 응답의 상품 이름 사용)
requestId	string	필수	상품 검색 결과에서 받은 요청 ID (`searchProducts` 응답의 requestId 사용)

{% endstep %} {% endstepper %}

React 코드 예시

```js import React, { useState, useEffect } from 'react'; /** * Genser Search React Component * 전제조건: public/index.html의 에 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 (

{/* 검색 폼 */} {/* 검색 결과 리스트 */}

{products.map((product) => (

handleProductClick(product)} style={{ cursor: 'pointer', margin: '10px 0', border: '1px solid #ddd', padding: '10px' }} > {/* 이미지 처리 (API 응답에 따라 필드명 조정 필요) */} {product.imageUrl &&

}

{product.name}

{product.code}

))}

); }; export default GenserSearch; ```

Vue 코드 예시

```js ```

HTML/JS 코드 예시

```js Genser Search Example

```