setDeviceOrientation

미니앱 화면 방향을 세로(portrait) 또는 가로(landscape)로 설정합니다. 동영상 플레이어, 게임, 지도처럼 특정 방향이 필요한 기능에 사용합니다.

시그니처

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

declare function setDeviceOrientation(options: {
  type: 'portrait' | 'landscape';
}): Promise<void>;

파라미터

이름	타입	필수	설명
options.type	'portrait' | 'landscape'	✓	설정할 화면 방향. 'portrait'는 세로, 'landscape'는 가로입니다.

반환값

• Promise<void> — 방향 변경 요청이 전달되면 resolve.
• devtools mock 환경에서는 DevTools 패널의 Viewport 탭 방향이 변경됩니다. 단, 패널에서 방향을 auto가 아닌 값으로 고정한 경우 SDK 호출은 무시됩니다.

권한

권한이 필요하지 않습니다.

예제

최소 예제

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

await setDeviceOrientation({ type: 'landscape' });

실전 예제 — 동영상 전체 화면 재생

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

export function FullscreenVideoPlayer() {
  useEffect(() => {
    // 동영상 재생 시 가로 모드로 전환
    setDeviceOrientation({ type: 'landscape' });

    return () => {
      // 화면을 벗어날 때 세로 모드로 복원
      setDeviceOrientation({ type: 'portrait' });
    };
  }, []);

  return <video src="/sample.mp4" controls />;
}

직접 실행해 보기

sdk-example의 Navigation 페이지에서 setDeviceOrientation 카드를 실행해 결과를 확인할 수 있습니다.

→sdk-example에서 실행해 보기

관련 API

• setScreenAwakeMode — 화면 자동 꺼짐을 방지합니다.
• setIosSwipeGestureEnabled — iOS 엣지 스와이프 제스처를 제어합니다.

관련 가이드

• Guides — 미니앱 화면 흐름 패턴 — 미니앱 진입·종료, 외부 URL 열기, 화면 컨텍스트(회전·꺼짐·보안) 패턴.

외부 참조

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