개발 문서

플러그인 옵션

요약

Mindlogic Plugin은 다양한 설정 옵션을 통해 맞춤화가 가능합니다. 이 문서에서는 MLCPluginOptions 인터페이스에서 사용할 수 있는 모든 옵션을 자세히 설명합니다.

시작하기

플러그인 설정은 MLCPlugin.init() 함수에 옵션 객체를 전달하여 이루어집니다:


javascript
window.MLCPlugin.init('window-id', {
  // 여기에 옵션 추가
});

모든 옵션은 선택사항입니다. 기본값을 사용하려면 해당 옵션을 생략하면 됩니다.

옵션 요약

아래 표는 사용 가능한 모든 옵션의 요약입니다. 각 옵션에 대한 자세한 설명은 아래에서 확인할 수 있습니다.

속성명	타입	기본값	설명
divId	`string`	`"mlc-root"`	Plugin이 마운트될 HTML 엘리먼트 ID
position	`object`	`{ right: 10, bottom: 10 }`	뷰포트 내 Plugin의 초기 위치
initialOpen	`boolean`	`false`	초기화 시 Plugin의 열림 상태
movePlugin	`boolean`	`false`	Plugin 이동 및 크기 조절 가능 여부
customImage	`object`	-	Plugin 트리거 버튼의 커스텀 이미지
hideButton	`boolean`	`false`	트리거 버튼 숨김 여부
showInitialGuideModal	`boolean`	`true`	첫 접속 시 가이드 모달 표시 여부
hideCloseButton	`boolean`	`false`	닫기 버튼 숨김 여부
stylesheetUrl	`string`	-	외부 스타일시트 URL
styles	`string`	-	인라인 커스텀 CSS
onMessageSend	`function`	-	메시지 전송 시 콜백
onRefresh	`function`	-	세션 새로고침 시 콜백
onHide	`function`	-	채팅창 닫기 시 콜백
onOpen	`function`	-	채팅창 열기 시 콜백

레이아웃 및 위치 옵션

다음 옵션들은 플러그인의 레이아웃과 화면상 위치를 제어합니다.

divId

string

플러그인이 마운트될 HTML 요소의 ID를 지정합니다. 기본값은 "mlc-root"입니다.


javascript
window.MLCPlugin.init('YOUR_WINDOW_ID', {
  divId: 'mlc-root',
});

position

object

뷰포트 내에서 플러그인의 초기 위치를 설정합니다. right와 bottom 값으로 화면 가장자리로부터의 거리를 지정합니다.


javascript
window.MLCPlugin.init('YOUR_WINDOW_ID', {
  position: { right: 20, bottom: 30 },
});

모바일 환경에서는 작은 값을 사용하는 것이 좋습니다.

movePlugin

boolean

헤더를 드래그하여 플러그인을 이동하고 모서리를 드래그하여 크기를 조절할 수 있는지 여부를 결정합니다.


javascript
window.MLCPlugin.init('YOUR_WINDOW_ID', {
  movePlugin: false,
});

모바일 환경에서는 크기 조절 기능이 제한적일 수 있습니다.

모양 및 스타일링 옵션

다음 옵션들은 플러그인의 시각적 모양과 스타일을 설정합니다.

customImage

object

플러그인의 트리거 버튼에 사용될 커스텀 이미지의 너비, 높이, URL을 지정합니다.


javascript
window.MLCPlugin.init('YOUR_WINDOW_ID', {
  customImage: {
    width: 60,
    height: 60,
    url: 'https://example.com/custom-image.png',
  },
});

고품질 이미지를 사용하고, 최소 60x60 픽셀 크기를 유지하세요.

stylesheetUrl

string

플러그인의 Shadow DOM에 로드될 외부 스타일시트의 URL을 지정합니다.


javascript
// 예시: CSS 파일을 인라인으로 가져오기
const pluginStyles = await import('./plugin-styles.css?inline');

window.MLCPlugin.init('YOUR_WINDOW_ID', {
  styles: pluginStyles.default,
});

styles

string

플러그인의 Shadow DOM에 직접 주입될 커스텀 CSS 문자열을 지정합니다.

스타일 충돌을 방지하기 위해 플러그인 내부 요소를 신중하게 정의하세요.

동작 제어 옵션

다음 옵션들은 플러그인의 동작을 제어합니다.

initialOpen

boolean

플러그인이 초기화될 때 열려 있는 상태로 시작할지 여부를 결정합니다. 기본값은 false입니다.


javascript
window.MLCPlugin.init('YOUR_WINDOW_ID', {
  initialOpen: false,
});

hideButton

boolean

플러그인의 트리거 버튼을 숨길지 여부를 결정합니다. true로 설정하면 사용자가 수동으로 플러그인을 트리거할 수 없습니다.


javascript
window.MLCPlugin.init('YOUR_WINDOW_ID', {
  hideButton: false,
});

이 옵션을 true로 설정할 경우, 자체 UI 요소를 통해 플러그인을 제어하는 방식을 구현하세요.

showInitialGuideModal

boolean

사용자가 처음 접속할 때 가이드 모달을 표시할지 여부를 결정합니다. 기본값은 true입니다.


javascript
window.MLCPlugin.init('YOUR_WINDOW_ID', {
  showInitialGuideModal: true,
});

가이드 모달을 사용하려면 콘솔에 가이드 내용을 추가하여야 모달이 호출됩니다.

hideCloseButton

boolean

채팅 창 헤더의 닫기 버튼 표시 여부를 제어합니다. true로 설정하면 사용자가 수동으로 채팅 창을 닫을 수 없습니다.


javascript
window.MLCPlugin.init('YOUR_WINDOW_ID', {
  hideCloseButton: false,
});

플러그인이 활성화된 상태에서 헤더의 닫기 버튼이 제거 됩니다 (ex)ESC 같은 단축키는 작동됩니다.

이벤트 콜백 옵션

다음 옵션들은 플러그인의 다양한 이벤트에 대응하는 콜백 함수를 설정합니다.

onMessageSend

function

사용자가 메시지를 보낼 때 트리거되는 콜백 함수입니다. params.sessionId와 params.message를 통해 세션 ID와 메시지 내용에 접근할 수 있습니다.


javascript
window.MLCPlugin.init('YOUR_WINDOW_ID', {
  onMessageSend: params => {
    console.log(
      '메시지 전송: ' + params.message + ', 세션: ' + params.sessionId,
    );
  },
});

사용자 메시지를 분석하여 특정 키워드에 따라 추가 기능을 제공할 수 있습니다.

onRefresh

function

사용자가 세션을 새로고침할 때 트리거되는 콜백 함수입니다. params.sessionId를 통해 세션 ID에 접근할 수 있습니다.


javascript
window.MLCPlugin.init('YOUR_WINDOW_ID', {
  onRefresh: params => {
    console.log('세션이 새로고침됨, ID: ' + params.sessionId);
  },
});

사용자가 직접 refresh 하지 않아도 특정 작업을 할 경우 session을 새로고침 할 수 있습니다.

onHide

function

채팅 창이 닫힐 때 트리거되는 콜백 함수입니다. 사용자 동작이나 프로그래매틱하게 닫힐 때 호출됩니다.


javascript
window.MLCPlugin.init('YOUR_WINDOW_ID', {
  onHide: () => {},
});

사용자가 특정 작업을 할 경우 플러그인을 종료 시킬 수 있습니다.


javascript
window.MLCPlugin.init('YOUR_WINDOW_ID', {
  onOpen: () => {},
});

onOpen

function

채팅 창이 열릴 때 트리거되는 콜백 함수입니다. 사용자 동작이나 프로그래매틱하게 열릴 때 호출됩니다.

콜백 함수를 활용하여 플러그인과 웹사이트 간의 상호작용을 구현할 수 있습니다. 예를 들어, 사용자가 특정 메시지를 보냈을 때 웹사이트의 다른 부분을 업데이트하는 등의 기능을 구현할 수 있습니다.

플러그인 설정 예제

아래는 여러 옵션을 설정하는 예제입니다:


javascript
// 플러그인 초기화 예제 (실행 가능)
const pluginOptions = {
  divId: 'custom-plugin-container',
  position: { right: 20, bottom: 30 },
  initialOpen: true,
  movePlugin: true,
  customImage: {
    width: 60,
    height: 60,
    url: 'https://example.com/custom-image.png',
  },
  hideButton: false,
  showInitialGuideModal: false,
  hideCloseButton: false,
  onRefresh: params => {
    console.log('세션이 새로고침됨, ID: ' + params.sessionId);
    return '세션이 새로고침됨';
  },
  onMessageSend: params => {
    console.log(
      '메시지 전송: ' + params.message + ', 세션: ' + params.sessionId,
    );
    return '메시지 전송됨';
  },
  onHide: () => {
    console.log('채팅창이 닫혔습니다');
    return '채팅창이 닫혔습니다';
  },
  onOpen: () => {
    console.log('채팅창이 열렸습니다');
    return '채팅창이 열렸습니다';
  },
};

// 옵션을 보기 좋게 포맷팅하여 반환합니다
JSON.stringify(pluginOptions, null, 2);

플러그인 설정, 이렇게 확인해보세요!

✅ 모든 스크립트가 올바른 순서로 로드되었나요?

✅ 플러그인 컨테이너 요소가 페이지에 제대로 삽입되었나요?

✅ 커스텀 스타일이 의도한 대로 적용되었나요?

✅ 데스크톱과 모바일 환경 모두에서 테스트해보셨나요?

문제가 발생하면 브라우저 개발자 도구의 콘솔을 확인하여 디버깅 정보를 확인해보세요.

마지막 수정 날짜: Apr 24, 2025

플러그인 메서드

액션 버튼 추가하기

Docs

플러그인 옵션

시작하기

옵션 요약

레이아웃 및 위치 옵션

`divId`
string

`position`
object

`movePlugin`
boolean

모양 및 스타일링 옵션

`customImage`
object

`stylesheetUrl`
string

`styles`
string

동작 제어 옵션

`initialOpen`
boolean

`hideButton`
boolean

`showInitialGuideModal`
boolean

`hideCloseButton`
boolean

이벤트 콜백 옵션

`onMessageSend`
function

`onRefresh`
function

`onHide`
function

`onOpen`
function

플러그인 설정 예제