# 챗봇 위젯 커스터마이징

## **챗봇 위젯 커스터마이징**

이 문서는 임베디드 챗봇 위젯 UI를 우리 사이트에 맞게 커스텀하게 제어하기 위해 제공되는 공개 함수 두 가지, \
`toggle()` 과 `layoutUpdate(widget)` 사용법을 설명합니다. 

 젤라또 어드민에서 제공하는 위젯 설정 대신, 사이트에서 챗봇 위젯을 커스텀하게 사용할 때 선택적으로 사용해 주세요.

{% hint style="info" %}
두 함수는 **초기화(init) 이후,** **필요한 시점**에 호출해 주세요.
{% endhint %}

챗봇 위젯을 커스터마이징 하기 위해서는 우선 젤라또에서 제공하는 챗봇 위젯 숨김 처리가 필요합니다. 현재 해당 기능은 별도 문의 요청 후 적용할 수 있습니다.

> 기능 문의 및 추가 확인 사항은 <gelatto_sales@plateer.com> 으로 연락해 주세요.

### **커스터마이징 주의 사항**

* 챗봇 위젯의 크기와 위치를 커스텀 한 후 **어드민(관리자 화면) 젤라또 만들기 > 스타일/위젯 설정**에 값을 반영해 주세요.

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

{% hint style="danger" %}
**챗봇 위젯 커스터마이징을 해도 어드민 설정의 위젯 설정은 필수입니다.**

챗봇 대화창(대화 인터페이스)의 위치는 위젯의 크기와 위치를 기반으로 조정됩니다.
{% endhint %}

{% hint style="warning" %}
**linkToStartAutoOpen:true 일 때 버튼 렌더링 속도가 느릴 경우, 다소 어색하게 동작할 수 있습니다.**

linkToStartAutoOpen:false(기본값) 일 때는 영향이 없습니다.

<sub>\*linkToStartAutoOpen: gelatto.init() 제공/챗봇 답변 내 링크 클릭 시 이동한 페이지에서 대화창이 자동 열리도록 설정하는 값</sub>
{% endhint %}

***

## **제공 함수**

### **요약**

<table><thead><tr><th width="300.56640625">함수</th><th>설명</th></tr></thead><tbody><tr><td><code>gelatto.toggle()</code></td><td><ul><li>챗봇 위젯 UI의 표시/숨김을 토글</li><li>포커스/스크롤 포함한 UI 상태를 안전하게 전환</li><li>데스크톱/모바일 환경 모두 지원하며 올바른 전환 처리를 진행</li></ul></td></tr><tr><td><code>gelatto.layoutUpdate(widget: 필수)</code></td><td><ul><li>현재 화면(디바이스/뷰포트)에 맞게 챗봇 대화창과 챗봇 위젯 버튼 레이아웃을 반응형 기준으로 재계산해 즉시 반영</li><li><code>(widget)</code> 인자 필수</li></ul></td></tr></tbody></table>

{% hint style="warning" %}
**필수 사항**

* `gelatto.layoutUpdate(widget)` 함수는 `(widget)` 옵션을 인자로 넘겨 즉시 적용해야 합니다.
* 두 함수 모두 초기화(init) 후 호출해 주세요.
  {% endhint %}

### toggle()

* **설명**: 챗봇 사용자 대화창(컨테이너)의 열림/닫힘 상태를 전환합니다.
* **내용**
  * 닫힘 → 열림: 챗봇 사용자 대화창(컨테이너) 표시, 포커스/스크롤 처리
  * 열림 → 닫힘: 챗봇 사용자 대화창(컨테이너) 숨김

| 항목      | 설명 |
| ------- | -- |
| 입력 파라미터 | 없음 |
| 반환 값    | 없음 |

**사용 예시**

```javascript
// JavaScript
// 챗봇 위젯 버튼 클릭 등 사용자 액션에 바인딩
document.getElementById('openChatBtn').addEventListener('click', () => {
  if (window.gelatto && window.gelatto.toggle) {
     gelatto.toggle();
  }
});
```

### layoutUpdate(widget)

* **설명**: 챗봇 사용자 대화창(컨테이너)과 챗봇 위젯 버튼(플로팅 버튼)의 위치/크기를 현재 Viewport(데스크톱/모바일)에 맞게 재설정합니다.
* **내용**
  * Viewport에 따라 모바일/데스크톱 분기
  * 챗봇 사용자 대화창(컨테이너) 최대 크기, 라운딩, 하단 오프셋 계산 / 확장·축소 상태에 따라 사이즈 스위칭
  * 채팅창 위치·여백 재계산

<table><thead><tr><th width="272.83203125">항목</th><th>설명</th></tr></thead><tbody><tr><td>입력 파라미터</td><td><code>widget</code> (필수): 챗봇 레이아웃 위치 계산에 사용할 옵션 오브젝트</td></tr><tr><td>반환 값</td><td>void</td></tr></tbody></table>

**widget 옵션 필드 예시**

<table><thead><tr><th width="170.5859375">필드명</th><th width="144.0390625">타입</th><th>설명</th></tr></thead><tbody><tr><td>posType</td><td>string</td><td><code>'RIGHT_BOTTOM'</code> | <code>'LEFT_BOTTOM'</code> (데스크톱 위치)</td></tr><tr><td>posSide</td><td>number</td><td>데스크톱 가로 여백(px)</td></tr><tr><td>posBottom</td><td>number</td><td>데스크톱 세로 여백(px)</td></tr><tr><td>mobilePosType</td><td>string</td><td><code>'RIGHT_BOTTOM'</code> | <code>'LEFT_BOTTOM'</code> (모바일 위치)</td></tr><tr><td>mobilePosSide</td><td>number</td><td>모바일 전용 가로 여백(px)</td></tr><tr><td>mobilePosBottom</td><td>number</td><td>모바일 전용 세로 여백(px)</td></tr><tr><td>size</td><td>number</td><td>원형 플로팅 버튼 직경(px)</td></tr></tbody></table>

**사용 예시**

```javascript
// JavaScript
// 즉시 새로운 챗봇 위치/여백을 반영하고 싶을 때
gelatto.layoutUpdate({
  posType: 'LEFT_BOTTOM',
  posSide: 24,
  posBottom: 24,
  mobilePosType: 'RIGHT_BOTTOM',
  mobilePosSide: 16,
  mobilePosBottom: 16,
  size: 56
});
```

{% hint style="warning" %}
**필수 사항**

* 초기 렌더링 이후 동적 레이아웃 변경에서 호출해 최신 레이아웃을 유지해 주세요.
* 어드민 설정 값과 동일하게 전달하고, 필요한 값만 수정해 주세요.
* **SPA 라우팅 환경**에서는 전환 시 열림 상태를 닫는 등 일관성 유지가 필요합니다.
  {% endhint %}

***

## **자주 묻는 질문 (FAQ)**

<details>

<summary>layoutUpdate(widget) 함수를 호출했는데 위치가 바뀌지 않습니다.</summary>

widget 필드 값이 유효하지 않거나(예: `'20px'` → `20`), UI가 아직 렌더링되지 않았을 수 있습니다.&#x20;

</details>


---

# 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://groobee.gitbook.io/gelatto/getting-started/installation/widget-customizing.md?ask=<question>
```

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.