setScreenAwakeMode

화면 자동 꺼짐(화면 절전 모드)을 방지하거나 허용합니다. 지도 내비게이션, 운동 추적, 레시피처럼 사용자가 화면을 계속 봐야 하는 기능에 사용합니다.

시그니처

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

declare function setScreenAwakeMode(options: {
  enabled: boolean;
}): Promise<{ enabled: boolean }>;

파라미터

이름	타입	필수	설명
options.enabled	boolean	✓	true이면 화면 꺼짐 방지 활성화, false이면 비활성화(기본 동작 복원).

반환값

• Promise<{ enabled: boolean }> — 설정이 적용된 후 현재 enabled 상태를 반환합니다.

반드시 해제하세요

화면 꺼짐 방지는 배터리를 빠르게 소모합니다. 기능이 끝나거나 화면을 벗어날 때 반드시 setScreenAwakeMode({ enabled: false })를 호출하세요. React useEffect cleanup을 활용하면 안전합니다.

권한

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

예제

최소 예제

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

await setScreenAwakeMode({ enabled: true });

실전 예제 — 지도 내비게이션 화면

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

export function NavigationMap() {
  useEffect(() => {
    // 내비게이션 중에는 화면이 꺼지지 않게 설정
    setScreenAwakeMode({ enabled: true });

    return () => {
      // 화면을 벗어날 때 꺼짐 방지 해제
      setScreenAwakeMode({ enabled: false });
    };
  }, []);

  return <div>{/* 지도 컴포넌트 */}</div>;
}

직접 실행해 보기

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

→sdk-example에서 실행해 보기

관련 API

• setDeviceOrientation — 화면 방향을 설정합니다.
• setSecureScreen — 화면 캡처·녹화를 차단합니다.

관련 가이드

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

외부 참조

• @apps-in-toss/web-framework — 상위 SDK 패키지. 실제 export는 내부적으로 @apps-in-toss/web-bridge에서 가져옵니다.
• 표준 Web API 대응: Screen Wake Lock API — 브라우저 표준이지만 인앱 webview에서 지원 여부는 호스트 앱에 따라 다릅니다.