알림 API

문자열 title, NotificationOptions 딕셔너리 options, 그리고 환경 설정 객체 settings으로 설정 객체로 알림 생성을 하려면:

1. origin을 settings의 오리진으로 설정합니다.

2. baseURL을 settings의 API 기본 URL로 설정합니다.

3. fallbackTimestamp를 Unix epoch부터 settings의 현재 실제 시간까지의 밀리초 수(가장 가까운 정수로 반올림)로 설정합니다.

4. title, options, origin, baseURL, fallbackTimestamp을 인자로 알림 생성의 결과를 반환합니다.

문자열 title, NotificationOptions 딕셔너리 options, origin origin, URL baseURL, EpochTimeStamp fallbackTimestamp로 알림 생성을 하려면:

1. notification을 새로운 알림으로 설정합니다.

2. options["silent"] 가 true이고 options["vibrate"] 존재하면, TypeError를 throw합니다.

3. options["renotify"] 가 true이고 options["tag"] 가 빈 문자열이면, TypeError를 throw합니다.

4. notification의 data를 StructuredSerializeForStorage(options["data"])로 설정합니다.

5. notification의 제목을 title로 설정합니다.

6. notification의 방향을 options["dir"]로 설정합니다.

7. notification의 언어를 options["lang"]로 설정합니다.

8. notification의 오리진을 origin으로 설정합니다.

9. notification의 본문을 options["body"]로 설정합니다.

10. options["navigate"] 존재하면, baseURL로 파싱하고, 실패가 아니면 notification의 네비게이션 URL을 그 반환값으로 설정합니다. (실패면 notification의 네비게이션 URL은 null로 남깁니다.)

11. notification의 태그를 options["tag"]로 설정합니다.

12. options["image"] 존재하면, baseURL로 파싱하고, 실패가 아니면 notification의 이미지 URL을 그 반환값으로 설정합니다. (실패면 notification의 이미지 URL은 설정하지 않습니다.)

13. options["icon"] 존재하면, baseURL로 파싱하고, 실패가 아니면 notification의 아이콘 URL을 그 반환값으로 설정합니다. (실패면 notification의 아이콘 URL은 설정하지 않습니다.)

14. options["badge"] 존재하면, baseURL로 파싱하고, 실패가 아니면 notification의 배지 URL을 그 반환값으로 설정합니다. (실패면 notification의 배지 URL은 설정하지 않습니다.)

15. options["vibrate"] 존재하면, 검증 및 정규화하고, notification의 진동 패턴을 그 반환값으로 설정합니다.

16. options["timestamp"] 존재하면, notification의 타임스탬프를 그 값으로 설정합니다. 그렇지 않으면 notification의 타임스탬프를 fallbackTimestamp로 설정합니다.

17. notification의 재알림 선호를 options["renotify"]로 설정합니다.

18. notification의 무음 선호를 options["silent"]로 설정합니다.

19. notification의 상호작용 요구 선호를 options["requireInteraction"]로 설정합니다.

20. notification의 액션을 « »로 설정합니다.

21. options["actions"]의 각 entry에 대해, 지원되는 최대 액션 수까지(초과 항목은 건너뜀):

    1. action을 새로운 알림 액션으로 설정합니다.

    2. action의 이름을 entry["action"]로 설정합니다.

    3. action의 제목을 entry["title"]로 설정합니다.

    4. entry["navigate"] 존재하면, baseURL로 파싱하고, 실패가 아니면 action의 네비게이션 URL을 그 반환값으로 설정합니다. (실패면 action의 네비게이션 URL은 null로 남깁니다.)

    5. entry["icon"] 존재하면, baseURL로 파싱하고, 실패가 아니면 action의 아이콘 URL을 그 반환값으로 설정합니다. (실패면 action의 아이콘 URL은 null로 남깁니다.)

    6. action을 notification의 액션에 추가합니다.

22. notification을 반환합니다.

알림 권한 상태 가져오기를 하려면 다음 단계를 실행합니다:

1. permissionState를 "notifications"로 현재 권한 상태 가져오기의 결과로 설정합니다.

2. permissionState가 "prompt"이면, "default"를 반환합니다.

3. permissionState를 반환합니다.

주어진 알림 notification에 대한 fetch 단계는 다음과 같습니다:

1. 알림 플랫폼이 이미지를 지원하면, fetch notification의 image URL을, image URL이 설정되어 있을 때 실행합니다.

   이 리소스는 <img>와 유사하게 fetch하는 것이 목적이지만, 추상화가 필요함.

   그리고 나서, 병렬로:

   1. response를 기다립니다.

   2. response의 internal response의 type이 "default"라면, 리소스를 이미지로 디코드 시도합니다.

   3. 이미지 포맷이 지원되면 notification의 이미지 리소스를 디코드된 리소스로 설정합니다. (지원되지 않으면 notification은 이미지 리소스를 가지지 않습니다.)

2. 알림 플랫폼이 아이콘을 지원하면, fetch notification의 icon URL을, icon URL 이 설정되어 있을 때 실행합니다.

   이 리소스는 <img>와 유사하게 fetch하는 것이 목적이지만, 추상화가 필요함.

   그리고 나서, 병렬로:

   1. response를 기다립니다.

   2. response의 internal response의 type이 "default"라면, 리소스를 이미지로 디코드 시도합니다.

   3. 이미지 포맷이 지원되면 notification의 아이콘 리소스를 디코드된 리소스로 설정합니다. (지원되지 않으면 notification은 아이콘 리소스를 가지지 않습니다.)

3. 알림 플랫폼이 배지를 지원하면, fetch notification의 badge URL을, badge URL이 설정되어 있을 때 실행합니다.

   이 리소스는 <img>와 유사하게 fetch하는 것이 목적이지만, 추상화가 필요함.

   그리고 나서, 병렬로:

   1. response를 기다립니다.

   2. response의 internal response의 type이 "default"라면, 리소스를 이미지로 디코드 시도합니다.

   3. 이미지 포맷이 지원되면 notification의 배지 리소스를 디코드된 리소스로 설정합니다. (지원되지 않으면 notification은 배지 리소스를 가지지 않습니다.)

4. 알림 플랫폼이 액션 및 액션 아이콘을 지원하면, notification의 액션 각각에 대해: 아이콘 URL이 null이 아니면 fetch action의 아이콘 URL을 실행합니다.

   이 리소스는 <img>와 유사하게 fetch하는 것이 목적이지만, 추상화가 필요함.

   그리고 나서, 병렬로:

   1. response를 기다립니다.

   2. response의 internal response의 type이 "default"라면, 리소스를 이미지로 디코드 시도합니다.

   3. 이미지 포맷이 지원되면 action의 아이콘 리소스를 디코드된 리소스로 설정합니다. (지원되지 않으면 action의 아이콘 리소스는 null로 남깁니다.)

주어진 알림 notification에 대한 알림 표시 단계는 다음과 같습니다:

1. notification에 대해 fetch 단계를 실행합니다.

2. 모든 fetch가 완료되고 notification의 이미지 리소스, 아이콘 리소스, 배지 리소스(있는 경우), 그리고 notification의 액션의 아이콘 리소스(있는 경우)가 설정될 때까지 기다립니다.

3. shown을 false로 설정합니다.

4. oldNotification을 알림 목록에서 태그가 빈 문자열이 아니고 notification의 태그와 같으며, 오리진이 notification의 오리진과 동일 출처인 알림으로 설정합니다(있으면), 없으면 null로 설정합니다.

5. oldNotification이 null이 아니면:

   1. oldNotification에 대해 닫기 이벤트 처리를 실행합니다.

   2. 알림 플랫폼이 교체를 지원하면:

      1. 알림 목록에서 oldNotification을 notification으로 교체합니다.

      2. shown을 true로 설정합니다.

      알림 플랫폼은 더 나은 사용자 경험을 위해 네이티브 교체를 지원하는 것이 강하게 권장됩니다.

   3. 그렇지 않으면 알림 목록에서 oldNotification을 제거합니다.

6. shown이 false이면:

   1. notification을 알림 목록에 추가합니다.

   2. 기기에서 notification을 표시합니다(예: 알림 플랫폼 API 호출).

7. shown이 false이거나 oldNotification이 null이 아니고, notification의 재알림 선호가 true이면, notification에 대해 알림 단계를 실행합니다.

8. notification이 비지속성 알림이면, 태스크 큐잉하여 Notification 객체(해당 notification을 나타냄)에 show 이벤트를 발생시킵니다.

최종 사용자가 알림 notification 또는 그 액션 중 하나를 활성화할 때, 해당 알림 플랫폼이 활성화를 지원한다고 가정하고, 사용자 에이전트는(별도 명시가 없으면) 다음 단계를 실행해야 합니다:

1. action을 null로 설정합니다.

2. 최종 사용자가 notification의 액션 중 하나를 활성화했다면, action을 해당 알림 액션으로 설정합니다.

3. navigationURL을 notification의 네비게이션 URL로 설정합니다.

4. action이 null이 아니면, navigationURL을 action의 네비게이션 URL로 설정합니다.

   이렇게 하면 알림 액션의 네비게이션 URL이 null일 때 click 이벤트로 넘어가도록 되어, 웹 개발자에게 더 많은 유연성을 제공합니다.

5. navigationURL이 null이 아니면:

   1. 다음 두 옵션 중 하나를 구현 정의 방식으로 선택합니다:

      • 사용자 에이전트의 최상위 탐색 가능 객체 집합 내 기존 최상위 탐색 가능 객체를 navigationURL로 탐색합니다.

      • navigationURL로 새 최상위 탐색 가능 객체 생성을 합니다.

      사용자 에이전트는 플랫폼 규칙을 따르는 것이 강력히 권장됩니다.

   2. Return.

6. notification이 지속성 알림이면:

   1. actionName을 빈 문자열로 설정합니다.

   2. action이 null이 아니면, actionName을 action의 이름으로 설정합니다.

   3. 서비스 워커 알림 이벤트 발행 "notificationclick"를 notification과 actionName을 넘겨 실행합니다.

7. 그 외에는, 태스크 큐잉하여 다음 단계를 실행합니다:

   1. intoFocus를 Notification 객체(해당 notification을 나타냄)에 click 이벤트를 발생시키는 결과로 설정하며, cancelable 속성을 true로 초기화합니다.

      사용자 에이전트는 focus() 를 이벤트 리스너 내에서 동작하도록 하는 것이 권장됩니다.

   2. intoFocus가 true이면, 사용자 에이전트는 notification의 관련 브라우징 컨텍스트 뷰포트를 포커스로 가져와야 합니다.

웹 플랫폼 전체에서 "activate"는 의도적으로 "click"으로 명명되어 있습니다.

주어진 알림 notification에 대한 닫기 단계는 다음과 같습니다:

1. 알림 목록이 notification을 포함하지 않으면 이 단계들을 중단합니다.

2. notification에 대해 닫기 이벤트 처리를 실행합니다.

3. 알림 목록에서 notification을 제거합니다.

알림 notification에 대해 닫기 이벤트 처리를 하려면:

1. notification이 지속성 알림이고 최종 사용자에 의해 닫혔다면, 서비스 워커 알림 이벤트 발행 "notificationclose"를 notification으로 실행합니다.

2. notification이 비지속성 알림이면, 태스크 큐잉하여 Notification 객체(해당 notification을 나타냄)에 close 이벤트를 발생시킵니다.

최종 사용자에게 주어진 알림 notification을 알릴 때 알림 단계는 다음과 같습니다:

1. notification의 진동 패턴(있는 경우)으로 진동 수행을 합니다.

[Exposed=(Window,Worker)]
interface Notification : EventTarget {
  constructor(DOMString title, optional NotificationOptions options = {});

  static readonly attribute NotificationPermission permission;
  [Exposed=Window] static Promise<NotificationPermission> requestPermission(optional NotificationPermissionCallback deprecatedCallback);

  static readonly attribute unsigned long maxActions;

  attribute EventHandler onclick;
  attribute EventHandler onshow;
  attribute EventHandler onerror;
  attribute EventHandler onclose;

  readonly attribute DOMString title;
  readonly attribute NotificationDirection dir;
  readonly attribute DOMString lang;
  readonly attribute DOMString body;
  readonly attribute USVString navigate;
  readonly attribute DOMString tag;
  readonly attribute USVString image;
  readonly attribute USVString icon;
  readonly attribute USVString badge;
  [SameObject] readonly attribute FrozenArray<unsigned long> vibrate;
  readonly attribute EpochTimeStamp timestamp;
  readonly attribute boolean renotify;
  readonly attribute boolean? silent;
  readonly attribute boolean requireInteraction;
  [SameObject] readonly attribute any data;
  [SameObject] readonly attribute FrozenArray<NotificationAction> actions;

  undefined close();
};

dictionary NotificationOptions {
  NotificationDirection dir = "auto";
  DOMString lang = "";
  DOMString body = "";
  USVString navigate;
  DOMString tag = "";
  USVString image;
  USVString icon;
  USVString badge;
  VibratePattern vibrate;
  EpochTimeStamp timestamp;
  boolean renotify = false;
  boolean? silent = null;
  boolean requireInteraction = false;
  any data = null;
  sequence<NotificationAction> actions = [];
};

enum NotificationPermission {
  "default",
  "denied",
  "granted"
};

enum NotificationDirection {
  "auto",
  "ltr",
  "rtl"
};

dictionary NotificationAction {
  required DOMString action;
  required DOMString title;
  USVString navigate;
  USVString icon;
};

callback NotificationPermissionCallback = undefined (NotificationPermission permission);

new Notification(title, options) 생성자 단계는 다음과 같습니다:

1. this의 관련 글로벌 객체가 ServiceWorkerGlobalScope 객체라면, TypeError를 throw합니다.

2. options["actions"] 가 비어 있지 않으면 TypeError를 throw합니다.

   액션은 지속성 알림에서만 지원됩니다.

3. notification을 title, options, this의 관련 설정 객체를 인자로 하여 설정 객체로 알림 생성의 결과로 설정합니다.

4. this를 notification과 연관시킵니다.

5. 병렬로 다음 단계를 실행합니다:

   1. 알림 권한 상태 가져오기의 결과가 "granted"가 아니면, 태스크 큐잉하여 error 이벤트 발생을 this에 실행하고 이 단계들을 중단합니다.

   2. notification에 대해 알림 표시 단계를 실행합니다.

정적 permission getter 단계는 알림 권한 상태 가져오기의 결과를 반환합니다.

const permission = await navigator.permissions.query({name: "notifications"});
if (permission.state === "granted") {
   // API를 사용할 권한이 있습니다…
}

정적 requestPermission(deprecatedCallback) 메서드 단계는 다음과 같습니다:

1. global을 현재 글로벌 객체로 설정합니다.

2. promise를 새로운 Promise로 this의 관련 Realm에서 생성합니다.

3. 병렬로 다음 단계를 실행합니다:

   1. permissionState를 사용 권한 요청하기 "notifications"의 결과로 설정합니다.

   2. 글로벌 태스크 큐잉을 DOM 조작 태스크 소스에서 global에 실행하여 다음 단계를 수행합니다:

      1. deprecatedCallback이 주어졌다면, 콜백 함수 호출 deprecatedCallback에 « permissionState », "report"를 전달하여 실행합니다.

      2. promise 해결을 promise와 permissionState로 실행합니다.

4. promise를 반환합니다.

var not = new Notification("Gebrünn Gebrünn by Paul Kalkbrenner", { icon: "newsong.svg", tag: "song" });
not.onclick = function() { displaySong(this); };

self.registration.showNotification("New mail from Alice", {
  actions: [{action: 'archive', title: "Archive"}]
});

self.addEventListener('notificationclick', function(event) {
  event.notification.close();
  if (event.action === 'archive') {
    silentlyArchiveEmail();
  } else {
    clients.openWindow("/inbox");
  }
}, false);

Instance 1                                   | Instance 2
                                             |
// Instance notices there is new mail.       |
new Notification("New mail from John Doe",   |
                 { tag: 'message1' });       |
                                             |
                                             |  // Slightly later, this instance notices
                                             |  // there is new mail.
                                             |  new Notification("New mail from John Doe",
                                             |                   { tag: 'message1' });

// Bob says "Hi"
new Notification("Bob: Hi", { tag: 'chat_Bob' });

// Bob says "Are you free this afternoon?"
new Notification("Bob: Hi / Are you free this afternoon?", { tag: 'chat_Bob' });

dictionary GetNotificationOptions {
  DOMString tag = "";
};

partial interface ServiceWorkerRegistration {
  Promise<undefined> showNotification(DOMString title, optional NotificationOptions options = {});
  Promise<sequence<Notification>> getNotifications(optional GetNotificationOptions filter = {});
};

[Exposed=ServiceWorker]
interface NotificationEvent : ExtendableEvent {
  constructor(DOMString type, NotificationEventInit eventInitDict);

  readonly attribute Notification notification;
  readonly attribute DOMString action;
};

dictionary NotificationEventInit : ExtendableEventInit {
  required Notification notification;
  DOMString action = "";
};

partial interface ServiceWorkerGlobalScope {
  attribute EventHandler onnotificationclick;
  attribute EventHandler onnotificationclose;
};

showNotification(title, options) 메서드 단계는 다음과 같습니다:

1. global을 this의 관련 글로벌 객체로 설정합니다.

2. promise를 새로운 Promise로 this의 관련 Realm에서 생성합니다.

3. this의 active worker가 null이면, promise를 TypeError로 reject하고 promise를 반환합니다.

4. notification을 title, options, this의 관련 설정 객체를 인자로 하여 설정 객체로 알림 생성의 결과로 설정합니다. 만약 이 과정에서 예외가 발생하면 promise를 해당 예외로 reject하고 promise를 반환합니다.

5. notification의 서비스 워커 등록을 this로 설정합니다.

6. 병렬로 다음 단계를 실행합니다:

   1. 알림 권한 상태 가져오기의 결과가 "granted"가 아니면, 글로벌 태스크 큐잉을 DOM 조작 태스크 소스에서 global에 실행하여 promise를 TypeError로 reject하고 이 단계들을 중단합니다.

   2. notification에 대해 알림 표시 단계를 실행합니다.

   3. notification의 서비스 워커 등록의 showNotification()이 성공적으로 호출된 적이 있는지 여부 를 true로 설정합니다.

   4. 글로벌 태스크 큐잉을 DOM 조작 태스크 소스에서 global에 실행하여 promise를 undefined로 resolve합니다.

7. promise를 반환합니다.

getNotifications(filter) 메서드 단계는 다음과 같습니다:

1. global을 this의 관련 글로벌 객체로 설정합니다.

2. realm을 this의 관련 Realm으로 설정합니다.

3. origin을 this의 관련 설정 객체의 오리진으로 설정합니다.

4. promise를 새로운 Promise로 realm에서 생성합니다.

5. 병렬로 다음 단계를 실행합니다:

   1. tag를 filter["tag"]로 설정합니다.

   2. notifications를 리스트로, 알림 목록 중 오리진이 origin과 동일 출처이고, 서비스 워커 등록이 this이며, 태그가 비어 있지 않다면 tag와 같은 알림만 포함하는 리스트로 설정합니다.

   3. 글로벌 태스크 큐잉을 DOM 조작 태스크 소스에서 global에 실행하여 다음 단계를 수행합니다:

      1. objects를 리스트로 설정합니다.

      2. 각 알림에 대해 notifications에서 생성 순서대로, realm을 사용해 해당 알림을 나타내는 Notification 객체를 새로 만들고 objects에 추가합니다.

      3. promise를 objects로 resolve합니다.

6. promise를 반환합니다.

이 메서드는 0개 이상의 Notification 객체를 반환하며, 이 객체들은 이미 존재하는 Notification 객체와 동일한 알림을 나타낼 수 있습니다.

서비스 워커 알림 이벤트 발행을 하기 위해 name라는 이름으로, 알림 notification 및 선택적 문자열 action(기본값은 빈 문자열)을 입력으로 받아, Fire Functional Event를 name, NotificationEvent, notification의 서비스 워커 등록, 그리고 다음 초기값을 넘겨 실행합니다.

notification

notification을 나타내는 새 Notification 객체

action

action

notification getter 단계는 초기화된 값을 반환하는 것입니다.

action getter 단계는 초기화된 값을 반환하는 것입니다.