내비게이션 바 설정
내비게이션 바는 화면 상단에 고정되어 있는 공통 UI 컴포넌트예요.
참고하세요
미니앱 로고 설정은 WebView 설정 또는 React Native 설정 문서를 참고해 주세요.
1. 내비게이션 바 기본 기능
게임
게임용 내비게이션 바는 투명한 배경에 더보기 버튼과 닫기(X) 버튼으로 구성돼요.
주의해 주세요
- X 버튼이 게임 화면의 다른 버튼과 겹치지 않도록 개발해 주세요.
- safeArea 문서를 참고해 주세요.
- X 버튼을 눌렀을 때는 종료 확인 모달을 반드시 표시해 주세요.
- 텍스트 :
$서비스명$을 종료할까요? - 버튼 :
닫기/종료하기(브랜드 컬러 적용)
- 텍스트 :
비게임
비게임 미니앱에서는 흰색 배경의 내비게이션 바가 기본으로 제공돼요.
좌측에는 미니앱 로고와 이름이, 우측에는 더보기 버튼과 X 버튼이 위치해요.
더보기 버튼 기능
더보기 버튼을 통해 아래 기능들을 별도 서버 연동이나 추가 구현 없이 바로 사용할 수 있어요.
문의하기 / 신고하기
콘솔에 등록한 고객센터 링크와 홈페이지 주소가 자동으로 표시돼요.
신고하기 기능을 통해 사용자가 제보를 보낼 수 있고, 파트너사는 콘솔을 통해 제보 내용을 확인할 수 있어요.
공유하기
사용자는 미니앱을 다른 사람에게 쉽게 공유할 수 있어요.
공유 시 미니앱 이름과 딥링크 주소가 함께 전송돼요.
권한 설정
사용자는 미니앱이 요청하는 권한을 확인하고, 언제든지 ON/OFF로 제어할 수 있어요.
홈 화면에 추가하기
자주 사용하는 미니앱을 휴대폰 홈 화면에 바로 등록할 수 있어요.
토스앱 5.246.0 이상부터 확인할 수 있어요.
미니앱 용량 삭제
자주 사용하지 않는 미니앱의 용량을 선택적으로 삭제할 수 있어요.
미니앱 내비게이션 바의 설정 버튼을 통해 서비스별 데이터를 삭제할 수 있어요.
미니앱 알림 ON/OFF
미니앱별 알림 수신 여부를 직접 설정할 수 있어요.
미니앱 내비게이션 바의 설정 버튼을 통해 서비스별 알림을 ON/OFF 할 수 있어요.
2. 디자인 가이드
상단 내비게이션은 사용자에게 일관된 정보 구조를 전달하기 위해 모노톤 아이콘만을 사용해요.
컬러 아이콘은 시각적 주의를 과도하게 분산시키고, 불필요한 강조로 혼란을 줄 수 있기 때문이에요.
특수한 케이스를 제외하고는 모두 모노톤 아이콘으로 통일해 사용하고 있어요.
3. 액세서리 아이콘 추가하기
게임, 비게임 미니앱 모두 우측 상단 더보기 버튼 왼쪽 영역에 아이콘을 한 개 추가할 수 있어요.
플랫폼별 설정 방식
WebView
partner.addAccessoryButton()으로 런타임에 버튼을 추가할 수 있어요.- 클릭 이벤트는
tdsEvent.addEventListener('navigationAccessoryEvent')로 받아요. - 초기 노출은
defineConfig의navigationBar.initialAccessoryButton옵션을 사용해요.
React Native
useTopNavigation()의addAccessoryButton()으로 런타임에 버튼을 추가할 수 있어요.- 또는
granite.config.ts의navigationBar.initialAccessoryButton을 사용해 초기 상태에서 버튼을 노출할 수 있어요.
interface NavigationBarOptions {
withBackButton?: boolean; // 뒤로가기 버튼 유무
withHomeButton?: boolean; // 홈버튼 유무
initialAccessoryButton?: InitialAccessoryButton; // 1개만 노출 가능
}
interface InitialAccessoryButton {
id: string;
title?: string;
icon: {
name: string;
};
}초기 설정
import { defineConfig } from '@apps-in-toss/web-framework/config';
export default defineConfig({
// ...
navigationBar: {
withBackButton: true,
withHomeButton: true,
initialAccessoryButton: {
id: 'heart',
title: 'Heart',
icon: {
name: 'icon-heart-mono',
},
},
},
});import { appsInToss } from '@apps-in-toss/framework/plugins';
import { defineConfig } from '@granite-js/react-native/config';
export default defineConfig({
// ...
plugins: [
appsInToss({
// ...
navigationBar: {
withBackButton: true,
withHomeButton: true,
initialAccessoryButton: {
icon: {
name: 'icon-heart-mono',
},
id: 'heart',
title: '하트',
},
},
}),
],
});동적 추가
import { partner, tdsEvent } from '@apps-in-toss/web-framework';
partner.addAccessoryButton({
id: 'heart',
title: '하트',
icon: {
name: 'icon-heart-mono',
},
});
const cleanup = tdsEvent.addEventListener('navigationAccessoryEvent', {
onEvent: ({ id }) => {
if (id === 'heart') {
console.log('버튼 클릭');
}
},
});
window.addEventListener('pagehide', () => {
cleanup();
});import { partner, tdsEvent } from '@apps-in-toss/web-framework';
useEffect(() => {
partner.addAccessoryButton({
id: 'heart',
title: '하트',
icon: {
name: 'icon-heart-mono',
},
});
const cleanup = tdsEvent.addEventListener('navigationAccessoryEvent', {
onEvent: ({ id }) => {
if (id === 'heart') {
console.log('버튼 클릭');
}
},
});
return cleanup;
}, []);import { useTopNavigation } from '@apps-in-toss/framework';
import { tdsEvent } from '@toss/tds-react-native';
const { addAccessoryButton } = useTopNavigation();
addAccessoryButton({
id: 'heart',
title: '하트',
icon: {
name: 'icon-heart-mono',
},
onPress: () => console.log('버튼 클릭'),
});
useEffect(() => {
const cleanup = tdsEvent.addEventListener('navigationAccessoryEvent', {
onEvent: ({ id }) => {
if (id === 'heart') {
console.log('heart 클릭됨');
}
},
});
return () => {
cleanup();
};
}, []);4. 홈 버튼 추가하기
비게임 미니앱에서는 왼쪽 상단에 홈으로 이동하는 버튼을 표시할 수 있어요.
홈 버튼은 서비스 이름 오른쪽에 위치하며, 사용자가 언제든 첫 화면으로 돌아올 수 있도록 도와줘요.
홈 버튼 관련 동작 제어는 이벤트 제어하기 문서를 참고해 주세요.
주의해주세요
- 오른쪽 액세서리 버튼 영역에는 홈 버튼을 중복 추가하지 말아주세요.
- 홈 버튼은 "서비스 진입점" 역할만 수행하며, 커스텀 기능이나 문구 추가는 불가능해요.
interface NavigationBarOptions {
withHomeButton?: boolean; // 홈 버튼 표시 여부
}navigationBar: {
withBackButton: true,
withHomeButton: true,
}참고사항
- 액세서리 버튼은 모노톤 아이콘만 지원돼요.
- 한 번에 표시할 수 있는 액세서리 버튼은 1개뿐이에요.
- 컬러 아이콘이나 커스텀 UI 추가는 지원하지 않아요.
- 홈 버튼은 비게임 미니앱에서만 사용 가능해요.