> For the complete documentation index, see [llms.txt](https://groobee.gitbook.io/gelatto/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://groobee.gitbook.io/gelatto/getting-started/installation/widget-customizing.md).

# 챗봇 위젯 커스터마이징

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

이 문서는 임베디드 챗봇 위젯 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>