events

미니앱에서 발생하는 플랫폼 이벤트(앱인토스, TDS, Granite)를 구독하는 함수 모음입니다. 이벤트 리스너는 addEventListener 호출 시 cleanup 함수를 반환하므로 컴포넌트 unmount 시 반드시 호출해야 합니다. 분석용 로깅은 Analytics 네임스페이스를 참고하세요.

메서드

메서드	반환 타입	용도
appsInTossEvent.addEventListener	() => void	앱인토스 플랫폼 이벤트를 구독합니다.
graniteEvent.addEventListener	() => void	Granite(토스 내부) 이벤트를 구독합니다. backEvent, homeEvent 지원.
onVisibilityChangedByTransparentServiceWeb	() => void	투명 서비스 웹 컨테이너 표시 여부 변화를 구독합니다.
tdsEvent.addEventListener	() => void	TDS(Toss Design System) 이벤트를 구독합니다. navigationAccessoryEvent 지원.

권한

권한이 필요하지 않습니다. events 네임스페이스의 모든 함수는 별도의 PermissionName에 바인딩되지 않습니다.

이벤트 구독 패턴

모든 addEventListener 및 onVisibilityChangedByTransparentServiceWeb은 cleanup 함수를 반환합니다. React에서는 useEffect의 반환값으로 사용하세요.

import { graniteEvent } from '@apps-in-toss/web-framework';
import { useEffect } from 'react';

function Page() {
  useEffect(() => {
    const cleanup = graniteEvent.addEventListener('backEvent', {
      onEvent: () => {
        // 뒤로 가기 버튼 처리
      },
    });
    return cleanup;
  }, []);

  return <main>{/* 페이지 콘텐츠 */}</main>;
}

UX 가이드

• cleanup 누락에 주의하세요. 컴포넌트가 unmount된 뒤에도 이벤트가 발화되면 state 업데이트로 인한 메모리 누수가 발생합니다. useEffect 반환값으로 cleanup을 꼭 호출하세요.
• graniteEvent.backEvent는 하드웨어 뒤로 가기 키 인터셉트에 사용하세요. 구독 중에는 기본 뒤로 가기 동작이 억제되므로, 직접 내비게이션 로직을 구현해야 합니다.
• tdsEvent.navigationAccessoryEvent는 partner.addAccessoryButton과 세트입니다. 버튼을 등록하고 이벤트를 구독하는 두 단계가 모두 필요합니다.

직접 실행해 보기

sdk-example의 Events 페이지에서 이벤트를 직접 구독하고 결과를 확인할 수 있습니다.

→sdk-example에서 실행해 보기

외부 참조

• @apps-in-toss/web-framework — 상위 SDK 패키지. 실제 export는 내부적으로 @apps-in-toss/web-bridge에서 가져옵니다.