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

```

--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.genser.ai/integration/frontend-installation/installation-guide.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.