navigation
현재 뷰를 닫거나, 외부 URL을 열거나, 콘텐츠를 공유하고, 화면 방향·보안·절전 모드 같은 디바이스 수준 설정을 제어합니다. 미니앱의 화면 흐름 및 호스트 환경 통합에 필요한 API를 한데 모은 네임스페이스입니다.
메서드
| 메서드 | 용도 |
|---|---|
closeView | 현재 미니앱 뷰를 닫습니다. |
getTossShareLink | 토스 인앱 공유 링크를 생성합니다. |
openURL | 외부 URL을 엽니다. |
requestReview | 앱 스토어 리뷰 요청 다이얼로그를 트리거합니다. |
setDeviceOrientation | 화면 방향을 세로 또는 가로로 설정합니다. |
setIosSwipeGestureEnabled | iOS 엣지 스와이프 뒤로가기 제스처를 활성화 또는 비활성화합니다. |
setScreenAwakeMode | 화면 자동 꺼짐을 방지합니다. |
setSecureScreen | 화면 캡처 및 녹화 차단을 설정합니다. |
share | 시스템 공유 시트를 통해 메시지를 공유합니다. |
권한
권한이 필요하지 않습니다. navigation 네임스페이스의 메서드들은 별도의 PermissionName에 바인딩되지 않으며, getPermission() / openPermissionDialog() 유틸도 노출하지 않습니다. 권한이 필요한 다른 네임스페이스에서의 일반적인 처리 흐름은 Guides — 권한 처리 패턴을 참고하세요.
UX 가이드
closeView는 명시적 탈출 경로에만 사용하세요. "완료" 버튼이나 "닫기" 아이콘처럼 사용자가 의도적으로 현재 화면을 벗어나는 시점에만 호출하세요. 오류 핸들러 같은 비의도적 경로에서 호출하면 뷰가 예기치 않게 사라집니다.setScreenAwakeMode는 반드시 해제하세요. 지도·운동 추적처럼 화면이 켜져 있어야 하는 기능이 끝나면setScreenAwakeMode({ enabled: false })를 호출해 배터리를 아끼세요. ReactuseEffectcleanup이 적합합니다.setSecureScreen을 과도하게 적용하지 마세요. 결제 정보, 주민등록번호 등 민감한 화면에만 활성화하세요. 모든 화면을 보안 화면으로 설정하면 사용자가 앱 내용을 공유하기 어렵고 접근성 도구와 충돌할 수 있습니다.setDeviceOrientation은 기능에 맞게 쓰세요. 동영상 재생, 게임처럼 가로 모드가 실제로 필요한 기능에서만 방향을 제어하세요. 이유 없이 방향을 고정하면 사용자 경험에 마찰을 줍니다.
직접 실행해 보기
sdk-example의 Navigation 페이지에서 모든 메서드를 실험해 볼 수 있습니다.
sdk-example에서 실행해 보기외부 참조
@apps-in-toss/web-framework— 상위 SDK 패키지. 실제 export는 내부적으로@apps-in-toss/web-bridge에서 가져옵니다.- 표준 Web API 대응:
navigator.share—@ait-co/polyfill이share를navigator.share위에 shim으로 제공합니다.