웹 애플리케이션 매니페스트

W3C 워킹 드래프트

이 문서에 대한 자세한 내용
이 버전:
https://www.w3.org/TR/2026/WD-appmanifest-20260507/
최신 공식 버전:
https://www.w3.org/TR/appmanifest/
최신 편집 초안:
https://w3c.github.io/manifest/
이력:
https://www.w3.org/standards/history/appmanifest/
커밋 기록
편집자:
Marcos Cáceres (Apple)
Daniel Murphy (Google Inc.)
Christian Liebel (Thinktecture AG)
이전 편집자:
Matt Giuca (Google Inc.) - 까지
Anssi Kostiainen (Intel Corporation) - 까지
Aaron Gustafson (Microsoft Corporation) - 까지
Mounir Lamouri (Google Inc.)
Rob Dolin (Microsoft Corporation)
Kenneth Rohde Christiansen (Intel Corporation) - 까지
Diego González (Microsoft Corporation) - 까지
피드백:
GitHub w3c/manifest (풀 리퀘스트, 새 이슈, 오픈 이슈)
브라우저 지원:
caniuse.com

Copyright © 2026 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.

요약

이 명세서는 개발자가 웹 애플리케이션과 관련된 메타데이터를 중앙에서 관리할 수 있도록 하는 JSON 기반 파일 형식을 정의합니다. 이 메타데이터에는 웹 애플리케이션의 이름, 아이콘에 대한 링크, 사용자가 웹 애플리케이션을 실행할 때 열릴 기본 URL 등이 포함됩니다. 매니페스트는 또한 개발자가 웹 애플리케이션의 기본 화면 방향을 선언할 수 있게 하며, 애플리케이션의 표시 모드(예: 전체 화면)도 설정할 수 있습니다. 추가로, 매니페스트를 통해 개발자가 웹 애플리케이션을 특정 URL에 "스코프"로 지정할 수 있습니다. 이는 매니페스트가 적용되는 URL을 제한하며, 다른 애플리케이션에서 웹 애플리케이션으로 "딥 링크"할 수 있는 방법을 제공합니다.

이러한 메타데이터를 사용하면, 사용자 에이전트는 개발자에게 네이티브 애플리케이션과 비슷한 사용자 경험을 만들 수 있는 수단을 제공합니다.

문서 상태

이 섹션은 문서가 공개될 당시의 상태를 설명합니다. 현재 W3C 출판물 목록과 이 기술 보고서의 최신 개정본은 W3C 표준 및 드래프트 인덱스에서 확인할 수 있습니다.

경고

이 문서는 웹 애플리케이션 워킹 그룹에서 Recommendation 트랙을 따라 작업 초안으로 공개되었습니다.

작업 초안으로 공개되었다고 해서 W3C 및 회원들의 승인이나 지지를 의미하지는 않습니다.

이 문서는 초안이며, 언제든지 다른 문서에 의해 업데이트, 대체 또는 폐기될 수 있습니다. 진행 중인 작업 외에 이 문서를 인용하는 것은 부적절합니다.

이 문서는 W3C 특허 정책에 따라 운영되는 그룹에서 작성되었습니다. W3C는 공개 특허 공개 목록을 유지 관리합니다. 이 목록은 그룹의 결과물과 관련된 모든 특허 공개를 포함하며, 특허 공개 방법에 대한 안내도 포함되어 있습니다. 특정 특허가 Essential Claim(s)를 포함한다고 생각하는 개인은 W3C 특허 정책 6절에 따라 정보를 공개해야 합니다.

이 문서는 2025년 8월 18일자 W3C 프로세스 문서에 따라 관리됩니다.

1. 웹 애플리케이션 매니페스트

애플리케이션 매니페스트는 웹 애플리케이션이 실행될 때 시작 매개변수와 애플리케이션 기본값을 포함하는 [JSON] 문서입니다.

매니페스트는 매니페스트 URL이 연관되어 있는데, 이는 매니페스트가 가져온 [URL]입니다.

매니페스트는 루트에 아래의 멤버 중 어느 것이든 가질 수 있으며, 모두 선택 사항입니다. 멤버들은 어떤 순서로든 나타날 수 있습니다.

참고

1.1 예시

이 섹션은 규범적인 내용이 아닙니다.

이 섹션은 개발자가 이 명세의 다양한 기능을 어떻게 활용할 수 있는지를 보여줍니다.

1.1.1 일반적인 구조

이 섹션은 규범적인 내용이 아닙니다.

아래는 일반적인 매니페스트 예시입니다.

예시 1: 일반적인 매니페스트 
{
  "lang": "en",
  "dir": "ltr",
  "name": "Super Racer 3000",
  "short_name": "Racer3K",
  "icons": [{
    "src": "icon/lowres.webp",
    "sizes": "64x64",
    "type": "image/webp"
  }, {
    "src": "icon/lowres.png",
    "sizes": "64x64"
  }, {
    "src": "icon/hd_hi",
    "sizes": "128x128"
  }],
  "scope": "/",
  "id": "superracer",
  "start_url": "/start.html",
  "display": "fullscreen",
  "orientation": "landscape",
  "theme_color": "aliceblue",
  "background_color": "red"
}

1.1.3 여러 아이콘 선언하기

이 섹션은 규범적인 내용이 아닙니다.

이 섹션은 icons 멤버를 사용해 웹 애플리케이션에 대한 여러 아이콘을 선언하는 방법을 보여줍니다. 아래 예시에서 개발자는 웹 애플리케이션에 포함된 아이콘에 대해 다음과 같이 선택했습니다:

  • 개발자는 같은 크기의 아이콘 두 개를 서로 다른 포맷으로 포함했습니다. 하나는 type 멤버를 통해 WebP로 명시했습니다. 만약 사용자 에이전트가 WebP를 지원하지 않으면 같은 크기의 두 번째 아이콘을 사용할 수 있습니다. 이 아이콘의 MIME 타입은 HTTP 헤더를 통해 결정되거나, 아이콘의 앞부분 몇 바이트를 통해 사용자 에이전트가 스니핑해서 결정할 수 있습니다.
  • 개발자는 픽셀 기반 아이콘 포맷(예: PNG 파일)에 대해 다양한 크기를 지정했습니다. 이 크기들은 사용자 에이전트가 특정 환경(예: 기기 홈 화면)에 사용할 적합한 아이콘을 결정하는 힌트입니다. 또한 ICO 파일(예: hd_hi.ico)을 포함했는데, 이는 각 디스플레이 크기에 맞게 개별적으로 설계된 래스터 아이콘을 포함합니다. 예를 들어, 256x256 이미지를 그대로 16x16 환경에 다운스케일하면 디테일이 크게 손실되기 때문에, 16x16 환경에 맞게 별도 이미지를 사용하는 것이 일반적입니다. 추가로 SVG 아이콘도 제공해 어떤 아이콘 크기에도 동적으로 리사이즈할 수 있지만, 일부 환경에서는 너무 작거나 흐려질 수 있습니다.

아이콘 목록은 사용자 에이전트에 제공되며, 다양한 환경과 위치에 맞춰 가장 적합한 아이콘이 선택됩니다.

예시 3: 여러 아이콘 
{
  "icons": [
    {
      "src": "icon/lowres.webp",
      "sizes": "48x48",
      "type": "image/webp"
    },{
      "src": "icon/lowres",
      "sizes": "48x48"
    },{
      "src": "icon/hd_hi.ico",
      "sizes": "72x72 96x96 128x128 256x256"
    },{
      "src": "icon/hd_hi.svg"
    }]
}

1.1.4 바로가기 만들기

이 섹션은 규범적인 내용이 아닙니다.

아래 예시에서 개발자는 두 개의 바로가기를 포함했습니다. 매니페스트의 URL이 https://example.com/manifest.webmanifest라고 가정하면:

  • 첫 번째 바로가기는 "Play Later"라는 텍스트로 표시됩니다. 운영체제가 컨텍스트 메뉴 아이콘과 SVG 이미지를 지원한다면, 사용자 에이전트는 https://example.com/icons/play-later.svg를 텍스트 옆에 표시할 수 있습니다. 실행 시, 사용자 에이전트는 새로운 최상위 브라우징 컨텍스트를 인스턴스화하고 https://example.com/play-later로 이동합니다.
  • 두 번째 바로가기는 "Subscriptions"라는 텍스트로 표시됩니다. 실행 시, 사용자 에이전트는 새로운 최상위 브라우징 컨텍스트를 인스턴스화하고 https://example.com/subscriptions?sort=desc로 이동합니다.
예시 4: 바로가기 추가 
{
  "shortcuts": [
    {
      "name": "Play Later",
      "description": "나중에 저장한 팟캐스트 목록 보기",
      "url": "/play-later",
      "icons": [
        {
          "src": "/icons/play-later.svg",
          "type": "image/svg+xml"
        }
      ]
    },
    {
      "name": "Subscriptions",
      "description": "구독 중인 팟캐스트 목록 보기",
      "url": "/subscriptions?sort=desc"
    }
  ]
}

1.1.5 "scope" 이해하기

이 섹션은 규범적인 내용이 아닙니다.

scope 멤버는 브라우저에게 어떤 문서가 웹 애플리케이션에 포함되고 어떤 문서가 아닌지를 알려줍니다. 즉, 사용자가 웹 사이트를 탐색할 때 매니페스트가 "적용"되는 웹 페이지 집합을 지정합니다.

예를 들어, {"scope": "/"}는 매니페스트가 오리진 내 모든 문서에 적용된다는 의미입니다. 반면, {"scope": "/racer/"}는 "/racer/" 경로 내의 문서에만 적용되어 "/racer/race1.html", "/racer/race2.html" 등은 모두 scope 내에 포함되지만, "/elsewhere/"나 루트 "/"는 "scope 밖"이므로 해당 경로의 문서에는 매니페스트가 적용되지 않습니다. 하나의 scope 경로만 지원합니다. 기술적인 상세는 5. 탐색 범위에서 확인할 수 있습니다.

매니페스트를 "적용"한다는 것은 매니페스트에서 프레젠테이션에 영향을 주는 멤버들이 효력을 발휘한다는 뜻입니다(예: 전체화면 디스플레이, 특정 화면 방향 적용 등). 애플리케이션이 scope 내 URL로 탐색되는 동안 브라우저는 계속해서 매니페스트를 적용합니다. 하지만 "scope 밖"으로 이동하면 매니페스트 적용이 중단되고 브라우저의 기본값이 적용됩니다. 예를 들어, 애플리케이션이 더 이상 전체화면이 아닌 브라우저 탭의 일반 웹 페이지로 표시될 수 있습니다. 구현자들은 웹 페이지가 scope 안팎으로 이동할 때의 동작을 자유롭게 결정할 수 있습니다. 자세한 기술 내용은 1.17.5 매니페스트 적용에서 확인할 수 있습니다.

마지막으로, 사용자가 오리진 내 어떤 문서에서든 웹 애플리케이션을 설치할 수 있으므로, 항상 매니페스트에 scope 멤버를 선언하는 것이 좋습니다. 만약 매니페스트에 scope 멤버가 없다면 start_url 멤버의 경로가 대체로 사용됩니다. 그리고 start_url마저 없으면, 웹 애플리케이션을 설치한 문서의 URL이 scope로 사용됩니다. 예기치 않은 탐색 동작을 피하려면 저자는 항상 scope 멤버를 포함시키고, 가능하다면 "/"로 설정하는 것이 바람직합니다.

1.2 dir 멤버

매니페스트의 dir 멤버는 기본 방향을 현지화 가능한 멤버에 대해 지정합니다. dir 멤버 값은 텍스트 방향으로 설정할 수 있습니다.

텍스트 방향은 다음과 같으며, 현지화 가능한 멤버의 기본값을 의미합니다:

"ltr"
왼쪽에서 오른쪽으로 쓰는 텍스트입니다.
"rtl"
오른쪽에서 왼쪽으로 쓰는 텍스트입니다.
"auto" (기본값)
텍스트 방향을 알 수 없습니다. 사용자 에이전트는 텍스트 표시를 추정하기 위해 휴리스틱을 사용해야 하며, 예를 들어 [UAX9]에 서술된 first-strong 알고리즘을 사용할 수 있습니다.

텍스트 방향 목록은 리스트 « "ltr", "rtl", "auto" » 입니다.

dir 멤버를 처리하려면, ordered map json과 ordered map manifest가 주어졌을 때:

  1. manifest["dir"]을 "auto"로 설정한다.
  2. json["dir"]이 존재하지 않거나, json["dir"]이 문자열이 아니면, 리턴한다.
  3. ASCII 앞뒤 공백 제거를 json["dir"]에 수행한다.
  4. ASCII 소문자화를 json["dir"]에 수행한다.
  5. 텍스트 방향 목록에 json["dir"]이 포함되지 않으면, 리턴한다.
  6. manifest["dir"]을 json["dir"]로 설정한다.

1.3 lang 멤버

매니페스트의 lang 멤버는 문자열 형태의 언어 태그로, 매니페스트의 현지화 가능한 멤버 값의 언어를 지정합니다. lang 멤버가 지정되지 않으면, 언어는 알 수 없는 것으로 처리됩니다.

참고

언어를 지정하면 사용자 에이전트가 폰트, 스타일, 하이픈 적용, 접근성을 위한 텍스트-음성 변환 등에서 가장 적절한 처리나 리소스를 선택할 수 있어 사용자 경험이 개선됩니다.

언어 태그는 [BCP47]에서 정의된 올바른 Language-Tag 생산식과 일치하는 문자열입니다.

참고

언어 태그는 대소문자를 구분하지 않습니다. 언어 태그 예시로는 'fr'(프랑스어), 'en-AU'(호주 영어), 'zh-Hans-CN'(중국 간체 한자)이 있습니다.

lang 멤버를 처리하려면, ordered map json과 ordered map manifest가 주어졌을 때:

  1. json["lang"]이 존재하지 않거나, json["lang"]이 문자열이 아니면 리턴한다.
  2. ASCII 앞뒤 공백 제거를 json["lang"]에 수행한다.
  3. IsStructurallyValidLanguageTag를 json["lang"]에 호출하여 false를 반환하면 리턴한다.
  4. Set manifest["lang"]을 json["lang"]에 CanonicalizeUnicodeLocaleId 추상 연산의 결과로 설정한다.

1.4 name 멤버

매니페스트의 name 멤버는 문자열이며, 웹 애플리케이션의 이름을 나타내며, 일반적으로 사용자에게 표시됩니다(예: 다른 애플리케이션 목록, 아이콘 라벨 등).

name 멤버는 현지화 가능한 멤버입니다.

name 멤버는 접근 가능한 이름으로 설치된 웹 애플리케이션에 사용됩니다.

참고: `name` 멤버 처리

매니페스트 처리 시 텍스트 멤버 처리 알고리즘을 사용하여 name 멤버를 처리합니다.

1.5 short_name 멤버

매니페스트의 short_name 멤버는 문자열로, 웹 애플리케이션 이름의 짧은 버전을 나타냅니다. 전체 이름을 표시할 공간이 충분하지 않은 경우에 사용됩니다.

short_name 멤버는 현지화 가능한 멤버입니다.

참고: `short_name` 멤버 처리

매니페스트 처리 시 텍스트 멤버 처리 알고리즘을 사용하여 short_name 멤버를 처리합니다.

1.6 scope 멤버

매니페스트의 scope 멤버는 문자열로, 해당 웹 애플리케이션의 탐색 범위를 나타내며, 애플리케이션 컨텍스트에 적용됩니다.

참고: 기본 scope

scope 멤버 처리 방법: ordered map json과 ordered map manifest가 주어졌을 때:

  1. manifest["scope"]에 파싱 "."을 manifest["start_url"]을 기준(base URL)으로 하여 결과를 할당한다.
  2. json["scope"]가 빈 문자열이면 리턴한다.
  3. scope을 파싱 json["scope"]를 manifest URL을 기준으로 하여 결과로 한다.
  4. scope이 실패(failure)이면 리턴한다.
  5. scope의 query와 fragment를 null로 설정한다.
  6. manifest["start_url"]이 scope 내가 아니면 리턴한다.
  7. 그 외의 경우, manifest["scope"]를 scope로 설정한다.

1.7 icons 멤버

매니페스트의 icons 멤버는 다양한 환경에서 웹 애플리케이션을 상징적으로 나타내는 이미지입니다. 예를 들어, 다른 애플리케이션 목록에서 웹 애플리케이션을 표시하거나, OS의 작업 전환기 또는 시스템 설정에 통합할 때 사용할 수 있습니다.

icons 멤버는 현지화 가능한 멤버입니다.

참고

1.8 display 멤버

매니페스트의 display 멤버는 웹 애플리케이션의 표시 모드에 대한 개발자의 선호를 나타냅니다. 값은 display mode입니다.

display 멤버 처리 방법: ordered map json과 ordered map manifest가 주어졌을 때:

  1. manifest["display"]를 "browser"로 설정한다.
  2. json["display"]가 존재하지 않거나 json["display"]가 문자열이 아니면 리턴한다.
  3. ASCII 앞뒤 공백 제거를 json["display"]에 수행한다.
  4. ASCII 소문자화를 json["display"]에 수행한다.
  5. display modes list에 json["display"]가 포함되지 않으면, 리턴한다.
  6. manifest["display"]를 json["display"]로 설정한다.

1.9 orientation 멤버

매니페스트의 orientation 멤버는 문자열로, 웹 애플리케이션의 모든 최상위 브라우징 컨텍스트의 기본 화면 방향 역할을 합니다. 가능한 값은 OrientationLockType 열거형의 값이며, 본 명세에서는 orientation values ("any", "natural", "landscape", "portrait", "portrait-primary", "portrait-secondary", "landscape-primary", "landscape-secondary")로 불립니다.

사용자 에이전트가 orientation 멤버의 값을 기본 화면 방향으로 지원한다면, 그 값이 웹 애플리케이션의 생명주기 동안 기본 화면 방향으로 동작합니다(런타임에 다른 방법으로 재정의하지 않는 한). 즉, 사용자 에이전트는 orientation이 unlock될 때마다 반드시(MUST) 기본 화면 방향으로 되돌려야 하며, 최상위 브라우징 컨텍스트가 탐색(navigated)될 때도 마찬가지입니다.

참고

명세는 [SCREEN-ORIENTATION]의 OrientationLockType에 의존하지만, 사용자 에이전트가 [SCREEN-ORIENTATION] API를 구현하는 것은 옵션(OPTIONAL)입니다. 물론 해당 API 지원을 권장합니다.

UI/UX 및 플랫폼 관례에 따라 일부 화면 방향과 함께 사용할 수 없는 표시 모드가 존재할 수 있습니다. 어떤 방향과 표시 모드가 함께 사용할 수 없는지는 구현자의 재량에 맡깁니다. 예를 들어, 일부 사용자 에이전트에서는 기본 화면 방향을 browser 표시 모드에서 변경하는 것이 이상할 수 있습니다.

참고

웹 애플리케이션이 실행 중일 때, 다른 방법(예: [SCREEN-ORIENTATION] API 등)으로 최상위 브라우징 컨텍스트의 방향을 변경할 수 있습니다.

orientation 멤버 처리 방법: ordered map json과 ordered map manifest가 주어졌을 때:

  1. json["orientation"]이 존재하지 않거나 json["orientation"]이 문자열이 아니면 리턴한다.
  2. ASCII 앞뒤 공백 제거를 json["orientation"]에 수행한다.
  3. ASCII 소문자화를 json["orientation"]에 수행한다.
  4. json["orientation"]이 포함하지 않으면 orientation values 중 아무것도, 리턴한다.
  5. manifest["orientation"]을 json["orientation"]로 설정한다.

1.10 start_url 멤버

매니페스트의 start_url 멤버는 문자열로, 시작 URL을 나타냅니다. 즉, 사용자가 웹 애플리케이션을 실행할 때(예: 기기 앱 메뉴나 홈 화면에서 아이콘을 클릭할 때) 사용자 에이전트가 로드하길 개발자가 원하는 URL입니다.

start_url 멤버는 권고적(advisory)이며, 사용자 에이전트는 MAY 무시하거나 최종 사용자가 사용하지 않을 선택권을 제공할 수 있습니다. 또한, 예를 들어 웹 애플리케이션에 대한 북마크를 만들 때나 그 이후에도, 사용자 에이전트는 최종 사용자가 URL을 수정하도록 허용할 수 있습니다(MAY).

start_url 멤버 처리 방법: ordered map json, ordered map manifest, URL manifest URL, URL document URL이 주어졌을 때:

  1. manifest["start_url"]을 document URL로 설정한다.
  2. json["start_url"]이 존재하지 않거나 json["start_url"]이 문자열이 아니면 리턴한다.
  3. json["start_url"]의 타입이 문자열이 아니거나, 빈 문자열이면 리턴한다.
  4. start URL을 파싱 json["start_url"]을 manifest URL을 기준으로 하여 얻는다.
  5. start URL이 실패(failure)이면 리턴한다.
  6. start URL이 document URL과 same origin이 아니면 리턴한다.
  7. 그 외의 경우, manifest["start_url"]을 start URL로 설정한다.

1.10.1 개인정보 보호 고찰: start_url 추적

start_url이 브라우저 외부에서 애플리케이션이 실행되었음을 나타내도록 설계될 수도 있습니다(예: "start_url": "index.html?launcher=homescreen"). 이는 분석(analytics)이나 기타 커스텀 기능에 유용할 수 있습니다. 그러나 개발자가 start_url에 사용자 고유 식별자(예: 서버에서 할당된 식별자, "?user=123", "/user/123/", "https://user123.foo.bar")를 인코딩할 수도 있습니다. 이는 사용자가 인지하지 못하는 지문/개인정보 민감 정보가 될 수 있습니다.

참고: start URL에 식별자 추가 금지

개발자가 start URL에 사용자 고유 정보를 포함하는 것은 좋지 않은 습관입니다. 이는 사용자가 사이트 데이터를 삭제해도 지문이 남을 수 있습니다. 하지만 본 명세는 이를 실질적으로 방지할 방법을 제공하지 않습니다.

위의 이유로, 설치 시 또는 그 이후에라도, 사용자 에이전트가 사용자가 애플리케이션의 start URL을 검사 및 필요 시 수정할 수 있도록 허용하는 것이 권장(RECOMMENDED)됩니다.

사용자 에이전트는 이런 형태의 지문(식별) 방지책을 제공할 수 있습니다(MAY). 예를 들어, 사용자가 오리진의 데이터를 삭제할 때, 사용자 에이전트는 해당 오리진의 scope 내 애플리케이션을 제거하여 start URL에 남은 지문을 함께 삭제할 수 있습니다.

1.11 id 멤버

매니페스트의 id 멤버는 문자열로, 애플리케이션의 고유 식별자(identity)를 나타냅니다. 고유 식별자(identity)는 URL 형태를 가지며, start URL과 동일한 오리진입니다.

고유 식별자는 사용자 에이전트가 애플리케이션을 전역적으로 고유하게 식별하는 데 사용됩니다. 사용자 에이전트가 고유 식별자가 기존에 설치된 애플리케이션과 일치하지 않는 매니페스트를 발견하면, 그 매니페스트를 별도의 애플리케이션으로 간주해야 합니다(SHOULD). 동일한 URL에서 제공되더라도 별도 애플리케이션으로 처리합니다. 반대로, manifest["id"]가 이미 설치된 애플리케이션의 고유 식별자와 동일(equal)하면(옵션으로 프래그먼트 제외 설정 가능), 그 매니페스트는 기존 애플리케이션의 매니페스트를 대체하는 것으로 간주해야 합니다(SHOULD). 이전과 다른 URL에서 제공되어도 별도 애플리케이션으로 취급하지 않습니다.

참고: 프래그먼트 제외가 최선의 관행
참고

고유 식별자는 웹 애플리케이션 목록을 수집하는 서비스에서 개별 애플리케이션을 고유하게 식별하는 데 사용할 수 있습니다.

참고

고유 식별자는 URL처럼 처리되지만, 탐색할 수 있는 리소스를 가리키지 않으므로 scope 내일 필요는 없습니다.

id 멤버 처리 방법: ordered map json, ordered map manifest가 주어졌을 때:

  1. manifest["id"]를 manifest["start_url"]로 설정한다.
  2. json["id"]의 타입이 문자열이 아니면 리턴한다.
  3. json["id"]가 빈 문자열이면 리턴한다.
  4. base origin을 manifest["start_url"]의 origin으로 한다.
  5. id를 파싱 json["id"]를 base origin을 기준으로 하여 얻는다.
  6. id가 실패(failure)이면 리턴한다.
  7. id가 manifest["start_url"]와 동일 오리진이 아니면 리턴한다.
  8. id의 fragment를 null로 설정한다.
  9. manifest["id"]를 id로 설정한다.

1.12 theme_color 멤버

매니페스트의 theme_color 멤버는 테마 적용이 가능한 멤버이며 애플리케이션 컨텍스트의 기본 테마 색상 역할을 합니다. 테마 색상이 무엇인지는 [HTML]에서 정의되어 있습니다.

사용자 에이전트가 theme_color 멤버 값을 기본 테마 색상으로 적용하면, 해당 색상은 매니페스트가 적용된 모든 브라우징 컨텍스트의 테마 색상이 됩니다. 단, 사용자 에이전트는 MAY 기본 테마 색상을, 문서의 URL이 scope 내이고 그 애플리케이션 컨텍스트의 매니페스트에 meta 요소가 있고 name 속성이 "theme-color"일 때, 이를 통해 오버라이드할 수 있습니다. 하지만 사용자 에이전트는 SHOULD NOT scope 밖 문서의 URL에 대해 name="theme-color" meta 요소로 기본 테마 색상을 오버라이드해서는 안 됩니다. 애플리케이션이 해당 문서들을 제어할 수 없기 때문입니다.

사용자 에이전트는 MAY 테마 색상의 알파 컴포넌트를 환경에 따라 무시할 수 있습니다. 예를 들어, 대부분의 환경에서는 테마 색상에 투명값을 사용할 수 없습니다.

구현자는 MAY theme_color 멤버로 정의된 값을 prefers-color-scheme 지원을 위해 오버라이드할 수 있습니다.

참고

매니페스트를 처리할 때, 색상 멤버 처리 알고리즘을 사용해 theme_color 멤버를 처리합니다.

1.13 background_color 멤버

매니페스트의 background_color 멤버는 테마 적용이 가능한 멤버로, 웹 애플리케이션의 예상되는 배경 색상을 설명합니다. 이 값은 애플리케이션 스타일시트에 이미 포함되어 있지만, 사용자 에이전트가 파일이 실제로 네트워크에서 받아지거나 디스크에서 읽기 전에 매니페스트를 인식한 웹 애플리케이션의 배경 색을 그릴 때 사용할 수 있습니다.

background_color 멤버는 웹 애플리케이션이 로딩되는 동안 사용자 경험을 개선하기 위한 용도이며, 사용자 에이전트가 웹 애플리케이션의 스타일시트가 적용된 이후에는 배경색으로 사용해서는 안 됩니다(MUST NOT).

구현자는 MAY background_color 멤버로 정의된 값을 prefers-color-scheme 지원을 위해 오버라이드할 수 있습니다.

참고

매니페스트를 처리할 때, 색상 멤버 처리 알고리즘을 사용해 background_color 멤버를 처리합니다.

1.14 shortcuts 멤버

매니페스트의 shortcuts 멤버는 웹 애플리케이션 내 핵심 작업에 접근할 수 있는 목록(list) 형태의 shortcut item들입니다.

참고

바로가기가 어떻게 표시되고 몇 개가 사용자에게 노출되는지는 사용자 에이전트 및/또는 운영체제의 재량입니다.

shortcuts 멤버 처리 방법: ordered map json, ordered map manifest, URL manifest URL이 주어졌을 때:

  1. processedShortcuts를 새 목록(list)으로 생성한다.
  2. Set manifest["shortcuts"]를 processedShortcuts로 설정한다.
  3. json["shortcuts"]가 존재하지 않거나, json["shortcuts"]가 목록(list)이 아니면 리턴한다.
  4. 각각 entry에 대해 json["shortcuts"]:
    1. shortcut을 process a shortcut에 entry, manifest URL, manifest["scope"], manifest["dir"]를 넘겨서 얻는다.
    2. shortcut이 실패라면 continue.
    3. Append shortcut을 processedShortcuts에 추가한다.

사용자 에이전트는 SHOULD 운영체제의 앱 아이콘 컨텍스트 메뉴 노출 방식과 일관된 인터페이스(예: 우클릭, 롱프레스 등)로 바로가기를 노출해야 합니다. 바로가기는 매니페스트에 제공된 순서대로 렌더링해야 하며, 컨텍스트 메뉴 노출 방식과 일관되게 표현해야 합니다. 운영체제의 관행이나 제한에 맞추기 위해 바로가기 목록을 잘라내 MAY 일부만 보여줄 수 있습니다.

1.15 *_localized 멤버

현지화 가능한 멤버(localizable member)는 매니페스트의 현지화가 가능한 멤버입니다. 각 현지화 가능한 멤버에는 *_localized 멤버가 대응하며, *는 실제 멤버 이름을 나타냅니다.

언어 맵(language map)은 ordered map으로, 키는 언어 태그(language tag)이고 값은 localized value입니다. localized value는 키에 지정된 언어로 현지화된 콘텐츠입니다.

현지화 가능한 멤버에 할당된 값은 기본 표현(default representation)입니다. *_localized 멤버들은 언어 맵을 포함하며, 애플리케이션 내 해당 현지화 가능한 멤버에 대해 localized value를 정의합니다. 사용자 에이전트는 SHOULD 사용자의 현지화 설정에 따라 언어 태그 키가 사용자의 선호와 가장 잘 일치하는 localized value를 선택해야 합니다. 해당 localized value가 없는 경우, 기본 표현(default representation)을 사용합니다.

1.15.1 텍스트 값의 지역화

localized text object는 다음 속성을 가지는 ordered map입니다:

value
지역화된 문자열입니다.
dir (선택)
텍스트 방향입니다.
lang (선택)
언어 태그입니다.

지역화 가능한 멤버가 문자열을 허용하는 경우, *_localized 멤버의 language map은 문자열 또는 localized text object를 localized value로 허용합니다.

문자열을 사용하는 경우나 dir 멤버가 localized text object에 없으면, 기본 방향(매니페스트의 dir 멤버)이 적용됩니다.

Note

문자열을 사용하는 경우나 lang 멤버가 localized text object에 없으면, language tag(language map의 key)가 적용됩니다.

Note

*_localized 텍스트 멤버 처리는 ordered map json, ordered map map, string member, text-direction defaultDirection을 입력으로 다음과 같이 동작합니다:

  1. member가 json에 존재하지 않으면 return.
  2. languageMap을 json[member]로 설정.
  3. languageMap이 ordered map이 아니면 return.
  4. languageTags를 languageMap의 키들로 설정.
  5. map[member]를 새 ordered map으로 설정.
  6. 각 languageTag를 languageTags에서 반복하여 localized text object 처리를 languageMap[languageTag], languageTag, map, member, defaultDirection에 대해 실행.

localized text object 처리는 문자열 또는 ordered map localizedValue, string defaultLanguageTag, ordered map map, string member, text-direction defaultDirection을 입력으로 다음과 같이 동작합니다:

  1. normalizedValue를 새 ordered map으로 설정.
  2. localizedValue가 문자열이면, 앞뒤 ASCII 공백 제거 후 normalizedValue["value"]에 localizedValue를 설정.
  3. localizedValue가 ordered map이면:
    1. "value"가 존재하고 localizedValue["value"]가 문자열이면, 앞뒤 ASCII 공백 제거 후 normalizedValue["value"]에 할당.
    2. "lang"이 존재하고 localizedValue["lang"]가 문자열이면, 앞뒤 ASCII 공백 제거 후 normalizedValue["lang"]에 할당.
    3. "dir"이 존재하고 localizedValue["dir"]가 문자열이면:
      1. 앞뒤 ASCII 공백 제거 후 localizedValue["dir"]에 적용.
      2. text-direction list가 포함하면 normalizedValue["dir"]에 할당.
  4. "value"가 존재하지 않으면 return.
  5. "lang"이 존재하지 않으면, normalizedValue["lang"]에 defaultLanguageTag 할당.
  6. "dir"이 존재하지 않으면, normalizedValue["dir"]에 defaultDirection 할당.
  7. IsStructurallyValidLanguageTag를 normalizedValue["lang"] 또는 defaultLanguageTag에 호출해서 false면 return.
  8. Set map[member][defaultLanguageTag] = normalizedValue.
Note

localized text object 처리 알고리즘은 문자열 또는 localized text object 모두를 localized value로 받을 수 있지만, 처리 결과는 value, lang, dir 멤버가 설정된 localized text object로 정규화됩니다.

1.15.2 이미지 리소스의 지역화

지역화 가능한 멤버가 리스트의 image resources를 허용하는 경우, *_localized 멤버의 language map은 리스트의 image resources를 localized value로 허용합니다.

*_localized 이미지 리소스 멤버 처리는 ordered map json, ordered map map, string member, URL manifest URL을 입력으로 다음과 같이 동작합니다:

  1. member가 json에 존재하지 않으면 return.
  2. languageMap을 json[member]로 설정.
  3. languageMap이 ordered map이 아니면 return.
  4. languageTags를 languageMap의 키들로 설정.
  5. map[member]를 새 ordered map으로 설정.
  6. 각 languageTag를 languageTags에서 반복:
    1. IsStructurallyValidLanguageTag를 languageTag에 호출해서 false면 continue.
    2. 이미지 리소스 처리를 실행하며, languageMap[languageTag]을 리스트의 image resources로, map[member], manifest URL, languageTag를 member로 전달.

1.16 color_scheme_dark 멤버

매니페스트의 color_scheme_dark 멤버는 순서가 있는 맵(ordered map)으로, 키는 테마 적용이 가능한 멤버이고, 값은 운영 체제가 다크 테마를 사용할 때 이 멤버들의 우선 적용될 색상 값입니다.

테마 적용이 가능한 멤버는 다음 매니페스트 멤버 중 하나입니다:

매니페스트를 적용할 때 운영 체제가 다크 테마를 사용하고, 해당 테마 적용이 가능한 멤버 member가 color_scheme_dark에 존재한다면, 유저 에이전트는 SHOULD(권장사항) color_scheme_dark[member]의 값을 member의 값 대신 사용해야 합니다. 다만 사용자의 접근성 설정 등 선호도가 더 우선시될 수 있습니다.

1.16.1 테마 적용 가능한 멤버의 테마화

color_scheme_dark 멤버를 처리하려면, 순서가 있는 맵(ordered map) json과 순서가 있는 맵 manifest, 그리고 URL manifest URL을 전달 받아 다음을 수행합니다:

  1. json["color_scheme_dark"]가 존재하지 않으면 return.
  2. colorScheme을 json["color_scheme_dark"]로 설정.
  3. colorScheme이 순서가 있는 맵이 아니면 return.
  4. processedColorScheme을 새로운 순서가 있는 맵으로 생성.
  5. Set manifest["color_scheme_dark"]에 processedColorScheme를 할당.
  6. 각각 member가 « "theme_color", "background_color" »인 경우:
    1. 색상 멤버 처리를 colorScheme, processedColorScheme, member를 전달하여 실행.

1.17 매니페스트 수명 주기

이 절에서는 매니페스트를 처리하고, 적용하는 알고리즘을 매니페스트에 대해 정의합니다.

사용자 에이전트는 "manifest" 링크 타입과 연관된, 연결된 리소스를 가져오고 처리하는 단계들을 MUST 지원해야 합니다.

1.17.1 매니페스트 처리

무시하도록 지시받으면, 사용자 에이전트는 해당 조건을 유발한 매니페스트, 멤버, 혹은 값이 존재하지 않는 것처럼 MUST 동작해야 합니다.

다음 알고리즘은 처리 확장 지점을 제공합니다. 매니페스트에 새로운 멤버를 추가하는 다른 스펙은 이 알고리즘의 이 지점에서 이 스펙에 자신을 훅(hook)으로 연결하는 것이 권장됩니다. 이들은 SHOULD NOT 이미 manifest 객체에 있는 기존 값을 수정해서는 안 됩니다.

Note

처리 확장 지점은 몽키 패치와 관련된 문제를 피하는 데 도움을 주기 위한 것입니다.

매니페스트 처리 단계는 다음 알고리즘에 의해 제공됩니다. 이 알고리즘은 URL 문서 URL, URL 매니페스트 URL, 바이트 시퀀스 bodyBytes 및 client (an 환경 설정 객체 또는 null).

  1. json을, JSON 바이트를 Infra 값으로 파싱 한 결과로 두며, 인수로 bodyBytes를 전달합니다.
  2. 만약 json이 파싱 예외이거나, json이 순서가 있는 맵이 아니라면:
    1. json을 빈 순서가 있는 맵으로 설정합니다.
  3. manifest를 빈 순서가 있는 맵으로 둡니다.
  4. dir 멤버를 처리하며, json과 manifest를 인수로 전달합니다.
  5. lang 멤버를 처리하며, json과 manifest를 인수로 전달합니다.
  6. 텍스트 멤버를 처리하며, json, manifest, 그리고 "name"을 인수로 전달합니다.
  7. *_localized 텍스트 멤버를 처리하며, json, manifest, "name_localized", 그리고 manifest["dir"]을 인수로 전달합니다.
  8. 텍스트 멤버를 처리하며, json, manifest, 그리고 "short_name"을 인수로 전달합니다.
  9. *_localized 텍스트 멤버를 처리하며, json, manifest, "short_name_localized", 그리고 manifest["dir"]을 인수로 전달합니다.
  10. start_url 멤버를 처리하며, json, manifest, manifest URL, 그리고 document URL을 인수로 전달합니다.
  11. id 멤버를 처리하며, json과 manifest를 인수로 전달합니다.
  12. document의 processed manifest가 null이 아니고, document의 processed manifest의 id가 동일하지 않다면 manifest["id"]와, return 합니다.
  13. scope 멤버를 처리하며, json, manifest, 그리고 manifest URL을 인수로 전달합니다.
  14. 색상 멤버를 처리하며, json, manifest, 그리고 "theme_color"를 인수로 전달합니다.
  15. 색상 멤버를 처리하며, json, manifest, 그리고 "background_color"를 인수로 전달합니다.
  16. display 멤버를 처리하며, json과 manifest를 인수로 전달합니다.
  17. 이미지 리소스를 처리하며, json["icons"], manifest, manifest URL, 그리고 "icons"를 인수로 전달합니다.
  18. *_localized 이미지 리소스 멤버를 처리하며, json, manifest, "icons_localized", 그리고 manifest URL을 인수로 전달합니다.
  19. color_scheme_dark 멤버를 처리하며, json, manifest, 그리고 manifest URL을 인수로 전달합니다.
  20. orientation 멤버를 처리하며, json, manifest를 인수로 전달합니다.
  21. shortcuts 멤버를 처리하며, json, manifest, 그리고 manifest URL을 인수로 전달합니다.
  22. 처리 확장 지점: 이 시점에서 알고리즘이 지원하는 독자적이거나 기타 멤버들을 처리합니다.
  23. manifest의 클라이언트를 client로 설정합니다.
  24. document의 processed manifest를 manifest로 둡니다.

1.17.2 색상 멤버 처리

Note: 지원되는 색상

오직 sRGB 색상과, 사용자 에이전트가 별도의 지식 없이 sRGB로 변환할 수 있는 색상(예: "AliceBlue")만 지원됩니다. 예를 들어, lab(…)이나 color(display-p3, …)는 추가 지식 없이 sRGB로 변환할 수 있지만, color(--custom-profile, …)은 매니페스트에서 지정할 수 없는 "@color-profile" 규칙을 찾아야 하므로 사용할 수 없습니다.

순서가 있는 맵 json, 순서가 있는 맵 map, 그리고 문자열 member를 사용하여 색상 멤버를 처리하려면:

  1. 만약 json[member]가 존재하지 않거나, json[member]가 문자열이 아니라면 return 합니다.
  2. 선행 및 후행 ASCII 공백 제거를 json[member]에 수행합니다.
  3. color를, CSS 색상으로 파싱한 json[member] 값의 결과로 둡니다.
  4. 만약 color가 실패(failure)라면 return 합니다.
  5. 만약 color가, 사용자 에이전트가 본래 알고 있는 정보만으로 sRGB로 변환될 수 있다면, color를 sRGB로 변환합니다.
  6. 만약 color가 sRGB 색상이 아니라면 return 합니다.
  7. map[member]를 color로 설정합니다.

1.17.3 텍스트 멤버 처리

순서가 있는 맵 json, 순서가 있는 맵 map, 그리고 문자열 member가 주어졌을 때 텍스트 멤버를 처리하기 위해:

  1. 만약 json[member]가 존재하지 않거나, json[member]가 문자열이 아니라면 return 합니다.
  2. 선행 및 후행 ASCII 공백 제거를 json[member]에 수행합니다.
  3. map[member]를 json[member] 값으로 설정합니다.

1.17.4 문서 없이 매니페스트 처리

매니페스트 처리 단계는 [HTML]의 link 요소 처리 단계에 의해 호출되며, 이 경우 client는 문서의 관련 설정 객체입니다. 단계는 또한 MAY 사용자 에이전트에 의해 관련 문서 없이 매니페스트를 처리하기 위해 호출될 수 있으며, 이 경우 client는 null입니다.

이 경우, [HTML]에 정의된 대응되는 단계들이 제공하는 보장을 만족하기 위해, 사용자 에이전트는 최소한 과거의 어느 시점에 다음 조건이 충족되도록 하는 것이 SHOULD 입니다:

Note: 이러한 검사에 대한 근거

1.17.5 매니페스트 적용

처리된 manifest는 최상위 browsing context에 적용된다. 이는 manifest의 구성원들이 해당 browsing context의 표현 및/또는 동작에 영향을 주고 있음을 의미한다. 최상위 browsing context가 생성될 때마다, 사용자 에이전트는 navigation이 시작되기 전에 manifest를 그것에 적용MAY 한다.

사용자 에이전트는 기존의 최상위 브라우징 컨텍스트에 매니페스트를 적용할 수도 있습니다(MAY). 만약 active document의 URL이 매니페스트의 범위 (within scope)에 있다면, 기존의 최상위 브라우징 컨텍스트는 application context가 됩니다. 만약 URL이 범위 안에 있지 않다면, 결과 동작은 구현 정의입니다.

Note
Note

매니페스트가 적용된 최상위 브라우징 컨텍스트는 application context라고 합니다.

만약 application context가, 사용자 에이전트가 내비게이션하도록 요청받은 딥 링크의 결과로 생성되었다면, 사용자 에이전트는 MUST 즉시 그 딥 링크로 내비게이션해야 하며, 이때 historyHandling은 "replace"로 설정해야 합니다. 그렇지 않은 경우, application context가 생성될 때, 사용자 에이전트는 MUST 즉시 start URL로 내비게이션해야 하며, 이때 historyHandling은 "replace"로 설정해야 합니다.

Note

1.17.6 매니페스트 업데이트

manifest 링크 관계에 대해 지정된 것처럼, 매니페스트는 매 페이지 로드마다 가져와지고 처리됩니다. 매니페스트 처리가 성공하면, 사용자 에이전트는 MAY 업데이트된 매니페스트를, 해당 애플리케이션과 연관된 현재 및 미래의 application context에 적용할 수 있습니다.

사용자 에이전트는 매니페스트 이미지 리소스가 업데이트되었다고 간주해야 하며(SHOULD), 이는 src 멤버가 변경된 경우입니다. 만약 src가 변경되지 않았다면, 사용자 에이전트는 MAY 이미지를 다운로드하여, 일부 경우 시각적 차이를 검사할 수 있습니다.

Note: 아이콘 메타데이터 변경

업데이트 목적상, 다음 멤버는 설치 시 및 런치 표면(launch surface)에 표시되므로 보안 민감 멤버로 간주됩니다:

  1. short_name과 short_name_localized에 있는 로컬라이즈된 표현,
  2. icons와 icons_localized에 있는 로컬라이즈된 표현,
  3. name과 name_localized에 있는 로컬라이즈된 표현.

매니페스트의 다른 모든 멤버는 비보안 민감 멤버로 간주됩니다.

보안 민감 업데이트는, 보안 민감 멤버에 대한 업데이트입니다. 이와 대응하여, 비보안 민감 업데이트는 비보안 민감 멤버에 대한 업데이트입니다.

타입이 매니페스트 이미지 리소스인 업데이트된 보안 민감 멤버 (예: icons)를 고려할 때, 사용자 에이전트는 MAY 이미지가 크게 시각적으로 다르지 않다고 판단하는 경우, 이를 비보안 민감 업데이트로 간주할 수 있습니다.

사용자 에이전트는 SHOULD 모든 비보안 민감 업데이트를 즉시 적용해야 합니다.

사용자 에이전트는 SHOULD 모든 보안 민감 업데이트를 사용자에게 제시하고, 변경 사항을 적용하기 전에 명시적 허가를 요구해야 합니다.

Note: 업데이트가 제시될 때 사용자에게 보여줄 수 있는 예시 옵션

보안 민감 멤버는 방향과 관계없이, [UTS55]에서 설명하는 바와 같이 양방향으로 격리된 방식으로 표시되어야 합니다(SHOULD).

사용자가 로컬라이제이션 설정을 변경한 경우, 사용자 에이전트는 MAY 실행 표면(launch surface)에 보이는 보안 민감 멤버를, *_localized 멤버에 지정된 로컬라이즈된 표현으로 자동 조정할 수 있습니다. 이러한 변경 사항은 사용자가 다음 번에 웹 애플리케이션을 열 때 사용자에게 제시되어야 합니다(SHOULD).

2. 매니페스트 이미지 리소스

각 매니페스트 이미지 리소스는 이미지 리소스입니다. 매니페스트 이미지 리소스가 표시되는 문맥은 관련 매니페스트 멤버의 의미에 의해 결정됩니다(예: icons 멤버는 일반적으로 애플리케이션 아이콘을 나타내는 데 사용됩니다).

매니페스트 이미지 리소스는 일반 이미지 리소스와 달리 추가적인 purpose 멤버를 가질 수 있습니다.

사용자 에이전트는 MAY 매니페스트 이미지 리소스와 관련된 이미지를 플랫폼의 시각적 스타일에 맞게 표시 전에 수정할 수 있습니다. 예를 들어, 모서리를 둥글게 하거나 특정 색으로 칠하는 등의 방식입니다. 개발자는 색상 변경이나 모서리 잘림으로 인해 중요한 정보가 손실되지 않도록 이러한 시나리오를 대비하여 이미지 리소스를 준비하는 것이 권장됩니다.

매니페스트 이미지 리소스 가져오기는 주어진 매니페스트 이미지 리소스 image와 애플리케이션 매니페스트 manifest를 사용하여, 이미지 리소스 가져오기 결과 또는 null을 반환합니다.

  1. 만약 manifest의 client가 null이면, null을 반환합니다.
    Note
  2. 새 request를 request로 둡니다.
  3. request의 URL을 image의 src로 설정합니다.
  4. request의 destination을 "image"로 설정합니다.
  5. request의 client를 manifest의 client로 설정합니다.
  6. image와 request로 이미지 리소스 가져오기 결과를 반환합니다.
Note

2.1 purpose 멤버

purpose 멤버는 고유한 공백으로 구분된 토큰들의 순서 없는 집합입니다. 허용되는 값은 아이콘 용도입니다.

manifest image resource가 icon으로 사용될 때, 개발자는 해당 이미지가 호스트 OS의 환경에서(즉, 더 나은 통합을 위해) 특수한 용도로 사용된다는 힌트를 줄 수 있습니다. 사용자 에이전트는 SHOULD NOT 명시된 아이콘 용도 외의 목적으로 아이콘을 사용해서는 안 됩니다.

Note

예를 들어, 용도가 "monochrome"인 아이콘은 배지나 단색 배경의 고정 아이콘 등, 애플리케이션의 풀컬러 런치 아이콘과 시각적으로 구별되는 용도로 사용될 수 있습니다. 사용자 에이전트는 purpose 멤버의 값을 힌트로 사용하여 purpose가 어디서 어떻게 표시될지 결정합니다. 개발자가 별도로 선언하지 않는 한, 사용자 에이전트는 아이콘을 어떠한 용도로도 사용할 수 있습니다.

아이콘 용도는 다음과 같습니다:

monochrome
사용자 에이전트는 단색 아이콘과 단색 채우기가 필요한 곳에 이 아이콘을 표시할 수 있습니다. 아이콘의 색 정보는 무시되고 알파 데이터만 사용됩니다. 이 아이콘은 사용자 에이전트가 임의의 단색 채우기 위에 마스크처럼 사용할 수 있습니다.
maskable
이미지는 아이콘 마스크와 안전 영역을 염두에 두고 디자인되었으며, 이 이미지의 안전 영역 외부 부분은 사용자 에이전트에 의해 무시되거나 마스킹 처리될 수 있습니다.
any (기본값)
사용자 에이전트는 purpose가 요구되지 않는 곳에 자유롭게 아이콘을 표시할 수 있습니다. 예를 들어, manifest image resource가 "any" 용도만 있다면 "monochrome"가 필요한 컨텍스트에서는 사용되지 않습니다.

아이콘 용도 목록은 리스트 « "monochrome", "maskable", "any" »입니다.

Note

한 아이콘에 여러 용도가 포함되어 있다면 그 어느 용도로도 사용할 수 있습니다. 명시된 용도 중 인식 가능한 것이 없다면 아이콘은 완전히 무시됩니다. 예를 들어, 아이콘에 "monochrome fizzbuzz"라는 용도가 있으면, "monochrome"는 유효한 용도이므로 단색 아이콘으로 사용할 수 있습니다. 하지만 "fizzbuzz"만 있으면 무시됩니다.

이미지의 용도를 결정하려면, 순서가 있는 맵 json이 주어졌을 때:

  1. 만약 json["purpose"]가 존재하지 않거나, json["purpose"]가 문자열이 아니라면:
    1. 집합 « "any" »를 반환한다.
  2. keywords를, ASCII 공백으로 분할한 json["purpose"]의 결과로 둔다.
  3. purposes를 새로운 집합으로 둔다.
  4. 각 keyword를 keywords에서 반복한다:
    1. icon purposes list에 keyword가 포함되지 않으면, continue.
    2. 그렇지 않으면, append를 사용하여 keyword를 purposes에 추가한다.
  5. purposes가 비어 있으면, failure를 반환한다.
  6. purposes를 반환한다.

2.2 콘텐츠 보안 정책

아이콘 이미지를 가져올 수 있는지에 대한 보안 정책은 매니페스트 소유 Document에 연결된 img-src 지시어 [CSP3]에 의해 결정됩니다.

2.3 아이콘 마스크와 안전 영역

일부 플랫폼은 고유의 아이콘 모양을 선호하지만, 웹 애플리케이션은 여러 플랫폼에서 동작해야 하므로 maskable 목적을 추가하여 아이콘에 사용자 에이전트가 마스크를 적용할 수 있음을 나타낼 수 있습니다. 이를 통해 플랫폼에서 아이콘이 일관성 있게 보이도록 하고, 플랫폼 곳곳에서 다양한 마스크와 배경색을 적용할 수 있습니다.

안전 영역은 maskable 아이콘 내에서 사용자 에이전트의 선택과 관계없이 항상 표시되는 영역입니다. 아이콘 중심에 위치한, 반지름이 아이콘 크기의 2/5(40%)인 원으로 정의됩니다. 아이콘이 정사각형이 아니라면 너비와 높이 중 작은 쪽을 기준으로 합니다.

Note

maskable 아이콘의 디자이너는 모든 중요한 부분이 안전 영역 안에 있도록 해야 합니다.

safe zone illustrated
Figure 1 안전 영역은 아이콘의 너비와 높이 중 작은 값의 2/5(40%) 반지름을 가진 중심 원입니다.

이 영역의 모든 픽셀은 모든 마스크에서 항상 보장됩니다. 안전 영역 밖의 픽셀은 적용된 마스크에 따라 보이지 않을 수도 있습니다.

사용자 에이전트는 임의 크기의 마스크를 적용할 수 있으며, 중심(안전 영역)에서 아이콘 크기의 2/5 이상 떨어진(최소 너비, 높이) 픽셀을 투명하게 만들 수 있습니다.

사용자 에이전트는 안전 영역 내의 픽셀을 투명하게 해서는 안 됩니다.

사용자 에이전트는 아이콘에 패딩을 추가하여 확대할 수 있습니다.

아이콘에 투명 픽셀이 있으면, 사용자 에이전트는 반드시 임의의 단색(예: 흰색) 위에 아이콘을 합성해야 합니다.

Note

maskable 아이콘에는 투명 픽셀 사용을 피하는 것이 좋습니다.

2.3.1 마스크 예시

Note

안전 영역 안에만 내용이 있으면 대부분의 아이콘은 상하좌우 약 10% 패딩(내용 없음 또는 배경 등)이 생깁니다. 모든 안전 영역 외부가 마스크 처리될 때 아이콘을 점검하는 것이 좋습니다.

2.3.1.1 "maskable" 목적 아이콘
An icon over a checkerboard background
Figure 2 이미지 투명 배경의 기본 이미지
An icon in a purple circle (40% of the size) over a yellow background
Figure 3 안전 영역 아이콘 크기 2/5(40%) 반지름의 원
2.3.1.2 마스크 예시
An icon inside a rounded yellow square on a purple background
Figure 4 둥근 사각형 Android
An icon inside an extremely rounded yellow square on a purple background
Figure 5 스퀴클 Android
An icon inside a rounded yellow circle on a purple background
Figure 6 원 Android
An icon inside a somewhat rounded yellow square on a purple background
Figure 7 둥근 사각형 iOS
An icon on a yellow background
Figure 8 풀블리드 Windows

2.4 단색 아이콘과 단색 채우기

일부 플랫폼은 아이콘을 단색 채우기로(한 가지 색상) 표시하도록 강제하며, 아이콘의 투명도만 매니페스트에서 지정할 수 있습니다. 여러 플랫폼에서 동작해야 하므로, monochrome 목적을 추가하여 아이콘에 사용자 에이전트가 색상을 지정할 수 있음을 나타낼 수 있습니다. 이렇게 하면 플랫폼에서 아이콘이 일관성 있게 보이고, 다양한 색상과 패딩을 적용할 수 있습니다.

monochrome 아이콘을 표시할 때, 사용자 에이전트는 픽셀의 빨강, 초록, 파랑 성분을 독립적으로 표시해서는 안 됩니다. 픽셀의 원래 알파값은 그대로, 빨강/초록/파랑 값은 사용자 에이전트가 임의로 선택하여 표시해야 합니다. 모든 픽셀에 같은 색 값을 사용하는 것이 권장됩니다.

Note

monochrome 아이콘의 디자이너는 모든 픽셀을 검정색으로 하고 투명도로 실루엣만 표현할 수 있습니다.

사용자 에이전트는 아이콘에 패딩을 추가해 확대할 수 있습니다.

사용자 에이전트는 투명 픽셀 뒤에 임의의 색상 배경을 추가할 수 있고, 배경이 아이콘과 충분한 대비를 갖도록 해야 합니다.

2.4.1 단색 아이콘 사용 예시

2.4.1.1 사용 예시
A black icon over a checkerboard background
Figure 9 이미지 색상이 없는 기본 이미지.
A dark gradient icon over a checkerboard background
Figure 10 그라데이션 채움 이미지가 그라데이션으로 채워짐.
A dark yellow icon over a light gray background
Figure 11 단색 채움과 패딩 매니페스트의 테마 색상으로 채워짐.

2.5 이미지 리소스 처리

이미지 리소스 처리는 list images, ordered map map, manifest URL 및 string member를 입력으로 받아 다음과 같이 동작합니다:

  1. imageResources를 새 리스트로 설정합니다.
  2. map[member]를 imageResources로 설정합니다.
  3. images가 리스트가 아니면, return.
  4. 각 potential image를 images에서 반복:
    1. image를 process an image resource from JSON을 potential image와 manifest URL로 실행한 결과로 설정합니다.
    2. image가 실패이면, continue.
    3. purposes를 이미지 목적 결정을 potential image에 실행한 결과로 설정합니다.
    4. purposes가 실패이면, continue.
    5. image["purpose"]를 purposes로 설정합니다.
    6. Append image를 imageResources에 추가합니다.

3. 바로가기 항목

각 바로가기 항목은 ordered map이며, 웹 앱 내의 주요 작업 또는 페이지로의 링크를 나타냅니다. 다음 멤버를 가집니다:

사용자 에이전트는 이러한 멤버를 사용하여 운영체제에서 웹 앱의 아이콘을 사용할 때 표시할 컨텍스트 메뉴를 구성할 수 있습니다. 사용자가 운영체제 메뉴에서 바로가기를 실행할 때, 사용자 에이전트는 실행해야 합니다 바로가기 실행.

3.1 name 멤버

바로가기 항목의 name 멤버는 string이며, 컨텍스트 메뉴에 사용자에게 일반적으로 표시되는 바로가기의 이름을 나타냅니다.

name 멤버는 지역화 가능한 멤버입니다.

3.2 short_name 멤버

바로가기 항목의 short_name 멤버는 string 타입이며, 바로가기 이름의 짧은 버전을 나타냅니다. 전체 이름을 표시할 공간이 부족할 때 사용됩니다.

short_name 멤버는 지역화 가능한 멤버입니다.

3.3 description 멤버

바로가기 항목의 description 멤버는 string 타입이며, 개발자가 바로가기에 대한 목적을 설명할 수 있도록 합니다. 사용자 에이전트는 이 정보를 접근성 기술에 노출할 수 있습니다.

description 멤버는 지역화 가능한 멤버입니다.

3.4 url 멤버

바로가기 항목의 url 멤버는 처리된 매니페스트의 범위 내에 있는 URL로, 관련 바로가기가 활성화될 때 열립니다.

3.5 icons 멤버

바로가기 항목의 icons 멤버는 다양한 컨텍스트에서 바로가기를 상징적으로 표현하는 이미지 목록입니다.

icons 멤버는 지역화 가능한 멤버입니다.

3.6 바로가기 실행

바로가기 항목 shortcut이 manifest와 함께 호출되면, 웹 애플리케이션 실행 단계를 manifest와 shortcut.url로 실행합니다.

3.7 바로가기 항목 처리

바로가기를 처리하려면, 순서가 있는 맵 item과 URL manifest URL, URL scope, 텍스트 방향 defaultDirection을 받는다:

  1. 다음 중 하나라도 해당된다면 failure를 반환한다:
  2. url을, 파싱 결과인 item["url"]에 manifest URL을 기준(base URL)으로 둔 결과로 둔다.
  3. url이 failure라면, failure를 반환한다.
  4. url이 scope scope 내부가 아니라면, failure 반환.
  5. shortcut을 ordered map «[ "url" → url, "name" → item["name"] ]»로 둔다.
  6. *_localized 텍스트 멤버 처리를 item, shortcut, "name_localized", defaultDirection을 전달하여 실행한다.
  7. "short_name"이 존재하고, item["short_name"]이 문자열이면, set을 사용해 shortcut["short_name"]에 item["short_name"]을 할당한다.
  8. *_localized 텍스트 멤버 처리를 item, shortcut, "short_name_localized", defaultDirection을 전달하여 실행한다.
  9. "description"이 존재하고, item["description"]이 문자열이면, set을 사용해 shortcut["description"]에 item["description"]을 할당한다.
  10. *_localized 텍스트 멤버 처리를 item, shortcut, "description_localized", defaultDirection을 전달하여 실행한다.
  11. 이미지 리소스 처리를 item["icons"], shortcut, manifest URL, "icons"를 전달하여 실행한다.
  12. *_localized 이미지 리소스 멤버 처리를 item, shortcut, "icons_localized", manifest URL을 전달하여 실행한다.
  13. shortcut을 반환한다.

4. 설치 가능한 웹 애플리케이션

어떤 웹사이트도 설치 가능한 웹 애플리케이션입니다.

사용자 에이전트는 최종 사용자가 웹 애플리케이션을 자신의 디바이스에 설치할 수 있는 방식을 제공할 수 있으며, 사용자가 매니페스트의 멤버가 적용된 새로운 최상위 브라우징 컨텍스트를 인스턴스화할 수 있게 합니다.

웹 애플리케이션이 설치되고 나면, 이를 설치된 웹 애플리케이션이라고 합니다. 즉, 매니페스트의 멤버 또는 그 기본값이 웹 애플리케이션의 최상위 브라우징 컨텍스트에 적용됩니다. 이것은 설치된 웹 애플리케이션이 전통적인 북마크와는 다르다는 점을 의미합니다. 전통적인 북마크에서 웹 페이지를 열면 매니페스트 속성들이 적용되지 않습니다.

Note

예를 들어, 설치를 지원하는 사용자 에이전트에서 웹 애플리케이션은 최종 사용자에게 네이티브 애플리케이션과 구분되지 않는 방식(예: 홈 화면, 런처, 시작 메뉴에 라벨이 붙은 아이콘으로 표시)으로 표시되고 실행될 수 있습니다. 웹 애플리케이션을 실행할 때, 매니페스트가 적용되어 사용자 에이전트가 최상위 브라우징 컨텍스트에 start URL이 로드되기 전에 적용됩니다. 이로 인해 사용자 에이전트는 매니페스트의 관련 값을 적용할 기회를 얻으며, 웹 애플리케이션의 display mode와 화면 방향을 변경할 수도 있습니다. 또는 사용자 에이전트가 웹 애플리케이션을 자체 북마크 목록에 설치할 수도 있습니다.

4.1 애플리케이션 이름

애플리케이션 이름은 name 또는 short_name 멤버에서 파생됩니다. 사용자 에이전트는 먼저 각 *_localized 멤버에서 지역화된 값을 해석해야 합니다.

name 멤버 또는 short_name 멤버가 없거나 비어 있거나 타입이 잘못된 경우, 사용자 에이전트는 name 멤버를 short_name의 대체로, 또는 short_name 멤버를 name의 대체로 사용할 수 있습니다.

name와 short_name 멤버가 모두 없거나 비어 있거나 타입이 잘못된 경우, 사용자 에이전트는 Document에서 적절한 대체 값을 찾을 수 있습니다(예: application-name을 name 또는 short_name 대신 사용). 또는, 사용자 에이전트는 플랫폼 규칙에 따라 기본 이름(예: "Untitled")을 지정해야 하며, 최종 사용자가 애플리케이션 이름을 직접 입력하도록 허용할 수도 있습니다.

name와 short_name 멤버가 모두 있는 경우, 구현체에서 사용 공간에 적합한 멤버를 선택합니다(예: 아이콘 아래 공간에는 short_name가 더 적합할 수 있음).

4.2 웹 애플리케이션 실행

운영 체제 또는 사용자 에이전트의 재량에 따라, 웹 애플리케이션 실행 단계를 처리된 매니페스트와 함께 실행한다.

Note

일반적으로 사용자가 홈 화면, 런처, 시작 메뉴 등 앱 실행 UI에서 설치된 웹 앱을 선택할 때 발생한다.

웹 애플리케이션 실행 단계는 다음 알고리즘에 의해 정의된다. 이 알고리즘은 처리된 매니페스트 manifest, 선택적 URL target URL, 선택적 POST 리소스 POST resource를 받아 애플리케이션 컨텍스트를 반환한다.

target URL이 주어졌다면, MUST manifest의 scope 내여야 한다.

다른 명세는 MAY 이 알고리즘의 단계를 자신만의 단계로 대체할 수 있다. 이 대체는 모든 웹 애플리케이션 실행 호출에 적용된다.

Note

이 알고리즘은 launch_handler 매니페스트 필드를 실험적으로 전체 웹 애플리케이션 실행 동작을 구성하도록 허용하기 위해 교체할 수 있습니다. 교체된 알고리즘은 기본적으로 새로운 애플리케이션 컨텍스트 생성을 호출하지만, 일부 조건 하에서 다르게 동작할 수 있습니다.

  1. 새로운 애플리케이션 컨텍스트 생성 단계를 manifest, target URL, POST resource를 전달하여 실행한 결과를 반환한다.

새로운 애플리케이션 컨텍스트 생성 단계는 다음 알고리즘에 의해 정의된다. 이 알고리즘은 처리된 매니페스트 manifest, 선택적 URL target URL, 선택적 POST 리소스 POST resource를 받아 애플리케이션 컨텍스트를 반환한다.

  1. target URL이 주어지지 않았다면, target URL을 start URL로 설정한다.
  2. traversable을 새로운 최상위 traversable 생성 단계를 target URL, POST resource와 함께 실행한 결과로 둔다.
  3. browsing context를 traversable의 액티브 브라우징 컨텍스트로 둔다.
  4. 적용을 manifest와 browsing context에 수행한다.
  5. browsing context를 반환한다.

4.3 프라이버시 및 보안 고려 사항

웹 애플리케이션을 설치할 수 있는 UI에서는 아이콘, 이름, start URL, origin 등 정보를 확인할 수 있도록 하는 것이 권장됩니다. 이는 최종 사용자가 웹 애플리케이션 설치 전에 정보를 확인하고, 필요시 수정할 수 있도록 하며, 다른 웹 앱을 모방하는지(예: 예상치 못한 아이콘/이름 사용) 판별할 기회를 제공합니다.

사용자 에이전트는 다른 애플리케이션이 시스템에 설치된 앱 목록을 파악하지 못하도록(권장됨) 해야 합니다(예: 캐시의 타이밍 공격 방지). 예를 들어, 설치 후 매니페스트에서 연결된 리소스(아이콘 등)를 사용자 에이전트 캐시에서 무효화하거나 일반 웹 탐색용 캐시와 별도의 캐시를 사용할 수 있습니다.

4.4 제거

사용자 에이전트는 설치된 웹 애플리케이션을 사용자가 제거할 수 있는 메커니즘을 제공해야 합니다.

제거 시점에, 애플리케이션과 관련된 기타 영구 데이터 및 설정(권한, 영구 저장소 등)을 사용자가 취소(revoke)할 기회를 제공하는 것이 권장됩니다.

6. 표시 모드

표시 모드는 웹 애플리케이션이 OS 내에서 어떻게 표시되는지를 나타냅니다(예: 전체화면 등). 표시 모드는 플랫폼의 UI 메타포와 기능에 대응하며, 실제 UI 규칙은 참고용이며 구현자가 해석에 자유를 갖습니다.

이 명세는 다음 표시 모드를 정의합니다:

fullscreen
브라우저 UI 요소를 숨기고, 사용 가능한 전체 화면을 모두 차지하여 웹 애플리케이션을 엽니다.
standalone
웹 애플리케이션을 독립 실행형 네이티브 앱처럼 보이고 동작하도록 엽니다. 별도 창, 런처 아이콘 등 포함. 이 모드에서 사용자 에이전트는 URL 바 등 표준 브라우저 UI를 제외하지만, 상태 바나 시스템 뒤로가기 버튼 등 시스템 UI는 포함할 수 있습니다.
minimal-ui
standalone과 비슷하지만, 최소한의 네비게이션 UI(뒤로, 앞으로, 새로고침, 주소 보기 등)를 제공합니다. 사용자 에이전트는 "공유", "인쇄" 등 플랫폼별 UI 요소도 추가할 수 있습니다.
browser (기본값)
플랫폼의 하이퍼링크 열기 규칙(예: 브라우저 탭, 새 창)에 따라 웹 애플리케이션을 엽니다.
Note

fullscreen 표시 모드는 Fullscreen API Standard와 독립적으로 동작합니다. 표시 모드는 브라우저 창의 전체화면 상태를, API는 뷰포트 내 요소의 전체화면을 제어합니다. 따라서 표시 모드가 fullscreen이어도 document.fullScreenElement는 null이고, fullscreenEnabled는 false일 수 있습니다.

manifest가 적용되어 최상위 browsing context에 적용되면, 유효한 display mode가 해당 최상위 browsing context의 적용된 display mode이다. 사용자 에이전트는 MAY 보안상의 이유로 적용된 display mode를 변경할 수 있다(예: 최상위 browsing context가 범위를 벗어나 navigate됨). 그리고/또는 사용자 에이전트는 MAY 사용자가 다른 display mode로 전환하는 수단을 제공할 수 있다.

display 멤버가 없거나, 유효한 display 멤버가 없으면, 사용자 에이전트는 browser display mode를 적용된 display mode로 사용한다. 따라서 사용자 에이전트는 MUST browser display mode를 지원해야 한다.

각 디스플레이 모드에는 폴백 체인(fallback chain)이 있는데, 이는 여러 디스플레이 모드의 목록입니다. 다음은 폴백 체인 목록입니다:

  1. browser는 «».
  2. minimal-ui는 « "browser" ».
  3. standalone은 « "minimal-ui", "browser" ».
  4. fullscreen은 « "standalone", "minimal-ui", "browser" ».

웹 앱이 선택한 디스플레이 모드를 결정하는 단계는 다음 알고리즘에 의해 정의됩니다. 이 알고리즘은 처리된 매니페스트 manifest를 받아 디스플레이 모드를 반환합니다.

  1. 처리 확장 포인트: 이 단계에서 독자적이거나 추가로 지원하는 디스플레이 모드를 처리합니다.
  2. 사용자 에이전트가 manifest["display"]를 지원하면, manifest["display"]를 반환합니다.
  3. 각 fallback_mode에 대해, manifest["display"]의 폴백 체인을 반복:
    1. 사용자 에이전트가 fallback_mode를 지원하면, fallback_mode를 반환합니다.
Note

위의 루프는 항상 값을 반환합니다. 그 이유는 browser가 모든 모드의 폴백 체인에 포함되고, 모든 사용자 에이전트는 browser 디스플레이 모드를 지원해야 하기 때문입니다.

디스플레이 모드 리스트는 리스트 « "fullscreen", "standalone", "minimal-ui", "browser" » 입니다.

사용자 에이전트는 웹 애플리케이션의 적용된 display mode를 display-mode 미디어 기능에 반영MUST해야 한다 [MEDIAQUERIES-5].

참고

사용자 에이전트는 manifest에 선언된 것이 반드시 아닌 적용된 display mode를 CSS 또는 JavaScript를 통해 접근할 수 있는 display-mode 미디어 기능을 통해 노출한다. 이 미디어 기능은 manifest가 적용되고 있지 않을 때 웹 페이지의 다른 display mode도 반영한다는 점에 유의하라. 예를 들어, 최종 사용자가 페이지를 fullscreen으로 전환하면, 사용자 에이전트는 이 변경을 display-mode 미디어 기능을 통해 CSS와 스크립트에 반영한다.

7. 개인정보 및 보안 고려사항

이 명세는 직접적으로 고가치 데이터를 다루지 않습니다. 하지만 설치된 웹 애플리케이션과 그 데이터는 "고가치"로 간주될 수 있습니다(특히 개인정보 관점에서).

매니페스트 포맷은 JSON이며 [UNICODE]를 사용해 인코딩됩니다. 그러므로 [JSON]과 [UNICODE-SECURITY]에 기술된 보안 고려사항이 적용됩니다. 또한, 개발자가 매니페스트에 임의/제약 없는 데이터를 포함하는 것을 막을 방법이 없으므로, 구현자들은 각자 특정 멤버 타입의 값에 대해 구현별 제한을 둘 필요가 있습니다. 예를 들어 서비스 거부 공격(DoS) 방지, 메모리 부족 문제 예방, 플랫폼 특정 제한 우회 등의 목적이 있을 수 있습니다.

웹 애플리케이션은 일반적으로 ECMAScript, HTML, CSS 파일 및 기타 미디어를 포함하며, 샌드박스 환경에서 실행됩니다. 따라서 구현자들은 지원하는 타입에 대한 보안 영향을 인지해야 합니다. 특히, 다음 명세들에서 설명하는 보안 고려사항을 반드시 참고해야 합니다: [CSS-MIME], [ECMAScript-MIME], [HTML].

웹 애플리케이션은 로컬 디바이스와 원격 호스트 모두와 동시 상호작용할 수 있는 콘텐츠를 포함할 수 있으므로, 구현자는 개인정보가 원격 호스트에 노출되는 것에 대한 영향을 고려해야 합니다. 방어 및 심층 보호 조치는 구현 책임이며, 본 명세에서 구체적으로 규정하지 않습니다. 하지만 이러한 조치 설계 시 사용자가 정보 공유를 인지할 수 있도록 하고, 권한 취소 인터페이스에 쉽게 접근할 수 있게 하는 것이 바람직합니다.

본 명세는 매니페스트의 일부 멤버에서 URL 선언을 허용하므로, 구현자는 [URL] 명세에서 논의한 보안 고려사항도 참고해야 합니다. 매니페스트에 포함된 IRIs 및 IDNA 주소를 표시하려는 구현체는 [UNICODE-SECURITY]에서 제시한 보안 권고를 따르는 것이 강력히 권장됩니다.

개발자는 [CSP3] 명세 전반에서 논의된 보안 고려사항을 인지해야 하며, 특히 data:를 매니페스트 인라인 목적으로 유효한 소스로 허용하는 것과 관련해 주의해야 합니다. 이를 허용하면 매니페스트를 문서 내에 직접 포함시켜 XSS 공격이 가능해질 수 있으므로, 완전히 피하는 것이 바람직합니다.

웹 애플리케이션을 설치할 수 있는 UI는 아이콘, 이름, start URL, 오리진 등 정보를 확인할 수 있도록 하는 것이 권장됩니다. 이는 최종 사용자가 설치 전 웹 애플리케이션의 정보를 확인하고, 필요시 수정할 수 있도록 하기 위함입니다. 또한, 웹앱이 다른 앱을 모방하는지(예: 예상치 못한 아이콘/이름 사용) 판별할 기회를 제공합니다.

사용자 에이전트는 다른 애플리케이션이 시스템에 설치된 앱 목록을 파악하지 못하도록(권장됨) 해야 합니다(예: 캐시의 타이밍 공격 방지). 예를 들어, 설치 후 매니페스트에서 연결된 리소스(아이콘 등)를 사용자 에이전트 캐시에서 무효화하거나, 일반 웹 탐색용 캐시와 별도의 캐시를 사용할 수 있습니다.

바로가기 url이 브라우저 외부에서 앱이 실행된 것처럼 보이게(예: "url": "/task/?from=homescreen") 구성될 수 있습니다. 또한 개발자가 url에 서버 할당 UUID와 같이 사용자를 고유하게 식별할 수 있는 문자열을 인코딩할 수도 있습니다. 이는 지문/개인정보에 민감한 정보이며, 사용자가 인지하지 못할 수 있습니다.

웹 애플리케이션이 실행 중일 때, 사용자 에이전트는 최종 사용자가 오리진, 시작/현재 URL, 승인된 권한, 아이콘 등 일반 정보를 확인할 수 있는 수단을 제공하는 것이 권장됩니다. 이러한 정보 노출 방식은 구현자 재량입니다.

또한, 매니페스트를 적용할 때 display mode가 "browser"가 아닌 경우, 사용자 에이전트는 사용자가 웹 브라우저의 일반 탐색 컨텍스트를 벗어났음을 명확히 알려주는 것이 권장됩니다. 이상적으로는 앱 실행 또는 전환이 호스트 플랫폼에서 다른 애플리케이션을 실행/전환하는 방식과 일관되게 수행되어야 합니다. 예를 들어, 길고 명확한 애니메이션 전환, "애플리케이션 X 실행 중" 음성 안내 등이 있습니다.

display 멤버는 오리진이 사용자 에이전트의 네이티브 UI 일부를 제어할 수 있게 합니다. 전체화면을 차지한 후, 다른 앱의 UI를 흉내낼 수도 있습니다. 이는 'display-mode' 미디어 특성 [MEDIAQUERIES-5]을 통해서도 가능하며, 스크립트는 이를 통해 웹앱의 표시 모드를 알 수 있습니다.

A. IANA 고려사항

mime 타입 application/manifest+json 은 애플리케이션 매니페스트 미디어 타입입니다. mime 타입과 .webmanifest 파일 확장자는 인터넷 네임버 할당 기관(IANA)에 등록되어 있습니다.

A.1 미디어 타입 등록

매니페스트가 전송되는 프로토콜이 [MIME-TYPES] 명세(예: HTTP)를 지원한다면, 매니페스트에 애플리케이션 매니페스트 미디어 타입을 지정하는 것이 권장됩니다.

타입 이름:
application
서브타입 이름:
manifest+json
필수 파라미터:
N/A
선택 파라미터:
N/A
인코딩 고려사항:
application/json과 동일 ([RFC7159] section 8.1)
개인정보 및 보안 고려사항:
7. 개인정보 및 보안 고려사항 참고.
이 MIME 타입을 사용하는 애플리케이션:
웹 브라우저
추가 정보:
매직 넘버:
N/A
파일 확장자:
.webmanifest
매킨토시 파일 타입 코드:
TEXT
추가 정보 문의 담당자:
Web Applications Working Group에 문의 가능. public-webapps@w3.org.
의도된 사용 범위:
COMMON
사용 제한:
없음
작성자:
W3C Web Applications Working Group.
변경 관리:
W3C.

B. 적합성

비규범으로 표시된 섹션뿐 아니라, 이 명세서의 모든 저작 지침, 다이어그램, 예시, 노트는 비규범적입니다. 그 외 모든 내용은 규범적입니다.

이 문서에서 MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, SHOULD, SHOULD NOT와 같은 키워드는 BCP 14 [RFC2119] [RFC8174] 에서 설명된 대로 해석되어야 하며, 반드시 대문자로 표기된 경우에만 해당합니다.

이 명세에 적합성을 주장할 수 있는 제품 클래스는 하나뿐입니다: user agent입니다.

Note

이 명세는 주로 웹 브라우저를 대상으로 하지만, 다른 소프트웨어도 적합하게 구현할 수 있습니다. 예를 들어, 검색 엔진이나 크롤러는 매니페스트를 찾아 처리하여 설치 가능한 웹앱 카탈로그를 구축할 수 있습니다.

B.1 확장성

이 섹션은 비규범적입니다.

이 명세는 확장 가능하도록 설계되었습니다. 다른 명세들에서 매니페스트에 새로운 멤버를 정의하는 것이 권장됩니다. 단, 이 경우 반드시 본 명세서의 컨벤션을 따르십시오. 특히, processing extension-point를 이용하여 매니페스트 처리 단계에 연결하세요. 또한, 본 명세서에서 제시한 방식대로 해당 멤버의 처리 단계를 명확히 명시해야 합니다. 이렇게 하면 플랫폼의 일관성을 유지할 수 있습니다.

커뮤니티가 확장 기능을 쉽게 찾을 수 있도록 Extensions Registry에 추가해 주십시오.

새로운 멤버를 지정할 때, 본 명세에서 정의된 내용을 오버라이드하거나 monkey patch하지 마십시오. 또한, 멤버가 다른 멤버보다 먼저 혹은 나중에 처리된다고 가정하지 마십시오. 새로운 멤버와 그 처리 과정은 원자적이고 독립적으로 유지해야 합니다. 구현체는 인식하지 못하거나 지원하지 않는 멤버를 자유롭게 무시할 수 있습니다.

에디터가 임시로 구현체를 돕기 위해 이 명세를 패치하려면, 이슈를 등록하여 커뮤니티에 알리십시오.

B.1.1 독점 매니페스트 멤버

이 섹션은 비규범적입니다.

독점 확장은 바람직하지 않지만, 현실적으로 피할 수 없습니다. 사용자 에이전트가 본 문서에 정의되지 않은 매니페스트 JSON 멤버를 해석하기로 선택한다면 주의해서 구현해야 합니다.

독점 확장을 추가하는 구현자는 표준이 될 수 있을지 고려해야 합니다(즉, 다른 플랫폼의 두 번째 사용자 에이전트도 해당 멤버를 쓸 수 있는지). 그렇다면 API를 벤더 중립적으로 설계하고 표준으로 제안해주십시오. 새 멤버가 진정으로 독점적이라면, 해당 에코시스템의 약어로 접두어를 붙여 이름 충돌을 피하십시오.

나중에 표준이 되면 제거할 목적의 벤더 프리픽스(접두어)는 사용하지 마십시오(영구적으로 남는 경우가 많음). 지금과 미래 모두 합리적인 프리픽스만 사용하십시오.

독점 확장도 Extensions Registry에 추가해주십시오. 이를 통해 커뮤니티가 벤더/웹 커뮤니티가 정의하고 문서화한 확장을 추적할 수 있습니다. 주기적으로 표준화 여부를 검토합니다.

아래는 가상의 독점 확장 예시입니다.

Example 13: 독점 확장 예시 
{
  ...
  "kpl_fancy_feature": "some/url/img",
  "gmpc_awesome_thing": { ... },
  "blitzly_site_verification": "KEY_9864D0966935"
  ...
}
Note

이 예시에서는 일부 외부 사이트나 서비스의 이름(가상)이 접두어로 사용되었습니다. 이는 브라우저나 브라우저 벤더의 이름이 아니라, 독점 서비스의 접두어입니다.

C. 애플리케이션 정보

이 섹션은 비규범적입니다.

웹 애플리케이션 매니페스트의 여러 멤버는 디지털 스토어, 설치 대화상자, 또는 웹앱이 마케팅/배포되는 기타 영역에서 어떻게 표시될지를 위한 추가 메타데이터를 제공합니다. 이러한 요구를 더 잘 지원하기 위해, 아래 멤버들은 Web App Manifest - Application Information로 이동되었습니다:

E. JSON 스키마

이 섹션은 비규범적입니다.

매니페스트 문서 검증에 관심있는 개발자는 매니페스트 형식용 비공식 JSON 스키마를 schemastore.org에서 확인할 수 있습니다. 이 스키마는 Apache 2.0으로 라이선스되며, Mads Kristensen가 관리합니다. 문제를 발견하면 이슈 등록 바랍니다(GitHub의 SchemaStore 저장소).

Note: 웹 매니페스트 JSON 스키마

F. 국제화

이 섹션은 비규범적입니다.

저자는 매니페스트 콘텐츠를 다음 중 한 방법으로 지역화하는 것이 기대됩니다:

매니페스트 내 지역화 값:
작성자는 로컬라이즈된 값을 로컬라이즈 가능한 멤버의 매니페스트에 제공할 수 있습니다. 사용자 에이전트는 모든 로컬라이즈된 값을 호스트 운영체제에 전달합니다. 사용자가 OS 레벨에서 로케일(locale)을 변경하면, OS는 설치된 웹 애플리케이션의 업데이트된 로컬라이즈 값을 표시할 수 있습니다.
언어 동적 설정:
예를 들어, 사용자의 선호 언어를 묻고 그에 따라 문서에 연결된 매니페스트 링크를 동적으로 추가/교체할 수 있습니다(예: "manifest.php?lang=fr"와 같이).
서버에서 콘텐츠 협상, 지오타게팅 등 사용:
웹앱을 호스팅하는 서버는 지오타게팅이나 콘텐츠 협상(예: HTTP "Accept-Language" 헤더 [RFC9110], 또는 커스텀 HTTP 헤더)으로 사용자의 언어를 미리 결정할 수 있습니다.

위 방법을 고려할 때, 사용자의 언어 선호도는 개인정보와 관련되어 있으므로 주의가 필요합니다: 사용자가 웹앱에 명시적으로 언어 선호도를 지정한 경우(단순히 UA 기본 언어 설정 사용이 아님), 이를 네트워크상에서 평문으로 전송하는 것은 부적절합니다. 이는 사용자의 개인정보를 노출시키기 때문입니다. 따라서 [TLS]를 사용하여 웹앱의 감시 위험을 줄일 것을 권장합니다([RFC7258]).

G. 사용 사례 및 요구사항

본 문서는 설치 가능한 웹앱의 사용 사례 및 요구사항을 다루고자 합니다.

H. 이슈 요약

이 명세서에는 이슈가 없습니다.

I. 변경 로그

이 섹션은 비규범적입니다.

아래는 First Public Working Draft 이후 주요 변경 사항입니다:

J. 감사의 글

이 섹션은 비규범적입니다.

본 문서는 [HTML] 명세의 라이선스에 따라 해당 명세의 텍스트를 재사용했습니다.

Dave Raggett와 Dominique Hazael-Massieux는 HTML5Apps 프로젝트를 통해 이 명세에 기여했습니다.

아이콘 예제 이미지에 대해 Claudio Gomboli에게 감사드립니다.

Indiana University Bloomington의 보안 연구자들은 범위 밖 네비게이션과 관련된 잠재적 위험을 보고하여 이 명세에 기여했습니다.

K. 색인

K.1 이 명세에서 정의한 용어

K.2 참조로 정의된 용어

L. 참고문헌

L.1 규범 참고문헌

[accname-1.2]
접근 가능한 이름과 설명 계산 1.2. Bryan Garaventa; Melanie Sumner. W3C. 2026년 4월 30일. W3C 작업 초안. URL: https://www.w3.org/TR/accname-1.2/
[BCP47]
언어 식별을 위한 태그. A. Phillips, Ed.; M. Davis, Ed. IETF. 2009년 9월. 최상의 현재 실천. URL: https://www.rfc-editor.org/rfc/rfc5646
[CSP3]
콘텐츠 보안 정책 레벨 3. Mike West; Antonio Sartori. W3C. 2026년 5월 5일. W3C 작업 초안. URL: https://www.w3.org/TR/CSP3/
[css-color-4]
CSS 색상 모듈 레벨 4. Tab Atkins Jr.; Chris Lilley; Lea Verou. W3C. 2026년 5월 2일. CRD. URL: https://www.w3.org/TR/css-color-4/
[CSS-MIME]
text/css 미디어 타입. H. Lie; B. Bos; C. Lilley. IETF. 1998년 3월. 정보 제공. URL: https://www.rfc-editor.org/rfc/rfc2318
[css-syntax-3]
CSS 구문 모듈 레벨 3. Tab Atkins Jr.; Simon Sapin. W3C. 2021년 12월 24일. CRD. URL: https://www.w3.org/TR/css-syntax-3/
[dom]
DOM 표준. Anne van Kesteren. WHATWG. Living Standard. URL: https://dom.spec.whatwg.org/
[ECMA-402]
ECMAScript 국제화 API 사양. Ecma International. URL: https://tc39.es/ecma402/
[ECMAScript-MIME]
스크립팅 미디어 타입. B. Hoehrmann. IETF. 2006년 4월. 정보 제공. URL: https://www.rfc-editor.org/rfc/rfc4329
[fetch]
Fetch 표준. Anne van Kesteren. WHATWG. Living Standard. URL: https://fetch.spec.whatwg.org/
[HTML]
HTML 표준. Anne van Kesteren; Domenic Denicola; Dominic Farolino; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[image-resource]
이미지 리소스. Aaron Gustafson; Rayan Kanso; Marcos Caceres. W3C. 2021년 6월 4일. W3C 작업 초안. URL: https://www.w3.org/TR/image-resource/
[infra]
Infra 표준. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/
[JSON]
자바스크립트 객체 표기법 (JSON) 데이터 교환 형식. T. Bray, Ed. IETF. 2017년 12월. 인터넷 표준. URL: https://www.rfc-editor.org/rfc/rfc8259
[MEDIAQUERIES-5]
미디어 쿼리 레벨 5. Tab Atkins Jr.; Florian Rivoal; Daniel Libby; Luke Warlow. W3C. 2026년 2월 19일. W3C 작업 초안. URL: https://www.w3.org/TR/mediaqueries-5/
[MIME-TYPES]
다목적 인터넷 메일 확장 (MIME) 파트 2: 미디어 타입. N. Freed; N. Borenstein. IETF. 1996년 11월. 초안 표준. URL: https://www.rfc-editor.org/rfc/rfc2046
[permissions]
권한. Marcos Caceres; Mike Taylor. W3C. 2025년 10월 6일. W3C 작업 초안. URL: https://www.w3.org/TR/permissions/
[RFC2119]
RFC에서 요구 사항 수준을 나타내는 데 사용하는 핵심 단어. S. Bradner. IETF. 1997년 3월. 최상의 현재 실천. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC7159]
자바스크립트 객체 표기법 (JSON) 데이터 교환 형식. T. Bray, Ed. IETF. 2014년 3월. 제안된 표준. URL: https://www.rfc-editor.org/rfc/rfc7159
[RFC8174]
RFC 2119의 대소문자 혼동에 관한 명확성. B. Leiba. IETF. 2017년 5월. 최상의 현재 실천. URL: https://www.rfc-editor.org/rfc/rfc8174
[SCREEN-ORIENTATION]
화면 방향. Marcos Caceres. W3C. 2025년 10월 21일. W3C 작업 초안. URL: https://www.w3.org/TR/screen-orientation/
[UAX9]
유니코드 양방향 알고리즘. Manish Goregaokar मनीष गोरेगांवकर; Robin Leroy. 유니코드 재단. 2025년 8월 13일. 유니코드 표준 부록 #9. URL: https://www.unicode.org/reports/tr9/tr9-51.html
[UNICODE]
유니코드 표준. 유니코드 재단. URL: https://www.unicode.org/versions/latest/
[UNICODE-SECURITY]
유니코드 보안 고려사항. Mark Davis; Michel Suignard. 유니코드 재단. 2014년 9월 19일. 유니코드 기술 보고서 #36. URL: https://www.unicode.org/reports/tr36/tr36-15.html
[URL]
URL 표준. Anne van Kesteren. WHATWG. Living Standard. URL: https://url.spec.whatwg.org/
[UTS55]
유니코드 소스 코드 처리. Robin Leroy; Mark Davis. 유니코드 재단. 2024년 1월 29일. 유니코드 기술 표준 #55. URL: https://www.unicode.org/reports/tr55/tr55-5.html

L.2 비규범 참고문헌

[FULLSCREEN]
전체 화면 API 표준. Philip Jägenstedt. WHATWG. Living Standard. URL: https://fullscreen.spec.whatwg.org/
[i18n-glossary]
국제화 용어집. Richard Ishida; Addison Phillips. W3C. 2024년 10월 17일. W3C 워킹 그룹 노트. URL: https://www.w3.org/TR/i18n-glossary/
[manifest-app-info]
웹 앱 매니페스트 - 애플리케이션 정보. Aaron Gustafson. W3C. 2023년 8월 21일. W3C 워킹 그룹 노트. URL: https://www.w3.org/TR/manifest-app-info/
[mimesniff]
MIME 스니핑 표준. Gordon P. Hemsley. WHATWG. Living Standard. URL: https://mimesniff.spec.whatwg.org/
[RFC7258]
광범위한 모니터링은 공격이다. S. Farrell; H. Tschofenig. IETF. 2014년 5월. 베스트 커런트 프랙티스. URL: https://www.rfc-editor.org/rfc/rfc7258
[RFC8246]
HTTP Immutable Responses. P. McManus. IETF. 2017년 9월. 제안 표준. URL: https://httpwg.org/specs/rfc8246.html
[RFC9110]
HTTP 시맨틱스. R. Fielding, Ed.; M. Nottingham, Ed.; J. Reschke, Ed. IETF. 2022년 6월. 인터넷 표준. URL: https://httpwg.org/specs/rfc9110.html
[SERVICE-WORKERS]
Service Workers Nightly. Monica CHINTALA; Yoshisato Yanagisawa. W3C. 2026년 4월 9일. CRD. URL: https://www.w3.org/TR/service-workers/
[TLS]
전송 계층 보안(TLS) 프로토콜 버전 1.2. T. Dierks; E. Rescorla. IETF. 2008년 8월. 제안 표준. URL: https://www.rfc-editor.org/rfc/rfc5246
[webidl]
Web IDL 표준. Edgar Chen; Timothy Gu. WHATWG. Living Standard. URL: https://webidl.spec.whatwg.org/