Events

위젯의 상태 변화와 동작을 감지하기 위한 이벤트 리스너를 제공합니다.

이벤트 등록 및 해제

on(event, handler)

이벤트 리스너를 등록합니다.

widget.on<T extends MSAPChat.EventType>(event: T, handler: MSAPChat.EventHandler<T>): void;

파라미터:

• event: 이벤트 타입 ('open' | 'close' | 'message' | 'ready' | 'error')
• handler: 이벤트가 발생할 때 호출될 함수

const widget = MSAPChat.init({
  applicationKey: 'your-application-key',
});

widget.on('open', () => {
  console.log('위젯이 열렸습니다');
});

off(event, handler)

이벤트 리스너를 해제합니다.

widget.off<T extends MSAPChat.EventType>(event: T, handler: MSAPChat.EventHandler<T>): void;

파라미터:

• event: 이벤트 타입
• handler: 해제할 핸들러 함수 (on으로 등록한 동일한 함수)

function handleOpen() {
  console.log('위젯이 열렸습니다');
}

// 등록
widget.on('open', handleOpen);

// 해제
widget.off('open', handleOpen);

지원되는 이벤트

open

위젯이 열렸을 때 발생하는 이벤트입니다.

widget.on('open', () => {
  console.log('채팅 위젯이 열렸습니다');
  // 분석 이벤트 전송, UI 업데이트 등
});

close

위젯이 닫혔을 때 발생하는 이벤트입니다.

widget.on('close', () => {
  console.log('채팅 위젯이 닫혔습니다');
  // 상태 저장, 정리 작업 등
});

message

새 메시지를 받았을 때 발생하는 이벤트입니다.

widget.on('message', (message) => {
  console.log('새 메시지:', message);
  // 알림 표시, 메시지 카운트 업데이트 등
});

INFO

message 이벤트는 iframe 내부에서 MESSAGE 타입의 postMessage를 보낼 때 발생합니다.

ready

위젯이 완전히 로드되고 준비되었을 때 발생하는 이벤트입니다.

widget.on('ready', () => {
  console.log('위젯이 준비되었습니다');
  // 위젯 제어 시작, 초기 메시지 전송 등
});

error

오류가 발생했을 때 발생하는 이벤트입니다.

widget.on('error', (error) => {
  console.error('에러 발생:', error);
  // 에러 로깅, 사용자 알림 등
});

WARNING

error 이벤트는 iframe 내부에서 ERROR 타입의 postMessage를 보낼 때 발생합니다.

사용 예제

기본 사용법

const widget = MSAPChat.init({
  applicationKey: 'your-application-key',
});

// 위젯이 준비되면 자동으로 열기
widget.on('ready', () => {
  console.log('위젯 준비 완료');
  widget.open();
});

// 위젯 열림/닫힘 추적
widget.on('open', () => {
  console.log('위젯 열림');
});

widget.on('close', () => {
  console.log('위젯 닫힘');
});

// 메시지 알림
widget.on('message', (message) => {
  console.log('새 메시지:', message);
  // 브라우저 알림 표시
  if (Notification.permission === 'granted') {
    new Notification('새 메시지', {
      body: message,
    });
  }
});

// 에러 처리
widget.on('error', (error) => {
  console.error('위젯 에러:', error);
});

이벤트 리스너 관리

// 핸들러 함수 정의
function handleOpen() {
  console.log('위젯 열림');
}

function handleClose() {
  console.log('위젯 닫힘');
}

// 이벤트 등록
widget.on('open', handleOpen);
widget.on('close', handleClose);

// 나중에 이벤트 해제
widget.off('open', handleOpen);
widget.off('close', handleClose);

일회성 이벤트 리스너

// 한 번만 실행되는 리스너
function onceReady() {
  console.log('위젯이 처음 준비되었습니다');
  widget.off('ready', onceReady); // 자동 해제
}

widget.on('ready', onceReady);

상태 추적

let messageCount = 0;

widget.on('message', (message) => {
  messageCount++;
  updateBadge(messageCount);
});

widget.on('open', () => {
  messageCount = 0;
  updateBadge(0);
});

function updateBadge(count) {
  const badge = document.getElementById('message-badge');
  badge.textContent = count;
  badge.style.display = count > 0 ? 'block' : 'none';
}

TypeScript 타입

아래 타입은 SDK의 msap-ai-chat.d.ts가 제공하는 전역 MSAPChat 네임스페이스에서 사용할 수 있습니다. 타입 파일 설치 방법은 TypeScript 타입 안내를 참고하세요.

declare namespace MSAPChat {
  type EventType = 'open' | 'close' | 'message' | 'ready' | 'error';

  interface EventMap {
    open: undefined;
    close: undefined;
    message: unknown;
    ready: undefined;
    error: Error | string | unknown;
  }

  type EventHandler<T extends EventType> = (data: EventMap[T]) => void;

  interface Instance {
    on<T extends EventType>(event: T, handler: EventHandler<T>): void;
    off<T extends EventType>(event: T, handler: EventHandler<T>): void;
    // ... other methods
  }
}

타입 안전한 사용법

// 올바른 사용
widget.on('open', () => {
  // open 이벤트 데이터는 undefined
});

widget.on('message', (data) => {
  // data는 unknown 타입이므로 타입 체크 필요
  console.log(data);
});

widget.on('error', (error) => {
  // error는 Error | string | unknown
  if (error instanceof Error) {
    console.error(error.message);
  }
});

// 타입 오류 발생
widget.on('open', (data: string) => {
  // Error: 'open' 이벤트 데이터는 undefined 타입
});

주의사항

• 메모리 누수 방지: 컴포넌트 언마운트 시 반드시 off()로 이벤트 리스너를 해제하세요.
• 에러 핸들링: 이벤트 핸들러 내부에서 발생한 에러는 콘솔에 로그되지만 다른 리스너에는 영향을 주지 않습니다.
• 동기 실행: 모든 이벤트 핸들러는 동기적으로 실행됩니다.
• 등록 순서: 같은 이벤트에 여러 핸들러를 등록하면 등록된 순서대로 실행됩니다.

다음 단계

• Methods - 현재 사용 가능한 메서드
• Examples - 라이브 예제
• Options - 초기화 옵션