Copyright © 2023 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.
이 명세는 설치된 웹 애플리케이션이 애플리케이션 배지를 설정할 수 있는 API를 정의합니다. 배지는 일반적으로 기기의 홈 화면이나 애플리케이션 도크에서 애플리케이션 아이콘과 함께 표시됩니다.
이 섹션은 문서가 발행될 당시의 상태를 설명합니다. 현재 W3C 발행물 목록과 이 기술 보고서의 최신 개정판은 W3C 기술 보고서 색인 https://www.w3.org/TR/ 에서 확인할 수 있습니다.
이 문서는 개발 중입니다.
이 문서는 웹 애플리케이션 워킹 그룹에서 Working Draft로 권고안 트랙을 통해 발행되었습니다.
Working Draft로 발행되었다고 해서 W3C 및 회원들의 승인을 의미하지는 않습니다.
이 문서는 초안이며 언제든지 다른 문서에 의해 업데이트, 대체 또는 폐기될 수 있습니다. 진행 중인 작업 외에는 인용에 부적합합니다.
이 문서는 W3C 특허 정책에 따라 운영되는 그룹에서 작성되었습니다. W3C는 해당 그룹 산출물과 관련해 공개 특허 공시 목록을 유지하며, 해당 페이지에는 특허 공시 방법도 안내되어 있습니다. 특정 특허가 필수 청구항을 포함한다고 믿는 사람이 있다면 W3C 특허 정책 6항에 따라 정보를 공개해야 합니다.
이 문서는 2021년 11월 2일 W3C 프로세스 문서에 따라 관리됩니다.
이 섹션은 규범적이지 않습니다.
async function updateMailBadge() {
// API 지원 여부 확인
if (!navigator.setAppBadge) return;
const unreadCount = await getUnreadMailCount();
// 앱 배지 설정 시도
try {
await navigator.setAppBadge(unreadCount);
} catch (e) {
// 배지 미지원 또는 사용자가 배지 설정을 차단함
}
}배지는 운영체제의 애플리케이션 아이콘에 나타날 수 있습니다. 동일 애플리케이션 내에서 여러 번 API 호출로 설정 또는 해제가 이루어지면, 가장 최근의 호출이 적용되며 애플리케이션이 종료된 후에도 계속 보일 수 있습니다.
async function showPlayerTurn(playerTurnId) {
if (playerTurnId === localPlayerId)
await navigator.setAppBadge();
else
await navigator.clearAppBadge();
}
일부 운영체제에서는 배지 설정 시
사용자 권한이 필요할 수 있습니다. 이 경우 개발자는 "notifications" 권한 상태를 먼저
확인한 후 배지 설정을 해야 합니다. 권한이 부여되지 않았다면, 개발자는
Notification.requestPermission()을
통해 권한을 요청해야 합니다.
async function checkPermission() {
permission = await navigator.permissions.query({
name: "notifications",
});
const button = document.getElementById("permission-button");
if (permission.state === "prompt") {
// 사용자에게 권한 요청 안내
button.hidden = false;
button.addEventListener("click", async () => {
await Notification.requestPermission();
checkPermission();
}, { once: true });
return;
}
button.hidden = true;
}배지는 설치된 웹 애플리케이션이 사용자의 주의를 필요로 하는 새로운 활동이나, 읽지 않은 수와 같은 소량의 정보를 알리기 위한 메커니즘입니다.
배지는 다음 중 하나의 값을 가질 수 있습니다:
0보다 큰 숫자 값임을 나타냅니다.
설치된 웹 애플리케이션은 배지를 가지고 있으며, 이는 "nothing"으로 초기화됩니다.
사용자 에이전트는 MAY (재)설정된 애플리케이션의 배지를 "nothing"으로 임의로 변경할 수 있습니다 (예: 시스템 규칙에 따름).
애플리케이션의 배지가 설정되면, 사용자 에이전트 또는 운영체제는 SHOULD 애플리케이션의 배지를 운영체제에서 애플리케이션을 대표하는 아이콘과 함께 표시해야 합니다 (예: 기기 홈 화면의 아이콘 위에 작은 오버레이로 표시).
사용자 에이전트는 MAY 사용자의 명시적 권한을 받아야 배지 설정이 가능합니다. 이런 권한이 필요할 경우, SHOULD "notifications" 권한과 연결해야 합니다.
배지 값이 "flag"로 설정된 경우, 사용자 에이전트 또는 운영체제는 SHOULD 특정하지 않은 표시(예: 색상 원)를 보여야 합니다.
배지 값이 "nothing"으로 설정되면, 사용자 에이전트 또는 운영체제는 SHOULD 배지 해제를 하여 더 이상 표시하지 않아야 합니다.
플랫폼 객체 context의 애플리케이션 배지 설정을 선택적 unsigned long long
contents 값으로 설정하려면:
Window
객체라면:
Document로 설정한다.
InvalidStateError"
DOMException을 반환한다.
SecurityError"로 이
알고리즘을 종료한다.
granted"가
아니라면,
글로벌
태스크를 큐잉하여 사용자
상호작용 태스크 소스를 global에 주고,
promise를 reject시키고,
NotAllowedError로
이 알고리즘을 종료한다.
undefined를 반환한다.
이 API는 설계상 쓰기 전용입니다. 사이트가 이전에 설정한 배지 값을 다시 읽어올 수 있는 방법은 없으므로, 애플리케이션 배지가 저장소나 지문 채취 메커니즘으로 사용될 수 없습니다.
사용자 에이전트 또는 운영체제는 MAY 배지 해제를 임의로 수행할 수 있으며, 시스템 규칙(예: 시스템 초기화 등)에 따라 동작할 수 있습니다.
제기자: @grorg (webkit-dev에서):
브라우저가 매우 빠르게 연속적으로 실행되는 여러 set/clear 작업(예: 깜빡이는 배지 생성)을 무시해야 한다는 명세 문구가 있으면 좋겠습니다. 예를 들어, 배지 작업은 1분에 한 번만 허용된다는 제한이 있을 수 있습니다.
이 부분은 UI와 관련이 있으므로 요구사항이 아닌 권고사항으로 처리하는 것이 좋겠습니다.
뭔가 "최종 일관성(eventual consistency)" 보장도 필요합니다. 즉, 마지막에 기록한 값이 최종적으로 사용자에게 표시된다는 보장입니다. 예를 들어, "3"을 설정하고 10초 후에 "12"를 설정했는데, 속도 제한 때문에 "12"가 반영되지 않아 사용자가 계속 "3"만 보는 상황을 막아야 합니다. 따라서 규칙은 "UI가 N초 이상 업데이트되지 않았다면 새 값으로 업데이트한다. 그렇지 않으면, 마지막 업데이트 이후 경과된 시간만큼 타이머를 설정해 N초 후 새 값으로 UI를 업데이트한다."와 같이 되어야 합니다.
이 섹션은 규범적이지 않습니다.
브라우저가 배지 표시를 제어하는 경우, 접근성 가이드라인을 정의할 수 있어야 합니다.
비규범적으로 표시된 섹션뿐 아니라, 저작 가이드라인, 도표, 예시, 주석도 모두 비규범적입니다. 이 명세의 그 외 모든 내용은 규범적입니다.
이 문서에서 MAY, MUST, SHOULD, SHOULD NOT이라는 용어는 BCP 14 [RFC2119] [RFC8174] 해당 용어가 본문처럼 모두 대문자로 표기된 경우에 한해, 그 의미로 해석해야 합니다.
Referenced in:
Referenced in: