스크린 깨우기 잠금 API

W3C 작업 초안

이 문서에 대한 추가 정보
이 버전:
https://www.w3.org/TR/2024/WD-screen-wake-lock-20241024/
최신 공개 버전:
https://www.w3.org/TR/screen-wake-lock/
최신 편집자 초안:
https://w3c.github.io/screen-wake-lock/
히스토리:
https://www.w3.org/standards/history/screen-wake-lock/
커밋 히스토리
테스트 스위트:
https://wpt.live/screen-wake-lock/
구현 보고서:
https://www.w3.org/wiki/DAS/Implementations
편집자:
Kenneth Rohde Christiansen (Intel Corporation)
Marcos Cáceres (Apple Inc.)
이전 편집자:
Raphael Kubo da Costa (Intel Corporation)
(Yandex)
(Yandex)
피드백:
GitHub w3c/screen-wake-lock (풀 리퀘스트, 새 이슈, 열린 이슈)
품질 보증 리드
Wanming Lin (Intel)

Copyright © 2024 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.

요약

이 문서는 웹 애플리케이션이 화면 깨우기 잠금을 요청할 수 있는 API를 명시합니다. 올바른 조건에서 허용된다면, 화면 깨우기 잠금은 시스템이 기기의 화면을 끄는 것을 방지합니다.

문서 현황

이 섹션은 본 문서가 발행된 시점의 상태를 설명합니다. 현재 W3C 발행 목록과 이 기술 보고서의 최신 수정본은 W3C 기술 보고서 인덱스 https://www.w3.org/TR/에서 확인할 수 있습니다.

구현자는 이 명세가 매우 불안정하다는 점을 인지해야 합니다. 논의에 참여하지 않는 구현자는 명세가 호환되지 않는 방식으로 변경되는 것을 경험할 수 있습니다. 이 명세를 최종적으로 후보 권고 단계 전에 구현하고자 하는 공급업체는 GitHub 저장소를 구독하고 논의에 참여해야 합니다.

이 문서는 디바이스 및 센서 워킹 그룹과 웹 애플리케이션 워킹 그룹에서 권고 절차를 사용하여 작업 초안으로 발행되었습니다.

작업 초안으로 발행되었다고 해서 W3C 및 회원의 지지를 의미하지는 않습니다.

이 문서는 초안이며, 언제든지 다른 문서로 업데이트, 대체 또는 폐기될 수 있습니다. 작업 중인 문서 외에 인용하는 것은 적절하지 않습니다.

이 문서는 W3C 특허 정책에 따라 운영되는 그룹에서 작성되었습니다. W3C는 특허 공개(디바이스 및 센서 워킹 그룹) 공개 목록과 특허 공개(웹 애플리케이션 워킹 그룹) 공개 목록을 관리하며, 각 그룹의 전달물과 관련된 공개 페이지에는 특허 공개 방법에 대한 안내도 포함되어 있습니다. 특허의 실질적 권리가 있다고 판단되는 개인은 필수 청구 정보를 W3C 특허 정책 6절에 따라 공개해야 합니다.

이 문서는 2023년 11월 3일 W3C 프로세스 문서에 따릅니다.

1. 소개

이 섹션은 규범적이지 않습니다.

최신 운영 체제는 공격적인 전력 관리 기능을 구현하여 더 긴 배터리 수명을 달성합니다. 즉, 사용자의 활동이 잠시 없으면 호스트 장치는 화면 밝기를 낮추고, 화면을 끄며, 심지어 CPU를 깊은 절전 상태로 진입시켜 전력 사용을 최대한 제한할 수 있습니다.

이런 기능은 배터리 수명 연장에는 매우 유용하지만, 바코드 스캔, 전자책 읽기, 레시피 따라하기, 발표 등과 같은 일부 사용 사례에서는 불편함을 초래할 수 있습니다. 더 많은 내용은 Wake Lock: 사용 사례를 참고하세요.

깨우기 잠금은 일반적으로 어떤 동작을 방지하지만, UA(사용자 에이전트)와 기본 OS는 배터리 상태(전원 연결, 방전 중, 배터리 잔량 낮음)에 따라 깨우기 잠금의 지속 시간을 제한하거나 절전 모드가 활성화된 경우에는 깨우기 잠금을 허용하지 않을 수 있습니다.

2. 깨우기 잠금

이 명세는 다음 깨우기 잠금 유형을 정의합니다:

  1. 스크린 깨우기 잠금은 화면이 꺼지는 것을 방지합니다. 오직 표시되는 문서만 스크린 깨우기 잠금을 획득할 수 있습니다.

API에서는 깨우기 잠금 유형이 WakeLockType 열거형 값으로 표현됩니다.

참고

다른 명세에서 다양한 깨우기 잠금 유형을 정의할 수 있습니다.

3. 정책 제어

스크린 깨우기 잠금 API는 정책 제어 기능을 "screen-wake-lock" 문자열로 식별합니다. 이 기능의 기본 허용 목록은 'self'입니다.

참고

4. 권한 및 사용자 프롬프트

[PERMISSIONS] API는 웹사이트가 사용자로부터 권한을 요청하고, 어떤 권한을 가지고 있는지 질의할 수 있는 통일된 방법을 제공합니다.

사용자 에이전트는 특정 깨우기 잠금 유형에 대해, 특정 Document에 대해, 플랫폼 설정이나 사용자 선호 같은 구현 특정 사유로 깨우기 잠금 거부를 할 수 있습니다.

사용자 에이전트가 깨우기 잠금이 활성화되었을 때, 사용자가 진행 중인 동작을 차단하거나 알림을 닫을 수 있도록, 방해되지 않는 알림을 표시하는 것을 권장합니다.

4.1 "screen-wake-lock" 강력한 기능

"screen-wake-lock" 강력한 기능은 이 명세에서 정의하는 기능을 활성화합니다.

4.2 권한 알고리즘

"screen-wake-lock" 강력한 기능은 권한 철회 알고리즘을 정의합니다. 스크린 깨우기 잠금 권한 철회 알고리즘을 호출하려면 아래 단계를 따릅니다:

  1. document를 현재 글로벌 오브젝트의 연결된 Document로 설정합니다.
  2. lockList를 document.[[ActiveLocks]]["screen"]로 설정합니다.
  3. lockList의 각 lock에 대해:
    1. 깨우기 잠금 해제를 document, lock, "screen"과 함께 실행합니다.

5. 개념

이 명세에서 언급한 작업 소스는 스크린 깨우기 잠금 작업 소스입니다.

플랫폼 깨우기 잠금이란 사용자 에이전트가 상태를 질의하고 깨우기 잠금을 획득/해제할 때 상호작용하는 플랫폼 인터페이스를 의미합니다.

플랫폼 깨우기 잠금은 기본 플랫폼(예: 네이티브 깨우기 잠금 프레임워크)에 의해 정의될 수도 있고, 사용자 에이전트가 직접 하드웨어를 제어할 수 있다면 사용자 에이전트에 의해 정의될 수도 있습니다.

6. Document 인터페이스 확장

6.1 내부 슬롯

내부 슬롯 초기 값 설명
[[ActiveLocks]] 하나의 순서 있는 맵은 깨우기 잠금 유형을 빈 목록에 매핑합니다. 순서 있는 맵으로, 깨우기 잠금 유형을 이 목록에 매핑하며, WakeLockSentinel 객체들이 이 Document와 연결되어 있습니다.

7. Navigator 인터페이스 확장 

WebIDL[SecureContext]
partial interface Navigator {
  [SameObject] readonly attribute WakeLock wakeLock;
};

8. WakeLock 인터페이스

WakeLock 인터페이스는 문서가 스크린 깨우기 잠금을 획득할 수 있도록 해줍니다. 

WebIDL[SecureContext, Exposed=(Window)]
interface WakeLock {
  Promise<WakeLockSentinel> request(optional WakeLockType type = "screen");
};

8.1 request() 메서드

request(type) 메서드 단계:

  1. document를 this의 관련 글로벌 객체의 연결된 Document로 설정합니다.
  2. 만약 document가 완전히 활성 상태가 아니라면, 거부된 promise와 "NotAllowedError" DOMException을 반환합니다.
  3. 만약 document가 사용 허가된 정책 제어 기능 "screen-wake-lock"가 아니라면, 거부된 promise와 "NotAllowedError" DOMException을 반환합니다.
  4. 만약 사용자 에이전트가 이 type의 깨우기 잠금을 document에 대해 거부하면, 거부된 promise와 "NotAllowedError" DOMException을 반환합니다.
  5. 만약 document의 visibility state가 "hidden"이라면, 거부된 promise와 "NotAllowedError" DOMException을 반환합니다.
  6. promise를 새 promise로 설정합니다.
  7. 아래 단계를 병렬로 실행합니다:
    1. state를 "screen-wake-lock" 사용 권한 요청 결과로 설정합니다.
    2. 만약 state가 "denied"이면:
      1. 글로벌 작업 큐에 스크린 깨우기 잠금 작업 소스와 document의 관련 글로벌 객체를 사용하여 promise를 "NotAllowedError" DOMException으로 reject합니다.
      2. 이 단계 중단
    3. 글로벌 작업 큐에 스크린 깨우기 잠금 작업 소스와 document의 관련 글로벌 객체를 사용하여 아래 단계를 실행:
      1. 만약 document가 완전히 활성 상태가 아니라면:
        1. promise를 "NotAllowedError" DOMException으로 reject합니다.
        2. 이 단계 중단
      2. 만약 document의 visibility state가 "hidden"이라면:
        1. promise를 "NotAllowedError" DOMException으로 reject합니다.
        2. 이 단계 중단
      3. 만약 document.[[ActiveLocks]]["screen"] 비어 있다면, 아래 단계를 병렬로 실행:
        1. 깨우기 잠금 획득을 "screen"으로 호출합니다.
          참고
      4. lock을 WakeLockSentinel 객체로 새로 만들고, type 속성을 type으로 설정합니다.
      5. lock을 lock에 document.[[ActiveLocks]]["screen"]에 추가합니다.
      6. promise를 lock으로 resolve합니다.
  8. promise를 반환합니다.

9. WakeLockSentinel 인터페이스 

WebIDL[SecureContext, Exposed=(Window)]
interface WakeLockSentinel : EventTarget {
  readonly attribute boolean released;
  readonly attribute WakeLockType type;
  Promise<undefined> release();
  attribute EventHandler onrelease;
};

WakeLockSentinel 객체는 플랫폼 깨우기 잠금에 대한 핸들을 제공하며, 직접 해제되거나 기본 플랫폼 깨우기 잠금이 해제될 때까지 유지됩니다. 이 객체의 존재는 특정 깨우기 잠금 유형에 대한 플랫폼 깨우기 잠금을 활성 상태로 유지하며, 특정 WakeLockSentinel 인스턴스 전부를 해제하면 해당 플랫폼 깨우기 잠금이 해제됩니다.

참고

9.1 내부 슬롯

WakeLockSentinel 인스턴스는 다음 내부 슬롯으로 생성됩니다:

내부 슬롯 초기 값 설명 (비규범)
[[Released]] false 해당 WakeLockSentinel이 해제되었는지 여부.

9.2 released 속성

released getter 단계는 this.[[Released]]를 반환하는 것입니다.

참고

9.3 type 속성

type getter 단계는 this의 깨우기 잠금 유형을 반환합니다.

9.4 release() 메서드

release() 메서드 단계:

  1. 만약 this의 [[Released]]가 false라면, 깨우기 잠금 해제를 lock을 this로, type을 this의 type 속성 값으로 실행합니다.
  2. undefined로 resolve된 promise를 반환합니다.

9.5 onrelease 속성

onrelease 속성은 "onrelease" 이벤트 핸들러 IDL 속성입니다. 이벤트 핸들러이며, 이벤트 핸들러 이벤트 타입은 "release"입니다.

스크립트에서 WakeLockSentinel 객체의 핸들이 해제되었을 때(직접 release() 호출하거나 사용자 에이전트가 깨우기 잠금을 해제하는 경우) 알림을 받을 때 사용됩니다.

참고
참고

9.6 가비지 컬렉션

WakeLockSentinel 객체가 "release" 이벤트에 대한 하나 이상의 이벤트 리스너를 등록하고, 해당 WakeLockSentinel 객체가 아직 해제되지 않았다면, Window 객체에서 WakeLockSentinel 객체로 강한 참조가 필수입니다.

WakeLockSentinel 객체가 스크린 깨우기 잠금 작업 소스에 작업을 큐에 추가한 동안, Window 객체에서 해당 WakeLockSentinel 객체로 강한 참조가 필수입니다.

10. WakeLockType 열거형

깨우기 잠금 유형을 설명하기 위해, 이 명세는 깨우기 잠금 유형을 나타내는 다음의 열거형을 정의합니다: 

WebIDLenum WakeLockType { "screen" };
screen
스크린 깨우기 잠금 유형.

11. 깨우기 잠금 관리

본 섹션은 특정 깨우기 잠금 유형이 명시적으로 언급되지 않는 한, 각 깨우기 잠금 유형에 동일하고 독립적으로 적용됩니다.

사용자 에이전트는 기본 운영 체제에 잠금 적용을 요청함으로써 깨우기 잠금을 획득합니다. 기본 운영 체제에 대한 요청의 가능한 반환 값은 확인하지 않습니다. 다시 말해, 사용자 에이전트는 깨우기 잠금 획득을 MUST 권고적(advisory)으로만 취급해야 합니다.

반대로, 사용자 에이전트는 기본 운영 체제에 더 이상 깨우기 잠금을 적용하지 않도록 요청함으로써 깨우기 잠금을 해제합니다. 운영 체제에 대한 요청이 성공했을 때에만 잠금이 해제된 것으로 간주됩니다.

운영 체제의 상태가 잠금의 적용을 허용하는 경우(예: 배터리 충전이 충분함) 깨우기 잠금은 적용 가능합니다.

스크린 깨우기 잠금은 사용자가 수동으로 화면을 끈 이후 다시 켜기 전까지 MUST NOT 적용 가능해서는 안 됩니다.

참고

11.1 자동 해제 깨우기 잠금

사용자 에이전트는 언제든지 깨우기 잠금을 해제할 수 있습니다. 예를 들어 다음과 같은 경우:

11.2 문서의 전체 활동 손실 처리

Document document가 더 이상 완전히 활성 상태가 아니게 되면, 사용자 에이전트는 다음 단계를 실행해야 합니다:

  1. 각각의 lock에 대해, document.[[ActiveLocks]]["screen"]에서:
    1. document, lock, "screen"로 깨우기 잠금 해제를 실행합니다.

11.3 문서의 가시성 손실 처리

이 명세는 페이지 가시성 변경 단계를 visibility state state 및 document와 함께 다음과 같이 정의합니다:

  1. state가 "hidden"이 아니면, 이 단계를 중단합니다.
  2. 각각의 lock에 대해, document.[[ActiveLocks]]["screen"]에서:
    1. document, lock, "screen"로 깨우기 잠금 해제를 실행합니다.

11.4 깨우기 잠금 획득 알고리즘

특정 type에 대해 깨우기 잠금을 획득하려면, 다음 단계를 실행합니다:

  1. type에 대한 깨우기 잠금이 적용 가능하지 않다면, 이 단계를 중단합니다.
  2. 기본 운영 체제에 type 유형의 깨우기 잠금을 획득하도록 요청합니다.

11.5 깨우기 잠금 해제 알고리즘

특정 document, lock, type에 대해 깨우기 잠금을 해제하려면, 다음 단계를 실행합니다:

  1. document.[[ActiveLocks]][type]에 lock이 없다면, 이 단계를 중단합니다.
  2. document.[[ActiveLocks]][type]에서 lock을 제거합니다.
  3. document.[[ActiveLocks]][type]이 비어 있다면, 다음 단계를 병렬로 실행합니다:
    1. 기본 운영 체제에 type 유형의 깨우기 잠금을 해제하도록 요청하고, 작업이 성공하면 success를 true로, 그렇지 않으면 false로 설정합니다.
    2. success가 true이고 type이 "screen"이면, 다음을 실행합니다:
      1. 화면이 실제로 꺼지기까지의 플랫폼별 비활성 타이머를 재설정합니다.
      참고
  4. lock의 [[Released]]를 true로 설정합니다.
  5. 이벤트를 발생시킨다(Fire an event) 이름은 "release"이고, lock에서 발생한다.

12. 보안 및 프라이버시 고려사항

스크린 깨우기 잠금은 다양한 기기 구성요소, 특히 디스플레이가 일반보다 더 높은 전력 수준으로 동작하게 할 수 있습니다. 이는 기기가 자동으로 잠금 상태로 전환되는 것을 방지하거나 배터리 소모를 가속화하는 등 바람직하지 않은 결과를 초래할 수 있습니다. 배터리 소모 가속화는 고정 전원 공급원을 즉시 사용할 수 없는 경우가 많은 모바일 기기에서 특히 문제가 됩니다. 예기치 않은 시점에 배터리가 완전히 방전되면 사용자가 통화를 걸거나 받거나 네트워크 서비스를 사용하는 것, 비상 통화 서비스를 포함하여, 이 불가능해질 수 있습니다.

구현은 예를 들어 배터리 용량이 낮거나 사용자가 기기를 절전 모드로 전환한 경우 스크린 깨우기 잠금 요청을 MAY 무시할 수 있습니다.

사용자 에이전트가 스크린 깨우기 잠금이 활성화되었을 때 이를 사용자가 알 수 있도록 하는 UI 또는 인디케이터를 제공하는 것을 RECOMMENDED합니다. 이러한 UI는 특정 웹 애플리케이션이 기기의 에너지에 부정적인 영향을 주는지 최종 사용자가 식별하고, 필요한 경우 조치를 취하는 데 도움을 줄 수 있습니다.

13. 예제

이 섹션은 규범적이지 않습니다.

예시 1: 스크린 깨우기 잠금 획득 및 해제 
function tryKeepScreenAlive(minutes) {
  navigator.wakeLock.request("screen").then(lock => {
    setTimeout(() => lock.release(), minutes * 60 * 1000);
  });
}

tryKeepScreenAlive(10);

이 예제는 사용자가 체크박스를 클릭하여 스크린 깨우기 잠금을 요청할 수 있게 하며, 깨우기 잠금 상태가 변경되는 경우 체크박스의 선택 상태를 업데이트합니다:

예시 2 
const checkbox = document.createElement("input");
checkbox.setAttribute("type", "checkbox");
document.body.appendChild(checkbox);

const sentinel = await navigator.wakeLock.request("screen");
checkbox.checked = !sentinel.released;
sentinel.onrelease = () => checkbox.checked = !sentinel.released;

이 예제에서는 서로 다른 두 개의 깨우기 잠금 요청을 생성하고 독립적으로 해제합니다:

예시 3 
let lock1 = await navigator.wakeLock.request("screen");
let lock2 = await navigator.wakeLock.request("screen");

lock1.release();
lock2.release();

14. 적합성

비규범으로 표시된 섹션뿐 아니라, 이 명세의 모든 저작 지침, 다이어그램, 예제, 참고는 비규범입니다. 그 외 이 명세의 모든 내용은 규범입니다.

이 문서에서 MAY, MUST, MUST NOT, RECOMMENDED 키워드는 여기에서와 같이 모두 대문자로 나타날 때에만 BCP 14 [RFC2119] [RFC8174]에 따라 해석되어야 합니다.

이 명세는 단일 제품(즉, 이 명세에 포함된 인터페이스를 구현하는 사용자 에이전트)에 대한 적합성 기준을 정의합니다.

A. 감사의 글

이 섹션은 규범적이지 않습니다.

본 작업에 기여해 주신 Mounir Lamouri, Sergey Konstantinov, Matvey Larionov, Dominique Hazael-Massieux, Domenic Denicola, Thomas Steiner, Anne van Kesteren께 진심으로 감사드립니다.

B. 변경 사항

이 섹션은 규범적이지 않습니다.

이 섹션은 이전 발행 이후의 변경 사항을 문서화합니다.

B.1 2017년 12월 14일 CR 이후 변경 사항

C. 색인

C.1 이 명세에서 정의된 용어

C.2 참조로 정의된 용어

D. IDL 색인

WebIDL[SecureContext]
partial interface Navigator {
  [SameObject] readonly attribute WakeLock wakeLock;
};

[SecureContext, Exposed=(Window)]
interface WakeLock {
  Promise<WakeLockSentinel> request(optional WakeLockType type = "screen");
};

[SecureContext, Exposed=(Window)]
interface WakeLockSentinel : EventTarget {
  readonly attribute boolean released;
  readonly attribute WakeLockType type;
  Promise<undefined> release();
  attribute EventHandler onrelease;
};

enum WakeLockType { "screen" };

E. 참고 문헌

E.1 규범적 참고 문헌

[dom]
DOM Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://dom.spec.whatwg.org/
[ECMASCRIPT]
ECMAScript Language Specification. Ecma International. URL: https://tc39.es/ecma262/multipage/
[html]
HTML Standard. Anne van Kesteren; Domenic Denicola; Dominic Farolino; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[infra]
Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/
[PERMISSIONS]
Permissions. Marcos Caceres; Mike Taylor. W3C. 2024년 3월 19일. W3C Working Draft. URL: https://www.w3.org/TR/permissions/
[PERMISSIONS-POLICY]
Permissions Policy. Ian Clelland. W3C. 2024년 9월 25일. W3C Working Draft. URL: https://www.w3.org/TR/permissions-policy-1/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. 1997년 3월. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. 2017년 5월. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
[WEBIDL]
Web IDL Standard. Edgar Chen; Timothy Gu. WHATWG. Living Standard. URL: https://webidl.spec.whatwg.org/

E.2 참고용 참고 문헌

[wake-lock-use-cases]
Wake Lock: Use cases. Marcos Caceres; Natasha Rooney; Dominique Hazaël-Massieux. W3C. 2014년 8월 14일. W3C Working Group Note. URL: https://www.w3.org/TR/wake-lock-use-cases/