@makecode/event-manager

@makecode/event-manager는 웹뷰와 앱 간의 상태 정보 교환 및 이벤트 관리 기능을 제공하는 이벤트 버스 라이브러리입니다. 클라이언트 및 서버 환경 모두를 지원하며, CustomEvent 기반으로 작동합니다.

주요 기능

• 이벤트 등록, 해제 및 디스패치 기능 제공
• 웹뷰와 앱 간의 양방향 통신 지원
• Android 및 iOS 플랫폼 간의 유연한 연동 방식 지원
• Next.js와 같은 SSR 환경에서도 안전하게 사용 가능

설치

npm install @makecode/event-manager

사용법

이벤트 등록 및 디스패치

import {
  eventBusOn,
  eventBusOff,
  eventBusDispatch,
} from '@makecode/event-manager';

// 이벤트 핸들러
const eventHandler = event => {
  console.log('Event received:', event.detail);
};

// 이벤트 리스너 등록
eventBusOn('testEvent', eventHandler);

// 이벤트 디스패치
eventBusDispatch('testEvent', { message: 'Hello from event bus!' });

// 이벤트 리스너 제거
eventBusOff('testEvent', eventHandler);

웹뷰 <-> 앱 연동

앱 > 웹뷰 정보(데이터) 전달을 위한 전역 함수 정의

import { appEventListener } from '@makecode/event-manager';

// 앱 이벤트 리스너 등록
appEventListener('deliverToTheWeb'); // window.deliverToTheWeb 이라는 함수 정의, 이를 통해 App 으로 부터 데이터 전달 받음

// 앱에서 호출 예시
window['deliverToTheWeb']('Message from app to webview!');

웹뷰 > 앱 정보(데이터) 전달

import { webviewDispatch, APP_EVENT_TYPE } from '@makecode/event-manager';

const sendToApp = webviewDispatch('webkit'); // Android 의 경우 bridge 이름 변경 가능 (안드로이드 앱 개발 담당자와 약속된 브리지, window[bridge])
sendToApp('testMessage', { message: 'Hello from webview!' }); // Android 의 경우 window[bridge]['testMessage'] 함수로 호출됨

Next.js 환경에서 사용

SSR 환경에서는 typeof window를 확인하여 클라이언트 환경에서만 이벤트를 처리합니다.

import { appEventListener } from '@makecode/event-manager';

if (typeof window !== 'undefined') {
  // 앱 > 웹뷰 정보(데이터) 전달을 위한 정의
  appEventListener('deliverToTheWeb');
}

'use client';

import { useEffect, ComponentProps, useCallback } from 'react';
import {
  eventBusOn,
  eventBusOff,
  eventBusDispatch,
} from '@lotte/event-manager';

import { EVENT_BUS } from '@/common/constant/event'; // 이벤트 이름 상수로 관리

export default function EventBus() {
  const eventHandler = useCallback(({ detail }: any = {}) => {
    console.log('EventBus', detail);
  }, []);

  useEffect(() => {
    eventBusOff(EVENT_BUS.TEST, eventHandler);
    eventBusOn(EVENT_BUS.TEST, eventHandler);
  }, [eventHandler]);

  const onClick: ComponentProps<'button'>['onClick'] = event => {
    eventBusDispatch(EVENT_BUS.TEST, { data: 'TEST' });
  };

  return (
    <>
      <h2>EvnetBus Test</h2>
      <div>
        <button onClick={onClick}>onClick</button>
      </div>
    </>
  );
}

Android 및 iOS 연동 방식 참고

• Android: window[bridge]type 방식 호출
• iOS (WKWebView): window.webkit.messageHandlers[type].postMessage(payload)
• iOS (스키마 방식): bridge://type 스키마를 iframe으로 호출

테스트 예제

setTimeout(() => {
  // 앱에서 웹뷰로 콜백 실행
  window[APP_EVENT_TYPE.TEST]?.('Test message from app!');
}, 3000);

API

eventBusOn(type: string, listener: EventListener, options?: EventOptions): void

특정 이벤트 타입에 대해 리스너를 등록합니다.

• type: 이벤트 타입을 나타내는 문자열
• listener: 이벤트가 발생했을 때 실행될 콜백 함수
• options: 이벤트 리스너 옵션 (선택 사항)

eventBusOff(type: string, listener: EventListener, options?: EventOptions): void

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

• type: 이벤트 타입을 나타내는 문자열
• listener: 제거할 이벤트 리스너 콜백 함수
• options: 이벤트 리스너 옵션 (선택 사항)

eventBusDispatch(type: string, payload?: any): void

특정 이벤트를 실행합니다.

• type: 실행할 이벤트 타입을 나타내는 문자열
• payload: 이벤트와 함께 전달할 데이터 (선택 사항)

appEventListener(type: string): void

앱에서 호출할 이벤트 리스너를 등록합니다.

• type: 등록할 이벤트 타입

webviewDispatch(bridge: TypedBridge): (type: string, ...payload: any) => any

웹뷰에서 앱으로 데이터를 전송합니다.

• bridge: 웹뷰와 앱 간 통신에 사용할 브릿지 이름 (기본값: 'webkit')
• type: 전송할 이벤트 타입
• payload: 앱으로 전송할 데이터