알림 API

설정 객체로 알림 생성을 수행하려면, 문자열 title, NotificationOptions 딕셔너리 options, 그리고 환경 설정 객체 settings가 주어졌을 때:

1. origin을 settings의 출처로 합니다.

2. baseURL을 settings의 API 기준 URL로 합니다.

3. fallbackTimestamp를 Unix 기원부터 settings의 현재 벽시계 시각까지의 밀리초 수를 가장 가까운 정수로 반올림한 값으로 합니다.

4. 알림 생성의 결과를 반환합니다. 인수는 title, options, origin, baseURL, 그리고 fallbackTimestamp입니다.

알림 생성을 수행하려면, 문자열 title, NotificationOptions 딕셔너리 options, 출처 origin, URL baseURL, 그리고 EpochTimeStamp fallbackTimestamp가 주어졌을 때:

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

2. options["renotify"]가 true이고 options["tag"]가 빈 문자열이면, 예외를 던집니다: TypeError.

3. notification의 데이터를 다음으로 설정합니다: StructuredSerializeForStorage(options["data"]).

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

5. notification의 방향을 다음으로 설정합니다: options["dir"].

6. notification의 언어를 다음으로 설정합니다: options["lang"].

7. notification의 출처를 origin으로 설정합니다.

8. notification의 본문을 다음으로 설정합니다: options["body"].

9. options["navigate"]가 존재하면, 파싱을 baseURL을 사용하여 수행하고, 실패를 반환하지 않으면 notification의 탐색 URL을 반환값으로 설정합니다. (그렇지 않으면 notification의 탐색 URL은 null로 유지됩니다.)

10. notification의 태그를 다음으로 설정합니다: options["tag"].

11. options["image"]가 존재하면, 파싱을 baseURL을 사용하여 수행하고, 실패를 반환하지 않으면 notification의 이미지 URL을 반환값으로 설정합니다. (그렇지 않으면 notification의 이미지 URL은 설정되지 않습니다.)

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

13. options["badge"]가 존재하면, 파싱을 baseURL을 사용하여 수행하고, 실패를 반환하지 않으면 notification의 배지 URL을 반환값으로 설정합니다. (그렇지 않으면 notification의 배지 URL은 설정되지 않습니다.)

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

15. notification의 재알림 설정을 다음으로 설정합니다: options["renotify"].

16. notification의 무음 설정을 다음으로 설정합니다: options["silent"].

17. notification의 상호작용 요구 설정을 다음으로 설정합니다: options["requireInteraction"].

18. notification의 동작을 « »로 설정합니다.

19. entry 각각에 대해, options["actions"]에서, 다음 수까지 최대 동작 수가 지원되는 범위 내에서 수행합니다 (이를 초과하는 항목은 건너뜁니다):

    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의 동작에 추가합니다.

20. notification을 반환합니다.

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

1. permissionState를 다음의 결과로 합니다: 현재 권한 상태 가져오기. 이때 "notifications"를 사용합니다.

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

3. permissionState를 반환합니다.

가져오기 단계는, 알림 notification과 null 또는 환경 설정 객체 settings가 주어졌을 때, 다음과 같습니다:

1. 알림 플랫폼이 이미지를 지원하고 notification의 이미지 URL이 설정되어 있으면, 알림 리소스를 가져옵니다. 인수는 notification, notification의 이미지 URL, settings, 그리고 리소스 resource가 주어졌을 때 다음을 실행하는 단계입니다: notification의 이미지 리소스를 resource로 설정합니다.

2. 알림 플랫폼이 아이콘을 지원하고 notification의 아이콘 URL이 설정되어 있으면, 알림 리소스를 가져옵니다. 인수는 notification, notification의 아이콘 URL, settings, 그리고 리소스 resource가 주어졌을 때 다음을 실행하는 단계입니다: notification의 아이콘 리소스를 resource로 설정합니다.

3. 알림 플랫폼이 배지를 지원하고 notification의 배지 URL이 설정되어 있으면, 알림 리소스를 가져옵니다. 인수는 notification, notification의 배지 URL, settings, 그리고 리소스 resource가 주어졌을 때 다음을 실행하는 단계입니다: notification의 배지 리소스를 resource로 설정합니다.

4. 알림 플랫폼이 동작과 동작 아이콘을 지원하면, 각각에 대해, action을 notification의 동작에서 순회합니다: action의 아이콘 URL이 null이 아니면, 알림 리소스를 가져옵니다. 인수는 notification, action의 아이콘 URL, settings, 그리고 리소스 resource가 주어졌을 때 다음을 실행하는 단계입니다: action의 아이콘 리소스를 resource로 설정합니다.

알림 리소스 가져오기를 수행하려면, 알림 notification, URL url, null 또는 환경 설정 객체 settings, 그리고 알고리즘 processResource가 주어졌을 때, 이 알고리즘은 리소스를 인수로 받습니다:

1. request를 새로운 요청으로 합니다. 이 요청의 URL은 url이고, 클라이언트는 settings이며, 대상은 "image"이고, 모드는 "no-cors"이며, 자격 증명 모드는 "include"입니다.

2. settings가 null이면, request의 출처를 notification의 출처로, request의 리퍼러를 "no-referrer"로, 그리고 request의 서비스 워커 모드를 "none"으로 설정합니다.

   이는 사용자 에이전트가 선언적 푸시 메시지의 알림을 표시하는 경우입니다. 이러한 알림의 리소스를 가져올 때는 서비스 워커가 관여하지 않습니다. 선언적 푸시 메시지는 서비스 워커를 요구하지 않도록 설계되었기 때문입니다. [PUSH-API]

3. 가져오기를 request에 대해 수행합니다. 이때 useParallelQueue를 true로 설정하고, processResponseConsumeBody를 다음 단계로 설정합니다. 이 단계에는 응답 response와 null, 실패 또는 바이트 시퀀스 bytes가 주어집니다:

   1. bytes가 null 또는 실패이면, 반환합니다.

   2. bytes를 이미지로 디코딩하려고 시도합니다.

   3. 이미지 형식이 지원되면, 디코딩된 리소스를 인수로 processResource를 실행합니다.

   이 리소스는 다음과 비슷한 방식으로 가져오려는 의도입니다: <img>. 다만 이는 추상화가 필요합니다.

알림 표시 단계는, 알림 notification과 null 또는 환경 설정 객체 settings가 주어졌을 때, 다음과 같습니다:

1. 가져오기 단계를 실행합니다. 인수는 notification과 settings입니다.

2. 모든 가져오기가 완료되고 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이면, 선택적으로 사용자 에이전트가 정의한 방식으로 최종 사용자에게 알립니다 (예: 소리 재생).

8. notification이 비지속 알림이면, 태스크를 큐에 넣습니다. 이 태스크는 이벤트를 발생시킵니다. 이벤트 이름은 show이며, Notification 객체를 대상으로 합니다. 이 객체는 notification을 나타냅니다.

알림 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. 반환합니다.

6. notification이 지속 알림이면:

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

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

   3. 서비스 워커 알림 이벤트를 발생시킵니다. 이름은 "notificationclick"이며, 인수는 notification과 actionName입니다.

7. 그렇지 않으면, 태스크를 큐에 넣어 다음 단계를 실행합니다:

   1. intoFocus를 다음의 결과로 합니다: 이벤트 발생. 이벤트 이름은 click이며, Notification 객체를 대상으로 합니다. 이 객체는 notification을 나타내며, cancelable 속성을 true로 초기화합니다.

      사용자 에이전트는 focus()가 이벤트 리스너 내부에서 작동하도록 하는 것이 권장됩니다. 이는 이름이 click인 이벤트의 리스너입니다.

   2. intoFocus가 true이면, 사용자 에이전트는 notification과 관련된 브라우징 컨텍스트의 뷰포트에 포커스를 맞추는 것이 좋습니다.

웹 플랫폼 전반에서 "활성화"는 의도적으로 "클릭"이라는 부정확한 이름으로 불립니다.

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

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

2. 닫기 이벤트를 처리합니다. 인수는 notification입니다.

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

닫기 이벤트 처리를 수행하려면, 알림 notification이 주어졌을 때:

1. notification이 지속 알림이고 notification이 최종 사용자에 의해 닫혔으면, 서비스 워커 알림 이벤트를 발생시킵니다. 이름은 "notificationclose"이며, 인수는 notification입니다.

2. notification이 비지속 알림이면, 태스크를 큐에 넣습니다. 이 태스크는 이벤트를 발생시킵니다. 이벤트 이름은 close이며, Notification 객체를 대상으로 합니다. 이 객체는 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;
  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;
  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.

2. options["actions"]가 비어 있지 않으면, 예외를 던집니다: TypeError.

   동작은 지속 알림에서만 지원됩니다.

3. notification을 다음의 결과로 합니다: 설정 객체로 알림 생성. 인수는 title, options, 그리고 this의 관련 설정 객체입니다.

4. this를 notification과 연결합니다.

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

   1. 알림 권한 상태 가져오기의 결과가 "granted"가 아니면, 태스크를 큐에 넣어 이벤트를 발생시킵니다. 이벤트 이름은 error이며, 대상은 this입니다. 그리고 이 단계를 중단합니다.

   2. 알림 표시 단계를 실행합니다. 인수는 notification과 this의 관련 설정 객체입니다.

정적 permission 게터의 단계는 알림 권한 상태 가져오기의 결과를 반환하는 것입니다.

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

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

1. global을 현재 전역 객체로 합니다.

2. promise를 새로운 프로미스로 합니다. 이는 this의 관련 Realm에 속합니다.

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

   1. permissionState를 다음의 결과로 합니다: 사용 권한 요청. 요청 대상은 "notifications"입니다.

   2. 전역 태스크를 큐에 넣습니다. 사용하는 DOM 조작 태스크 소스에, 주어진 global을 사용하여 다음 단계를 실행하도록 합니다:

      1. deprecatedCallback이 주어졌으면, 호출합니다: deprecatedCallback을 « permissionState »와 "report"를 사용하여 호출합니다.

      2. 이행합니다: promise를 permissionState로 이행합니다.

4. promise를 반환합니다.

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

self.registration.showNotification("Alice에게서 온 새 메일", {
  actions: [{action: 'archive', title: "보관"}]
});

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

인스턴스 1                                   | 인스턴스 2
                                             |
// 인스턴스가 새 메일이 있음을 알아차립니다.       |
new Notification("John Doe에게서 온 새 메일",   |
                 { tag: 'message1' });       |
                                             |
                                             |  // 조금 뒤에, 이 인스턴스가
                                             |  // 새 메일이 있음을 알아차립니다.
                                             |  new Notification("John Doe에게서 온 새 메일",
                                             |                   { tag: 'message1' });

// Bob이 "안녕하세요"라고 말합니다
new Notification("Bob: 안녕하세요", { tag: 'chat_Bob' });

// Bob이 "오늘 오후에 시간 있으세요?"라고 말합니다
new Notification("Bob: 안녕하세요 / 오늘 오후에 시간 있으세요?", { 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를 새로운 프로미스로 합니다. 이는 this의 관련 Realm에 속합니다.

3. this의 활성 워커가 null이면, 거부합니다: promise를 TypeError로 거부하고, promise를 반환합니다.

4. notification을 다음의 결과로 합니다: 설정 객체로 알림 생성. 인수는 title, options, 그리고 this의 관련 설정 객체입니다. 이 과정에서 예외가 발생했으면, 거부합니다: promise를 해당 예외로 거부하고, promise를 반환합니다.

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

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

   1. 알림 권한 상태 가져오기의 결과가 "granted"가 아니면, 전역 태스크를 큐에 넣습니다. 사용하는 DOM 조작 태스크 소스에, 주어진 global을 사용하여 거부하도록 합니다: promise를 TypeError로 거부합니다. 그리고 이 단계를 중단합니다.

   2. 알림 표시 단계를 실행합니다. 인수는 notification과 this의 관련 설정 객체입니다.

   3. notification의 서비스 워커 등록의 다음 showNotification()의 성공적인 호출 여부를 true로 설정합니다.

   4. 전역 태스크를 큐에 넣습니다. 사용하는 DOM 조작 태스크 소스에, 주어진 global을 사용하여 이행하도록 합니다: promise를 undefined로 이행합니다.

7. promise를 반환합니다.

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

1. global을 this의 관련 전역 객체로 합니다.

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

3. origin을 this의 관련 설정 객체의 출처로 합니다.

4. promise를 새로운 프로미스로 합니다. 이는 realm에 속합니다.

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

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

   2. notifications를 목록으로 합니다. 이 목록에는 모든 알림 중 다음 조건을 충족하는 알림이 포함됩니다: 알림 목록에 있으며, 그 출처가 동일 출처로서 origin과 같고, 그 서비스 워커 등록이 this이며, 그 태그는, tag가 빈 문자열이 아니면, tag와 같아야 합니다.

   3. 전역 태스크를 큐에 넣습니다. 사용하는 DOM 조작 태스크 소스에, 주어진 global을 사용하여 다음 단계를 실행하도록 합니다:

      1. objects를 목록으로 합니다.

      2. 각각에 대해, 알림을 notifications에서 생성 순서대로 순회하며, 새로운 Notification 객체를 realm으로 생성합니다. 이 객체는 알림을 나타내며, 이를 추가합니다: objects에 추가합니다.

      3. 이행합니다: promise를 objects로 이행합니다.

6. promise를 반환합니다.

이 메서드는 0개 이상의 새로운 Notification 객체를 반환하며, 이 객체들은 동일한 기반 알림을 나타낼 수 있습니다. 이는 Notification 객체 중 이미 존재하는 객체가 나타내는 알림과 같을 수 있다는 뜻입니다.

서비스 워커 알림 이벤트 발생을 수행하려면, 이름은 name이며, 알림 notification과 선택적 문자열 action이 주어졌을 때 (기본값은 빈 문자열): 기능 이벤트 발생을 실행합니다. 인수는 name, NotificationEvent, notification의 서비스 워커 등록, 그리고 다음 초기화입니다:

notification

새로운 Notification 객체로, notification을 나타냅니다.

action

action

notification 게터의 단계는 해당 속성을 초기화할 때 사용한 값을 반환하는 것입니다.

action 게터의 단계는 해당 속성을 초기화할 때 사용한 값을 반환하는 것입니다.