이벤트 제어하기

지원환경: React NativeWebView

실행환경: Toss AppSandbox App

이 문서에서는 앱 동작 중 발생하는 주요 이벤트를 감지하고 제어하는 방법을 안내해요.
대표적으로 뒤로가기 버튼 이벤트와 앱 진입 완료 이벤트를 다룰 수 있어요.

1. 뒤로가기 버튼 이벤트 감지하기

뒤로가기 버튼 이벤트를 제어하면 사용자가 실수로 페이지를 닫는 상황을 방지할 수 있어요.
예를 들어 결제 중이거나 폼 작성 중일 때, 뒤로가기를 눌러 화면이 닫히지 않게 막을 수 있어요.

주요 기능

기능	설명
`backEvent`	뒤로가기 버튼을 누르면 발생하는 이벤트예요.
`graniteEvent.addEventListener('backEvent', { ... })`	이벤트를 구독해요.
`onEvent`	뒤로가기 버튼이 눌리면 호출돼요. 기본 뒤로가기는 차단돼요.
`onError`	이벤트 처리 중 오류가 발생했을 때 호출돼요.
`unsubscription()`	등록된 이벤트 리스너를 해제할 수 있어요.

React Native에서는 useBackEvent() 훅으로 동일한 로직을 구현할 수 있어요.

예제

아래 예시는 사용자가 뒤로가기를 눌렀을 때 확인창을 띄우고, “확인”을 누르면 이동을 허용하는 예시예요.

jsReactReact Native

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

const unsubscription = graniteEvent.addEventListener('backEvent', {
  onEvent: () => {
    const shouldLeave = window.confirm('작성 중인 내용이 저장되지 않아요. 나가시겠어요?');
    if (shouldLeave) {
      // 나가는 코드를 작성해요.
    }
  },
  onError: (error) => {
    console.error(`에러가 발생했어요: ${error}`);
  },
});

window.addEventListener('pagehide', () => {
  unsubscription();
});

tsx

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

function ConfirmBackNavigation() {
  const [formValue, setFormValue] = useState('');

  useEffect(() => {
    const unsubscription = graniteEvent.addEventListener('backEvent', {
      onEvent: () => {
        const shouldLeave = window.confirm('작성 중인 내용이 저장되지 않아요. 나가시겠어요?');
        if (shouldLeave) {
          // 나가는 코드를 작성해요.
        }
      },
      onError: (error) => {
        alert(`에러가 발생했어요: ${error}`);
      },
    });

    return unsubscription;
  }, []);

  return (
    <div>
      <h2>입력 폼</h2>
      <textarea
        value={formValue}
        onChange={(e) => setFormValue(e.target.value)}
        placeholder="여기에 내용을 입력해 주세요"
        rows={5}
        style={{ width: '100%' }}
      />
    </div>
  );
}

tsx

import { useEffect, useState } from "react";
import { Alert, Button, View } from "react-native";
import { useBackEvent } from '@granite-js/react-native';

function UseBackEventExample() {
  const backEvent = useBackEvent();

  const [handler, setHandler] = useState<{ callback: () => void } | undefined>(
    undefined
  );

  useEffect(() => {
    const callback = handler?.callback;

    if (callback != null) {
      backEvent.addEventListener(callback);

      return () => {
        backEvent.removeEventListener(callback);
      };
    }

    return;
  }, [backEvent, handler]);

  return (
    <View>
      <Button
        title="Add BackEvent"
        onPress={() => {
          setHandler({ callback: () => Alert.alert("back") });
        }}
      />
      <Button
        title="Remove BackEvent"
        onPress={() => {
          setHandler(undefined);
        }}
      />
    </View>
  );
}

2. 앱 진입 완료 이벤트 감지하기

앱 진입 후 표시되는 “○○으로 이동했어요” 안내 문구가 사라지는 시점을 감지할 수 있어요. 이 시점을 기준으로 초기화, 데이터 로딩, 애니메이션 시작 등 작업을 수행할 수 있어요.

개요

appsInTossEvent를 사용하면 토스 앱에서 전달되는 다양한 상태 이벤트를 감지할 수 있어요. 그중 entryMessageExited 이벤트는 앱 진입 직후 안내 메시지가 화면에서 사라지는 시점을 알려줘요.

이 이벤트를 활용하면 앱이 사용자 입력을 받을 준비가 된 ready 상태를 정확히 감지할 수 있어요.

주요 기능

이벤트	설명
`appsInTossEvent.addEventListener('entryMessageExited', { onEvent })`	안내 메시지가 화면에서 사라지는 즉시 호출돼요.
`onEvent`	이벤트 발생 시 실행할 콜백 함수를 정의해요.
`onError`	이벤트 처리 중 오류가 발생하면 호출돼요.
`unsubscription()`	등록된 이벤트 리스너를 해제할 수 있어요.

예제

아래 예시는 안내 메시지가 사라진 직후 게임을 시작하는 예시예요.

jsReactReact Native

import { appsInTossEvent } from '@apps-in-toss/web-framework';

function startGame() {
  console.log('게임을 시작합니다!');
}

const unsubscription = appsInTossEvent.addEventListener('entryMessageExited', {
  onEvent: () => {
    startGame();
  },
  onError: (error) => {
    console.error('게임 시작 이벤트 처리 중 오류:', error);
  },
});

window.addEventListener('pagehide', () => {
  unsubscription();
});

tsx

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

/**
 * 안내 메시지가 사라진 시점에 게임을 시작하는 컴포넌트예요.
 *
 * @example
 * import { GameStarter } from './GameStarter';
 *
 * const App = () => <GameStarter />;
 */
function GameStarter() {
  useEffect(() => {
    const unsubscription = appsInTossEvent.addEventListener('entryMessageExited', {
      onEvent: () => {
        // 진입 메시지가 사라진 직후 게임 시작
        startGame();
      },
      onError: (error) => {
        console.error('게임 시작 이벤트 처리 중 오류:', error);
      },
    });

    return () => {
      unsubscription();
    };
  }, []);

  /**
   * 게임을 시작하는 함수예요.
   * 타이머 시작, 캐릭터 등장 등 초기 게임 로직을 이곳에 작성해요.
   */
  const startGame = () => {
    console.log('게임을 시작합니다!');
    // 게임 시작 로직 추가
  };

  return (
    <div>
      <h2>게임을 준비 중...</h2>
    </div>
  );
}

tsx

import { appsInTossEvent } from '@apps-in-toss/framework';
import { useEffect } from 'react';
import { View, Text, StyleSheet } from 'react-native';

/**
 * 안내 메시지가 사라진 시점에 게임을 시작하는 컴포넌트예요.
 *
 * @example
 * import { GameStarter } from './GameStarter';
 *
 * const App = () => <GameStarter />;
 */
function GameStarter() {
  useEffect(() => {
    const unsubscription = appsInTossEvent.addEventListener('entryMessageExited', {
      onEvent: () => {
        // 진입 메시지가 사라진 직후 게임 시작
        startGame();
      },
      onError: (error) => {
        console.error('게임 시작 이벤트 처리 중 오류:', error);
      },
    });

    return () => {
      unsubscription();
    };
  }, []);

  /**
   * 게임을 시작하는 함수예요.
   * 타이머 시작, 캐릭터 등장 등 초기 게임 로직을 이곳에 작성해요.
   */
  const startGame = () => {
    console.log('게임을 시작합니다!');
    // 게임 시작 로직 추가
  };

  return (
    <View>
      <Text>게임을 준비 중...</Text>
    </View>
  );
}

참고사항

graniteEvent는 네이티브 이벤트(뒤로가기 등)를, appsInTossEvent는 토스 앱 내부 상태 변화를 감지해요.
등록된 이벤트 리스너는 반드시 컴포넌트 언마운트 시 해제해야 해요.
이벤트 기반으로 실행되는 작업에는 반드시 에러 핸들러(onError) 를 추가해 예외 상황을 대비하세요.

이벤트 제어하기 ​

1. 뒤로가기 버튼 이벤트 감지하기 ​

주요 기능 ​

예제 ​

2. 앱 진입 완료 이벤트 감지하기 ​

개요 ​

주요 기능 ​

예제 ​

참고사항 ​

이벤트 제어하기

1. 뒤로가기 버튼 이벤트 감지하기

주요 기능

예제

2. 앱 진입 완료 이벤트 감지하기

개요

주요 기능

예제

참고사항