💡 Screen Wake Lock API 완벽 가이드: 브라우저 화면 꺼짐 방지와 배터리 최적화

const isWakeLockSupported = 'wakeLock' in navigator;

if (!isWakeLockSupported) {
  console.warn('이 브라우저는 Screen Wake Lock API를 지원하지 않습니다.');
}

// 센티널 인스턴스를 저장할 변수
let wakeLockSentinel = null;

async function acquireWakeLock() {
  try {
    // 반드시 'screen' 문자열 전달
    wakeLockSentinel = await navigator.wakeLock.request('screen');
    console.log('💡 화면 켜짐 유지(Wake Lock)가 활성화되었습니다.');

    // 락이 시스템이나 다른 요인으로 해제되었을 때의 이벤트 리스너
    wakeLockSentinel.addEventListener('release', () => {
      console.log('🔒 화면 켜짐 유지(Wake Lock)가 해제되었습니다.');
    });
  } catch (err) {
    // 사용자 권한 거부, 배터리 부족, 시스템 정책 등에 의한 예외
    console.error(`Wake Lock 요청 실패: ${err.name}, ${err.message}`);
  }
}

async function releaseWakeLock() {
  if (wakeLockSentinel !== null) {
    await wakeLockSentinel.release();
    wakeLockSentinel = null;
    console.log('수동으로 Wake Lock을 해제했습니다.');
  }
}

if (wakeLockSentinel && !wakeLockSentinel.released) {
  await wakeLockSentinel.release();
}

class ScreenLockManager {
  constructor() {
    this.sentinel = null;
    this.isActive = false;
    this.handleVisibilityChange = this.handleVisibilityChange.bind(this);
  }

  // 사용자가 기능 스위치를 켰을 때
  async enable() {
    this.isActive = true;
    document.addEventListener('visibilitychange', this.handleVisibilityChange);
    await this._request();
  }

  // 사용자가 기능 스위치를 껐을 때
  async disable() {
    this.isActive = false;
    document.removeEventListener('visibilitychange', this.handleVisibilityChange);
    if (this.sentinel) {
      await this.sentinel.release();
      this.sentinel = null;
    }
  }

  async _request() {
    // 탭이 화면에 보이지 않는 상태에서는 락을 요청해도 무조건 실패(AbortError/NotAllowedError)함
    if (document.visibilityState !== 'visible' || !this.isActive) {
      return;
    }

    try {
      this.sentinel = await navigator.wakeLock.request('screen');
      this.sentinel.addEventListener('release', () => {
        // 시스템에 의해 해제되었을 때 UI 상태 동기화 필요 시 처리
      });
      console.log('✅ Wake Lock 획득 성공');
    } catch (err) {
      console.warn('Wake Lock 획득 실패:', err.name);
    }
  }

  async handleVisibilityChange() {
    if (document.visibilityState === 'visible' && this.isActive) {
      // 사용자가 탭으로 복귀했을 때 자동으로 재획득
      await this._request();
    }
  }
}

export const screenLock = new ScreenLockManager();

# 동일 출처(Origin)에만 허용
Permissions-Policy: screen-wake-lock=(self)

# 특정 신뢰된 서드파티 도메인에 허용
Permissions-Policy: screen-wake-lock=(self "https://trusted-kiosk.example.com")

# 페이지 내 모든 스크립트의 Wake Lock 완전 차단
Permissions-Policy: screen-wake-lock=()

<!-- iframe 내부에서 Wake Lock 사용을 명시적으로 승인 -->
<iframe 
  src="https://partner-recipe.example.com/embed"
  title="Recipe Viewer"
  allow="screen-wake-lock"
  width="100%"
  height="600">
</iframe>

async function safeRequestWakeLock(): Promise<WakeLockSentinel | null> {
  if (!('wakeLock' in navigator)) {
    return null;
  }

  try {
    return await navigator.wakeLock.request('screen');
  } catch (error: unknown) {
    if (error instanceof DOMException) {
      switch (error.name) {
        case 'NotAllowedError':
          // 배터리 절약 모드 또는 권한 부족
          showToast('기기 저전력 모드 또는 시스템 설정으로 인해 화면 유지를 켤 수 없습니다.');
          break;
        case 'AbortError':
          // 작업 중단
          break;
        default:
          console.error('Wake Lock 알 수 없는 오류:', error);
      }
    }
    return null;
  }
}

import { useState, useEffect, useRef, useCallback } from 'react';

interface UseWakeLockOptions {
  autoReacquire?: boolean;
  onError?: (err: Error) => void;
  onRelease?: () => void;
}

export function useWakeLock(options: UseWakeLockOptions = {}) {
  const { autoReacquire = true, onError, onRelease } = options;
  
  const [isSupported, setIsSupported] = useState(false);
  const [isLocked, setIsLocked] = useState(false);
  
  const sentinelRef = useRef<WakeLockSentinel | null>(null);
  const isRequestedRef = useRef(false); // 사용자가 의도적으로 켰는지 여부

  useEffect(() => {
    setIsSupported('wakeLock' in navigator);
  }, []);

  const request = useCallback(async () => {
    if (!('wakeLock' in navigator)) {
      return false;
    }

    if (document.visibilityState !== 'visible') {
      return false;
    }

    try {
      // 이미 락이 존재하면 해제 후 재요청
      if (sentinelRef.current && !sentinelRef.current.released) {
        await sentinelRef.current.release();
      }

      const sentinel = await navigator.wakeLock.request('screen');
      sentinelRef.current = sentinel;
      isRequestedRef.current = true;
      setIsLocked(true);

      sentinel.addEventListener('release', () => {
        setIsLocked(false);
        sentinelRef.current = null;
        onRelease?.();
      });

      return true;
    } catch (err) {
      setIsLocked(false);
      onError?.(err as Error);
      return false;
    }
  }, [onError, onRelease]);

  const release = useCallback(async () => {
    isRequestedRef.current = false;
    if (sentinelRef.current && !sentinelRef.current.released) {
      await sentinelRef.current.release();
      sentinelRef.current = null;
    }
    setIsLocked(false);
  }, []);

  // Page Visibility 변화 감지 및 자동 재획득
  useEffect(() => {
    if (!isSupported || !autoReacquire) return;

    const handleVisibilityChange = async () => {
      if (document.visibilityState === 'visible' && isRequestedRef.current) {
        await request();
      }
    };

    document.addEventListener('visibilitychange', handleVisibilityChange);
    return () => {
      document.removeEventListener('visibilitychange', handleVisibilityChange);
    };
  }, [isSupported, autoReacquire, request]);

  // 컴포넌트 언마운트 시 자동 정리
  useEffect(() => {
    return () => {
      if (sentinelRef.current && !sentinelRef.current.released) {
        sentinelRef.current.release();
      }
    };
  }, []);

  return {
    isSupported,
    isLocked,
    request,
    release,
  };
}

export function RecipeViewer({ title, steps }: { title: string; steps: string[] }) {
  const { isSupported, isLocked, request, release } = useWakeLock({
    onError: (err) => alert(`화면 유지 실패: ${err.message}`),
  });

  return (
    <div className="recipe-container">
      <h2>{title}</h2>
      
      {isSupported && (
        <button 
          onClick={isLocked ? release : request}
          className={`wake-btn ${isLocked ? 'active' : ''}`}
        >
          {isLocked ? '💡 요리 모드 켜짐 (화면 유지)' : '🍳 요리 모드 켜기 (화면 유지)'}
        </button>
      )}

      <ol>
        {steps.map((step, idx) => (
          <li key={idx}>{step}</li>
        ))}
      </ol>
    </div>
  );
}

if (!('wakeLock' in navigator)) {
  // UI 버튼 숨김 또는 비활성화 처리
  toggleButton.style.display = 'none';
}