Copyright © 2025 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.
이 명세서는 설치된 웹 애플리케이션이 애플리케이션 배지를 설정할 수 있는 API를 정의합니다. 애플리케이션 배지는 일반적으로 기기의 홈 화면이나 애플리케이션 독에서 애플리케이션 아이콘과 함께 표시됩니다.
이 섹션은 이 문서가 발행된 시점의 상태를 설명합니다. 현재 W3C 발행 문서 목록과 이 기술 보고서의 최신 개정판은 W3C 표준 및 초안 색인에서 확인할 수 있습니다.
이 문서는 작업 중인 초안입니다.
이 문서는 Web Applications Working Group에서 권고안 경로를 사용하여 워킹 드래프트로 발행되었습니다.
워킹 드래프트로 발행된다고 해서 W3C 및 회원의 승인을 의미하지는 않습니다.
이 문서는 초안 문서이며 언제든지 다른 문서에 의해 업데이트, 교체 또는 폐지될 수 있습니다. 진행 중인 작업 이외의 용도로 이 문서를 인용하는 것은 적절하지 않습니다.
이 문서는 W3C 특허 정책에 따라 운영되는 그룹에서 작성되었습니다. W3C는 공개 특허 공개 목록을 그룹의 결과물과 관련하여 유지합니다. 해당 페이지에는 특허 공개 방법에 대한 안내도 포함되어 있습니다. 특정 특허가 필수 청구항을 포함한다고 판단되는 경우, 해당 정보를 W3C 특허 정책 6절에 따라 공개해야 합니다.
이 문서는 2025년 8월 18일 W3C 프로세스 문서에 의해 관리됩니다.
이 섹션은 규범적이지 않습니다.
배지는 일부 사용자에게 알림 피로를 유발할 수 있습니다. 따라서 작성자는 사용자의 주의나 행동이 진정으로 필요한 상태에만 배지를 할당해야 하며, 마케팅이나 참여 유도 목적의 남용은 피해야 합니다.
산만함이나 인지 부하를 증가시키는 빠르게 변하는 값의 사용을 피하십시오.
배지를 인식하지 못하거나 시스템 차원에서 비활성화한 사용자를 지원하기 위해, 작성자는 동일한 상태를 애플리케이션 UI 내에서 접근 가능한 패턴(예: 명확하게 라벨링된 앱 내 상태 표시기)으로 제공하는 것이 권장됩니다.
이 섹션은 규범적이지 않습니다.
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;
}배지(badge)는 설치된 웹 애플리케이션이 사용자에게 주의가 필요할 수 있는 새로운 활동이 있음을 알리거나, 읽지 않은 횟수와 같은 적은 양의 정보를 나타내는 방법으로 사용됩니다.
배지(badge)는 다음 값(values) 중 하나를 가질 수 있습니다.
0보다 큰 값으로 설정됨을 나타냅니다.
설치된 웹 애플리케이션은 연관된 배지를 가지며, 초기값은 "nothing"입니다. 운영체제가 배지 값을 저장하고 관리하며, user agent는 OS와 배지 변경 사항을 전달하는 중개자의 역할을 합니다.
user agent는 MAY (재)설정할 수 있으며, 애플리케이션의 배지를 "nothing"으로 임의로 바꿀 수 있습니다(예: 시스템 관례에 따라).
애플리케이션의 배지가 설정되면, user agent 또는 운영체제는 SHOULD 애플리케이션의 배지를 사용자의 운영체제에서 주요 아이콘과 함께 표시해야 합니다(예: 기기 홈 화면에서 애플리케이션 아이콘 위에 작은 오버레이로).
user agent는 MAY 사용자에게 명시적 권한을 요구할 수 있으며, 배지를 설정할 때 필요합니다. user agent가 이러한 권한을 요구할 경우, SHOULD 권한 부여를 "notifications" 권한과 연결해야 합니다.
배지가 설정되어 "flag"인 경우, user agent 또는 운영체제는 SHOULD 일반적인 기호(예: 색깔이 있는 원)로 표시해야 합니다. 만약 플랫폼이 "flag" 배지를 표시하지 못하면, user agent는 SHOULD 배지의 존재를 나타낼 수 있는 가장 가까운 표현(예: 값 "1")으로 표시해야 하며, 배지를 완전히 제거해서는 안 됩니다.
배지의 값이 설정되어 "nothing"인 경우, user agent 또는 운영체제는 SHOULD 배지 제거를 통해 배지를 더 이상 표시하지 않아야 합니다.
배지가 설정되어 number인 경우, user agent 또는 운영체제는:
각 운영체제는 배지 표시 기능에 차이가 있습니다. 최종적인 표시 동작은 운영체제가 제어하며, 사용자 설정이나 시스템 관례에 의해 추가로 수정될 수 있습니다. 운영체제에 배지 정보를 전달할 때, user agent는 SHOULD 배지 요청의 의미적 의도를 보존해야 합니다:
플랫폼 객체 context의 애플리케이션 배지 설정을 선택적 unsigned long long
contents 값으로 수행하려면:
Window
객체라면:
Document로 한다.
InvalidStateError"
DOMException로 한다.
SecurityError" DOMException로 한다.
granted"가
아니라면,
글로벌
태스크 큐잉을 user
interaction task source에서
global에 대해 promise 거부를 NotAllowedError로
하고 이 알고리즘을 종료한다.
undefined로 한다.
이 API는 의도적으로 쓰기 전용입니다. 사이트가 이전에 설정한 배지 값을 읽어올 방법이 없으므로, 애플리케이션 배지를 저장소나 핑거프린팅 메커니즘으로 사용할 수 없습니다.
사용자 에이전트 또는 운영체제는 MAY 배지 지우기를 badge에 임의로 적용할 수 있으며, 시스템 규칙(예: 시스템 초기화 시)을 따를 수 있습니다.
사용자 에이전트는 MAY 배지 설정 또는 해제를 제한하여 산만한 애니메이션을 방지하고 리소스 사용을 줄일 수 있습니다. 그러나 사용자 에이전트는 SHOULD 일반적으로 속도 제한을 운영 체제에 맡겨야 하며, 운영 체제가 시스템 부하, 사용자 환경설정 및 접근성 고려 사항에 따라 적절하게 제한할 수 있는 더 좋은 위치에 있기 때문입니다.
애플리케이션 배지는 사용자의 주의가 필요할 수 있는 상태를 전달합니다. 배지는 종종 웹 콘텐츠 영역 외부(예: 도크의 앱 아이콘 등)에 표시되기 때문에, 사용자 에이전트는 해당 정보가 플랫폼의 접근성 기능과 사용자 환경설정을 통해 접근 가능하고 제어 가능하도록 해야 합니다.
사용자 에이전트는 SHOULD 현재 value("flag"와 number 포함)을 플랫폼 접근성 API를 통해 노출하여, 보조 기술이 필요할 때(예: 사용자가 애플리케이션 아이콘에 포커스할 때) 이를 제시할 수 있도록 해야 합니다.
사용자 에이전트는 SHOULD NOT 배지 변경을 자동으로 알리지 않아야 하며, 대신 원하지 않는 중단을 피하는 플랫폼의 관례를 따라야 SHOULD 합니다.
이 섹션은 비규범적입니다.
배지는 일반적으로 하위 플랫폼에서 그려지기 때문에, 시각적 요소는 보통 그곳에서 처리됩니다. 그럼에도 불구하고, 사용자 에이전트와 플랫폼은 다음 사항을 고려해야 합니다:
사용자 에이전트는 SHOULD 플랫폼 접근성 설정 및 테마와 통합해야 합니다.
사용자 에이전트는 SHOULD OS 수준의 앱별 배지 환경설정(예: 운영 체제가 앱에 대해 배지를 비활성화하는 경우)을 반영해야 합니다.
비규범적인 부분으로 표시된 섹션뿐만 아니라, 이 명세서에 포함된 모든 작성 지침, 다이어그램, 예시, 그리고 노트도 비규범적입니다. 그 외의 모든 내용은 규범적입니다.
이 문서에서 MAY, MUST, MUST NOT, SHOULD, SHOULD NOT 등 주요 용어는 BCP 14 [RFC2119] [RFC8174] 에서 설명된 대로 해석되어야 하며, 오직 이처럼 모두 대문자로 표시될 때만 해당 해석이 적용됩니다.
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in: