푸시 API

애플리케이션 서버는 웹 애플리케이션의 서버 측 구성 요소를 의미합니다.

푸시 메시지는 애플리케이션 서버에서 웹 애플리케이션으로 전송되는 데이터입니다.

푸시 메시지는 해당 메시지가 제출된 활성 워커와 연결된 푸시 구독에 전달됩니다. 서비스 워커가 현재 실행 중이 아니면, 전달을 위해 워커가 시작됩니다.

선언적 푸시 메시지는 푸시 메시지이며, 데이터가 사용자 에이전트가 이해할 수 있는 JSON 문서입니다. 사용자 에이전트는 각 수신되는 푸시 메시지를 기회적으로 파싱하여, 선언적 푸시 메시지인지 선언적 푸시 메시지 파서를 통해 판단합니다.

선언적 푸시 메시지는 서비스 워커의 개입 없이 알림을 생성하고 표시할 수 있습니다. 그럼에도 불구하고, 애플리케이션 서버가 원하면 서비스 워커가 개입할 수 있습니다. 이러한 경우, 푸시 메시지의 선언적 특성은 예를 들어 저장소 압박으로 서비스 워커가 제거된 경우 백업 역할을 합니다. 또한 알림 데이터를 전달하는 보다 객체 지향적인 방법을 제공합니다.

{
  "web_push": 8030,
  "notification": {
    "title": "Ada emailed ‘London’",
    "lang": "en-US",
    "dir": "ltr",
    "body": "Did you hear about the tube strikes?",
    "navigate": "https://email.example/message/12"
  }
}

푸시 구독은 웹 애플리케이션을 대신하여 사용자 에이전트와 푸시 서비스 사이에 설정되는 메시지 전달 컨텍스트입니다.

푸시 구독에는 scope가 연관되어 있습니다. 이는 URL입니다.

푸시 구독은 scope의 path가 리스트이며 크기가 1이고, scope의 path[0]가 빈 문자열일 때 window-accessible scope를 가진 것으로 간주됩니다.

푸시 구독에는 푸시 엔드포인트가 연관되어 있습니다. 이는 반드시 푸시 서비스에서 노출되는 절대 URL이어야 하며, 애플리케이션 서버가 푸시 메시지를 전송할 수 있는 곳입니다. 푸시 엔드포인트는 반드시 푸시 구독을 고유하게 식별해야 합니다.

푸시 구독은 가질 수 있습니다 구독 만료 시간이 연관되어 있습니다. 설정된 경우, 이 값은 반드시 1970년 1월 1일 00:00:00 UTC부터 밀리초로 구독이 비활성화되는 시점을 나타내야 합니다. 사용자 에이전트는 가능하면 구독이 만료되기 전에 푸시 구독을 갱신해야 합니다.

푸시 구독에는 [RFC8291]에 따라 P-256 ECDH 키 페어와 인증 시크릿에 대한 내부 슬롯이 있습니다. 이러한 슬롯은 푸시 구독을 생성할 때 반드시 채워져야 합니다.

사용자 에이전트가 어떠한 이유로든 푸시 구독의 키를 변경해야 하고, 푸시 구독의 연관된 서비스 워커 등록이 null이 아니면, 반드시 푸시 구독을 갱신해야 합니다.

푸시 구독 생성을 하려면, PushSubscriptionOptionsInit optionsDictionary가 주어졌을 때:

1. subscription을 새로운 PushSubscription으로 생성합니다.
2. options를 새롭게 생성된 PushSubscriptionOptions 객체로 만들고, optionsDictionary의 해당 멤버와 값으로 초기화합니다.
3. subscription의 options 속성을 options로 설정합니다.
4. 새로운 P-256 ECDH 키 페어를 생성합니다 [ANSI-X9-62]. 개인 키는 subscription의 내부 슬롯에 저장합니다. 이 값은 애플리케이션에 노출되어서는 안 됩니다. 공개 키도 내부 슬롯에 저장되며, getKey() 메서드에 "p256dh"를 인자로 넘겨 호출하여 가져올 수 있습니다.
5. 새로운 인증 시크릿(옥텟 시퀀스)을 생성합니다. 이는 [RFC8291]에 정의된 방식입니다. 인증 시크릿은 subscription의 내부 슬롯에 저장합니다. 이 키는 getKey() 메서드에 "auth"를 인자로 넘겨 호출하여 가져올 수 있습니다.
6. 새로운 푸시 구독을 요청합니다. options의 applicationServerKey 속성이 설정되어 있다면 포함합니다. 예외가 발생하면 예외를 다시 던집니다.
7. 푸시 구독 요청이 성공적으로 완료되면:
   1. subscription의 endpoint 속성을 푸시 구독의 푸시 엔드포인트로 설정합니다.
   2. 푸시 구독에서 제공된 경우, subscription의 expirationTime을 설정합니다.
8. subscription을 반환합니다.

푸시 서비스라는 용어는 애플리케이션 서버가 웹 애플리케이션에 푸시 메시지를 보낼 수 있게 하는 시스템을 의미합니다. 푸시 서비스는 자신이 관리하는 푸시 엔드포인트 또는 엔드포인트를 해당 푸시 구독에 제공합니다.

사용자 에이전트는 푸시 서비스에 연결하여 푸시 구독을 생성합니다. 사용자 에이전트는 선택적으로 사용 가능한 푸시 서비스의 선택을 제한할 수 있습니다. 그 이유는 서비스 가용성(특정 국가나 네트워크, 직장 환경 등에서 방화벽에 의해 서비스가 차단되는 경우 포함), 신뢰성, 배터리 수명에 미치는 영향, 특정 푸시 서비스로 메타데이터를 유도하거나 회피하는 계약 등 성능 관련 우려가 있을 수 있습니다.

Push API는 강력한 기능이며, 이름은 "push"로 식별됩니다.

Permissions 명세와의 통합을 위해, 이 명세에서는 PushPermissionDescriptor permission descriptor type을 정의합니다.

WebIDLdictionary PushPermissionDescriptor : PermissionDescriptor {
  boolean userVisibleOnly = false;
};

userVisibleOnly는 userVisibleOnly와 동일한 의미를 가집니다.

{name: "push", userVisibleOnly: false}는 더 강력한 권한이며, {name: "push", userVisibleOnly: true}보다 우선합니다.

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

1. promise에 새로운 promise를 할당합니다.
2. global에 this의 관련 글로벌 객체를 할당합니다.
3. scope를 null로 설정합니다.
4. registration을 null로 설정합니다.
5. 만약 this의 서비스 워커 등록이 null이라면:
   1. scope를 기본 URL 파서로 "/"와 global의 연관 Document의 URL을 넘겨 실행한 결과로 설정합니다.
6. 그 외의 경우:
   1. Assert: this의 서비스 워커 등록은 서비스 워커 등록입니다.
   2. registration을 this의 서비스 워커 등록으로 설정합니다.
7. 다음 단계들을 병렬로 실행합니다:
   Note: 사용자 에이전트마다 검증 순서가 다를 수 있음
   1. 만약 scope가 실패이거나, URL의 scheme이 "https"가 아니라면, 글로벌 태스크를 큐에 넣어 promise를 reject하고 "NotAllowedError" DOMException을 반환합니다.
   2. 만약 options 인자의 userVisibleOnly 값이 false이고, 사용자 에이전트가 반드시 true여야 한다면, 글로벌 태스크를 큐에 넣어 promise를 reject하고 "NotAllowedError" DOMException을 반환합니다.
   3. 만약 options 인자에 applicationServerKey 멤버에 non-null 값이 포함되어 있지 않고, 푸시 서비스가 이를 필요로 한다면, 글로벌 태스크를 큐에 넣어 promise를 reject하고 "NotSupportedError" DOMException을 반환합니다.
   4. 만약 options 인자에 applicationServerKey 속성에 non-null 값이 포함되어 있다면:
      1. 만약 options의 applicationServerKey 가 DOMString이라면, 그 값을 base64url로 디코딩한 옥텟 시퀀스의 ArrayBuffer로 설정합니다 [RFC7515].
      2. 디코딩에 실패하면, 글로벌 태스크를 큐에 넣어 promise를 reject하고 "InvalidCharacterError" DOMException을 반환하고 단계 종료.
      3. 반드시 options의 applicationServerKey 값이 P-256 곡선 상의 올바른 점이어야 합니다. 만약 값이 올바르지 않다면, 글로벌 태스크를 큐에 넣어 promise를 reject하고 "InvalidAccessError" DOMException을 반환하고 단계 종료.
   5. subscription을 null로 설정합니다.
   6. 만약 scope가 null이 아니라면:
      1. 만약 푸시 구독이 window-accessible scope를 가지고 있고, 그 scope가 equals scope라면, subscription을 해당 푸시 구독으로 설정합니다.
   7. 그 외의 경우:
      1. Assert: registration은 null이 아님.
      2. 만약 registration의 active worker가 null이면, 글로벌 태스크를 큐에 넣어 promise를 reject하고 "InvalidStateError" DOMException을 반환하고 단계 종료.
      3. 만약 registration의 연관된 푸시 구독이 null이 아니라면, subscription을 registration의 연관된 푸시 구독으로 설정합니다.
      4. scope를 registration의 scope URL로 설정합니다.
   8. permission에 "push" 사용 권한 요청 결과를 할당합니다.
   9. 만약 permission이 "denied"라면, 글로벌 태스크를 큐에 넣어 promise를 reject하고 "NotAllowedError" DOMException을 반환하고 단계 종료.
   10. 만약 subscription이 null이 아니라면:
       1. subscription에 오류가 있으면, 글로벌 태스크를 큐에 넣어 promise를 reject하고 "AbortError" DOMException을 반환하고 단계 종료.
       2. options 인자와 subscription의 options 속성을 비교합니다. BufferSource 값의 내용은 참조가 아닌 동등성으로 비교합니다.
       3. options의 어떤 속성이 subscription에 저장된 값과 다르다면, 글로벌 태스크를 큐에 넣어 promise를 reject하고 "InvalidStateError" DOMException을 반환하고 단계 종료.
       4. 글로벌 태스크를 큐에 넣어 promise를 resolve하고 subscription을 반환하고 단계 종료.
   11. Assert: subscription이 null이고 scope는 URL입니다.
   12. subscription을 푸시 구독 생성 결과로 설정합니다. 구독 생성 중 exception이 발생하면 글로벌 태스크를 큐에 넣어 promise를 reject하고 해당 exception을 반환하고 단계 종료.
   13. subscription의 scope를 scope로 설정합니다.
   14. 글로벌 태스크를 큐에 넣어 promise를 resolve하고 PushSubscription을 반환하고 단계 종료.
8. promise를 반환합니다.

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

1. promise에 새로운 promise를 할당합니다.
2. global에 this의 관련 글로벌 객체를 할당합니다.
3. windowScope를 null로 설정합니다.
4. registration을 null로 설정합니다.
5. 만약 this의 서비스 워커 등록이 null이라면, windowScope를 기본 URL 파서로 "/"와 global의 연관 Document의 URL을 넘겨 실행한 결과로 설정합니다.
6. 그 외의 경우:
   1. Assert: this의 서비스 워커 등록은 서비스 워커 등록입니다.
   2. registration을 this의 서비스 워커 등록으로 설정합니다.
7. 다음 단계들을 병렬로 실행합니다:
   1. subscription을 null로 설정합니다.
   2. 만약 windowScope가 null이 아니라면:
      1. 푸시 구독 중 scope가 windowScope인 것이 있다면, subscription을 해당 푸시 구독으로 설정합니다.
   3. 그 외의 경우:
      1. Assert: registration은 null이 아님.
      2. 만약 registration의 연관된 푸시 구독이 null이 아니라면, subscription을 registration의 연관된 푸시 구독으로 설정합니다.
   4. 만약 subscription이 null이면, promise를 null로 resolve합니다.
   5. subscription에 오류가 있으면, promise를 "AbortError" 이름의 DOMException으로 reject하고 단계 종료.
   6. PushSubscription에 해당하는 subscription으로 promise를 resolve합니다.
8. promise를 반환합니다.

permissionState() 메서드는 호출 시 반드시 다음의 단계를 실행합니다:

1. promise에 새로운 promise를 할당합니다.
2. promise를 반환하고, 다음 단계는 비동기로 계속합니다.
3. descriptor에 PermissionDescriptor를 새로 생성하여 name을 "push"로 초기화합니다.
4. state에 descriptor의 permission state를 할당합니다.
5. promise를 state로 resolve합니다.

푸시 서비스를 사용할 권한은 영속적일 수 있으며, 유효한 권한이 있으면 이후 구독에 대해 다시 확인할 필요가 없습니다.

권한이 필요하다면 반드시 subscribe() 메서드를 호출하여 요청해야 합니다.

WebIDL[Exposed=(Window,Worker), SecureContext]
interface PushSubscriptionOptions {
  readonly attribute boolean userVisibleOnly;
  [SameObject] readonly attribute ArrayBuffer? applicationServerKey;
};

userVisibleOnly 속성은 get 시 초기화된 값을 반환합니다.

applicationServerKey 속성은 get 시 초기화된 값을 반환합니다.

applicationServerKey 값이 존재할 경우 반드시 P-256 타원 곡선 [DSS]의 점을 포함해야 하며, [ANSI-X9-62] Annex A(즉, 0x04로 시작하는 65바이트, 비압축 형태)로 인코딩되어야 합니다. DOMString으로 제공되는 경우 반드시 base64url 인코딩 [RFC7515]을 사용해야 합니다.

사용자 에이전트는 푸시 서비스가 운영상 필요로 한다면 applicationServerKey 가 존재하지 않을 때 구독 시도를 거부할 수 있습니다.

applicationServerKey 값은 반드시 메시지 암호화에 사용되는 값과 달라야 합니다 [RFC8291].

WebIDLdictionary PushSubscriptionOptionsInit {
  boolean userVisibleOnly = false;
  (BufferSource or DOMString)? applicationServerKey = null;
};

userVisibleOnly 멤버가 true로 설정된 경우, 해당 푸시 구독은 사용자에게 가시적으로 효과가 나타나는 푸시 메시지(예: 웹 알림 표시)만을 위해 사용됨을 나타냅니다. [NOTIFICATIONS]

PushSubscriptionOptionsInit는 푸시 구독과 연관된 추가 옵션을 나타냅니다. 사용자 에이전트는 사용자에게 명시적 권한을 요청할 때 이러한 옵션을 고려할 수 있습니다. 옵션이 고려되면, 사용자 에이전트는 해당 옵션을 수신되는 푸시 메시지에 반드시 적용해야 합니다.

이러한 옵션은 선택사항이며, 사용자 에이전트는 일부 옵션만 지원할 수 있습니다. 사용자 에이전트는 지원하지 않는 옵션을 노출해서는 안 됩니다.

한 번 설정된 푸시 구독의 옵션은 변경할 수 없습니다. 기존 푸시 구독은 unsubscribe를 통해 해지한 뒤, 새로운 옵션으로 푸시 구독을 만들 수 있습니다.

applicationServerKey 멤버는 사용자 에이전트가 푸시 서비스와 푸시 구독을 설정할 때 사용됩니다. applicationServerKey 옵션에는 애플리케이션 서버용 타원 곡선 공개키가 포함되어 있습니다. 이 키는 애플리케이션 서버가 푸시 구독에 푸시 메시지를 전송할 때 자신을 인증하기 위해 사용합니다 ([RFC8292]에 정의됨). 푸시 서비스는 해당 개인키로 인증 토큰을 생성하지 않은 푸시 메시지를 모두 거부합니다.

푸시 메시지 암호화에 사용되는 암호화 키는 getKey() 메서드 또는 PushSubscription의 직렬화기를 통해 웹 애플리케이션에 제공됩니다. 각 키는 PushEncryptionKeyName 열거형의 값으로 이름이 지정됩니다.

WebIDLenum PushEncryptionKeyName {
  "p256dh",
  "auth"
};

p256dh 값은 [RFC8291]에 기술된 P-256 ECDH 디피-헬만 공개키를 가져오는 데 사용됩니다.

auth 값은 [RFC8291]에 기술된 인증 시크릿을 가져오는 데 사용됩니다.

Service Worker 명세는 ServiceWorkerGlobalScope 인터페이스를 정의합니다 [SERVICE-WORKERS] 이 명세는 해당 인터페이스를 확장합니다.

WebIDL[Exposed=ServiceWorker, SecureContext]
partial interface ServiceWorkerGlobalScope {
  attribute EventHandler onpush;
  attribute EventHandler onpushsubscriptionchange;
};

onpush 속성은 이벤트 핸들러 IDL 속성이며, 해당 이벤트 핸들러 이벤트 타입은 "push"입니다. "push" 이벤트는 푸시 메시지가 푸시 구독에 수신되었음을 나타냅니다.

onpushsubscriptionchange 속성은 이벤트 핸들러 IDL 속성이며, 해당 이벤트 핸들러 이벤트 타입은 "pushsubscriptionchange"입니다.

WebIDL[Exposed=ServiceWorker, SecureContext]
interface PushEvent : ExtendableEvent {
  constructor(DOMString type, optional PushEventInit eventInitDict = {});
  readonly attribute PushMessageData? data;
  readonly attribute Notification? notification;
};

dictionary PushEventInit : ExtendableEventInit {
  PushMessageDataInit? data = null;
  Notification? notification = null;
};

typedef (BufferSource or USVString) PushMessageDataInit;

PushEvent 인터페이스 또는 해당 인터페이스를 상속하는 인터페이스의 constructor가 호출될 때, 통상적인 이벤트 생성 단계에 다음 단계를 추가합니다:

1. eventInitDict의 data 멤버가 없으면, 이벤트의 data 속성에 null을 할당하고 이 단계를 종료합니다.
2. b를 eventInitDict의 "data" 멤버에서 바이트 시퀀스를 추출한 결과로 설정합니다.
3. 이벤트의 data 속성에 PushMessageData 인스턴스를 새로 생성하여, bytes를 b로 할당합니다.

data 속성은 초기화된 값을 반환해야 합니다.

notification 속성은 초기화된 값을 반환해야 합니다.

사용자 에이전트가 푸시 서비스로부터 푸시 메시지를 받으면, 다음 단계를 반드시 실행해야 합니다.

1. subscription을 푸시 메시지에 해당하는 활성 푸시 구독이라고 합시다.

2. registration을 subscription의 연결된 서비스 워커 등록이라고 합시다.

3. bytes를 null로 둡니다.

4. 만약 푸시 메시지가 페이로드를 포함한다면:

   1. subscription과 연결된 키 쌍의 개인 키와 [RFC8291]에 설명된 프로세스를 사용하여 푸시 메시지의 페이로드를 해독합니다. 결과 바이트 시퀀스로 bytes를 설정합니다.

   2. 어떤 이유로든 푸시 메시지 페이로드를 해독할 수 없다면, 푸시 메시지를 승인하고 이 단계를 중단합니다.

      Note

      push 이벤트는 푸시 구독과 연결된 키 쌍을 사용하여 성공적으로 해독되지 않은 푸시 메시지에 대해 발생하지 않습니다.

5. 만약 bytes가 null이 아니라면:

   1. baseURL을 subscription의 범위라고 합시다.

   2. origin을 baseURL의 origin이라고 합시다.

   3. fallbackTimestamp을 현재 Coarsened Wall Time이라고 합시다.

   4. declarativeResult를 bytes, origin, baseURL, 그리고 fallbackTimestamp이 주어진 선언적 푸시 메시지 파서를 실행한 결과라고 합시다.

   5. 만약 declarativeResult가 실패가 아니라면:

      1. notification을 declarativeResult의 알림이라고 합시다.

      2. notification의 서비스 워커 등록을 registration으로 설정합니다.

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

      4. 만약 declarativeResult의 mutable이 true이고 registration이 null이 아니라면:

         1. result를 registration, null, 그리고 notification을 나타내는 새로운 Notification 객체가 주어진 푸시 이벤트 발생의 결과라고 합시다.

         2. 만약 result가 실패가 아니라면, notificationShown을 result의 알림 표시 여부로 설정합니다.

      5. 만약 notificationShown이 false라면, notification이 주어진 알림 표시 단계를 실행합니다.

      6. 푸시 메시지를 승인하고 이 단계를 중단합니다.

6. 만약 registration이 null이라면, 이 단계를 중단합니다.

7. data를 PushMessageData 객체로 둡니다. bytes는 bytes가 null이 아니면 bytes이고, 그렇지 않으면 null입니다.

8. result를 registration, data, 그리고 null이 주어진 푸시 이벤트 발생의 결과라고 합시다.

9. 만약 result가 실패이고 동일한 푸시 메시지가 서비스 워커 등록에 여러 번 실패적으로 전달되었다면, 푸시 메시지를 승인합니다.

10. 만약 result가 실패가 아니라면, 푸시 메시지를 승인합니다.

푸시 이벤트 결과는 튜플이며, notification shown(불리언)을 포함합니다.

푸시 이벤트 발행은 서비스 워커 등록 registration, PushMessageData 객체 또는 null data, notification 또는 null notification이 주어졌을 때 실행합니다. 실패 또는 푸시 이벤트 결과를 반환합니다.

1. notificationResult를 null로 설정합니다.

2. registration의 showNotification() 성공 여부를 false로 설정합니다.

3. "push"라는 기능적 이벤트 발행을 PushEvent 타입으로 registration에 대해 아래 속성으로 실행합니다:

   data

   data

   notification

   notification

   그리고 dispatchedEvent에 대해 다음 단계를 병렬로 실행합니다:

   1. dispatchedEvent의 extend lifetime promises가 모두 resolve될 때까지 대기합니다.

   2. 성공적으로 resolve되지 않으면 notificationResult를 실패로 설정합니다.

   3. 그렇지 않으면 notificationResult를 registration의 showNotification() 성공 여부로 설정합니다.

4. notificationResult가 null이 아닐 때까지 대기합니다.

5. notificationResult가 실패면, 실패를 반환합니다.

6. Assert: notificationResult는 불리언입니다.

7. (notificationResult)를 반환합니다.

푸시 메시지 인지는 pushMessage를 인자로 받으며, [RFC8030]에 따라 pushMessage의 수신을 인지합니다.

푸시 메시지 인지는 푸시 서비스가 메시지 전달을 중지하고 애플리케이션 서버에 성공을 보고하도록 합니다. 이렇게 하면 동일한 푸시 메시지가 푸시 서비스에 의해 무한 반복 전달되지 않습니다.

인지는 또한 애플리케이션 서버가 푸시 메시지가 성공적으로 전달되었다는 수신 확인을 잘못 받을 수 있음을 의미합니다. 따라서 여러 번 거부를 반드시 허용해야 하며, 최소 3회 시도를 허용하는 것이 좋습니다.

pushsubscriptionchange 이벤트는 푸시 구독에 대한 변경이 애플리케이션의 제어 외부에서 발생했음을 나타냅니다. 예를 들면 갱신, 철회, 손실 등이 해당됩니다.

"pushsubscriptionchange" 이벤트 발행은 서비스 워커 등록 registration, newSubscription, oldSubscription이 주어졌을 때, 사용자 에이전트가 "pushsubscriptionchange"라는 기능적 이벤트를 PushSubscriptionChangeEvent 타입으로 registration에 대해 아래 속성으로 발행합니다:

newSubscription

newSubscription

oldSubscription

oldSubscription

WebIDL[Exposed=ServiceWorker, SecureContext]
interface PushSubscriptionChangeEvent : ExtendableEvent {
  constructor(DOMString type, optional PushSubscriptionChangeEventInit eventInitDict = {});
  readonly attribute PushSubscription? newSubscription;
  readonly attribute PushSubscription? oldSubscription;
};

WebIDLdictionary PushSubscriptionChangeEventInit : ExtendableEventInit {
  PushSubscription newSubscription = null;
  PushSubscription oldSubscription = null;
};