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

W3C 워킹 드래프트

이 문서에 대한 자세한 내용
이 버전:
https://www.w3.org/TR/2026/WD-appmanifest-20260813/
최신 공식 버전:
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라고 가정하면:

  • 첫 번째 바로 가기는 "나중에 재생"이라는 텍스트로 표시된다. 운영 체제가 상황에 맞는 메뉴 항목의 아이콘을 지원하고 해당 용도의 SVG 이미지도 지원하는 경우, 사용자 에이전트는 텍스트 옆에 https://example.com/icons/play-later.svg를 표시한다. 실행되면 사용자 에이전트는 새로운 최상위 탐색 가능 항목을 인스턴스화하고 https://example.com/play-later로 탐색한다.
  • 두 번째 바로 가기는 "구독"이라는 텍스트로 표시된다. 실행되면 사용자 에이전트는 새로운 최상위 탐색 가능 항목을 인스턴스화하고 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" 등은 모두 범위 내에 있지만, "/elsewhere/"와 루트 "/"에 있는 모든 것은 "범위 밖"이므로 매니페스트가 해당 경로의 문서에는 적용되지 않는다. 하나의 범위 경로만 지원된다. 기술 세부 사항은 5. 탐색 범위를 참조한다.

매니페스트를 적용한다는 것은 매니페스트에서 발견된 표시 방식에 영향을 미치는 모든 멤버가 효력을 발휘한다는 뜻이다. 예를 들면 display "fullscreen"이나 특정 화면 방향을 적용하는 경우이다. 애플리케이션이 범위 내 URL로 탐색되는 동안 브라우저는 계속 매니페스트를 적용한다. 그러나 웹 애플리케이션을 "범위 밖"으로 탐색하면 매니페스트가 더 이상 적용되지 않으며 브라우저는 자체 기본값을 적용한다. 그 결과 예를 들어 애플리케이션이 더 이상 전체 화면으로 표시되지 않고 브라우저 탭에 일반 웹 페이지로 표시된다. 범위 안팎으로 탐색되는 웹 페이지를 처리하는 방법은 구현자가 결정한다. 기술 세부 사항은 1.17.5 매니페스트 적용을 참조한다.

마지막으로 사용자가 출처 내 어느 문서에서든 웹 애플리케이션을 설치할 수 있으므로 매니페스트에 항상 scope 멤버를 선언하는 것이 좋다. scope 멤버가 매니페스트에 없으면 start_url 멤버의 경로를 대체 값으로 사용한다. 또한 start_url 멤버도 없으면 웹 애플리케이션을 설치한 문서 URL을 범위로 사용한다. 예상치 못한 탐색 동작을 방지하기 위해 작성자는 항상 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 열거형의 값이며, 이 명세에서는 이를 방향 값이라고 한다 (즉, "any", "natural", "landscape", "portrait", "portrait-primary", "portrait-secondary", "landscape-primary", "landscape-secondary").

사용자 에이전트가 orientation 멤버의 값을 기본 화면 방향으로 지원하는 경우, 해당 값은 웹 애플리케이션의 수명 동안 기본 화면 방향으로 사용된다 (런타임에 다른 수단으로 재정의되지 않는 한). 이는 방향 잠금이 해제될 때마다 사용자 에이전트가 방향을 기본 화면 방향으로 반드시 되돌려야 함을 의미한다 [SCREEN-ORIENTATION]. 또는 최상위 탐색 가능 항목이 탐색될 때도 마찬가지이다.

참고

명세는 [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 멤버는 문자열이며, 애플리케이션의 식별자를 나타낸다. 식별자는 URL 형식이며, 시작 URL과 동일 출처이다.

식별자는 사용자 에이전트가 애플리케이션을 전역적으로 고유하게 식별하는 데 사용된다. 사용자 에이전트가 이미 설치된 애플리케이션에 대응하지 않는 식별자를 가진 매니페스트를 발견하면, 사용자 에이전트에 권고되는 동작은 그 매니페스트를 별개의 애플리케이션에 대한 설명으로 취급하는 것이다. 이는 다른 애플리케이션과 동일한 URL에서 제공되는 경우에도 마찬가지이다. 사용자 에이전트가 manifest["id"]를 같음으로 비교할 때(프래그먼트 제외를 선택적으로 true로 설정) 비교 대상인 식별자가 이미 설치된 애플리케이션의 것인 매니페스트를 발견하면, 사용자 에이전트에 권고되는 동작은 이를 이 매니페스트가 이미 설치된 애플리케이션의 매니페스트를 대체하며 별개의 애플리케이션이 아니라는 신호로 사용하는 것이다. 이는 이전에 본 URL과 다른 URL에서 제공되는 경우에도 마찬가지이다.

참고: 프래그먼트를 제외하는 것이 모범 사례이다
참고

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

참고

식별자는 URL처럼 처리되지만 탐색할 수 있는 리소스를 가리키지 않으므로 범위 내에 있을 필요가 없다.

처리할 것은 id 멤버이며, 순서 있는 맵 json과 순서 있는 맵 manifest가 주어지면:

  1. manifest["id"]를 manifest["start_url"]로 설정한다.
  2. json["id"]의 타입이 문자열이 아니면 반환한다.
  3. json["id"]가 빈 문자열이면 반환한다.
  4. base origin을 manifest["start_url"]의 출처로 둔다.
  5. id를 다음 구문 분석 결과로 둔다. 대상은 json["id"]이며, base origin을 기본 URL로 사용한다.
  6. id가 실패이면 반환한다.
  7. id가 동일 출처인지 manifest["start_url"]과 비교하고, 그렇지 않으면 반환한다.
  8. id의 프래그먼트를 null로 설정한다.
  9. manifest["id"]를 id로 설정한다.

1.12 theme_color 멤버

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

사용자 에이전트가 theme_color 멤버의 값을 기본 테마 색상으로 따르는 경우, 해당 색상은 매니페스트가 적용된 모든 최상위 탐색 가능 항목의 테마 색상으로 사용된다. 그러나 사용자 에이전트는 애플리케이션 컨텍스트의 매니페스트 범위 내에 있는 문서의 URL에 meta 요소가 포함되어 있고 해당 요소의 name 속성이 "theme-color"인 경우 기본 테마 색상을 재정의할 수 있다. 그러나 사용자 에이전트는 애플리케이션이 이러한 문서를 제어할 수 없으므로, 문서의 URL이 범위 내에 있지 않은 경우, meta 요소의 name 속성이 "theme-color"이더라도 이를 통해 기본 테마 색상을 재정의해서는 안 된다.

사용자 에이전트는 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 멤버

현지화 가능 멤버는 매니페스트에서 현지화할 수 있는 멤버이다. 각 현지화 가능 멤버는 매니페스트에서 이에 대응하는 *_localized 멤버를 가지며, 여기서 *는 멤버 이름을 나타낸다.

언어 맵은 키가 순서 있는 맵이며, 그 키는 언어 태그이고 값은 현지화된 값이다. 현지화된 값은 키로 지정된 언어로 현지화된 콘텐츠이다.

현지화 가능 멤버에 할당된 값은 기본 표현이다. *_localized 멤버에는 언어 맵이 포함되며, 이 맵은 현지화된 값을 지정된 현지화 가능 멤버에 대해 애플리케이션에서 정의한다. 사용자 에이전트에 권고되는 동작은 사용자의 현지화 설정을 사용하여 현지화된 값 중 언어 태그 키가 사용자의 선호도와 가장 잘 일치하는 값을 선택하는 것이다. 이러한 현지화된 값을 사용할 수 없는 경우 기본 표현을 사용한다.

1.15.1 텍스트 값의 지역화

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

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

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

문자열이 사용되거나, dir 멤버가 현지화된 텍스트 객체에 없는 경우 기본 방향(dir 멤버, 매니페스트의 멤버)가 적용된다.

참고

문자열을 사용하는 경우나 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를 순서 있는 맵으로 둔다.
  2. localizedValue가 문자열이면, 앞뒤 ASCII 공백을 제거한다: localizedValue. 그런 다음 설정한다: normalizedValue["value"]를 localizedValue로.
  3. localizedValue가 순서 있는 맵이면:
    1. "value" 항목이 존재하는 localizedValue에서 localizedValue["value"]가 문자열이면, 앞뒤 ASCII 공백을 제거한다: localizedValue["value"]. 그런 다음 설정한다: normalizedValue["value"]를 localizedValue["value"]로.
    2. "lang" 항목이 존재하는 localizedValue에서 localizedValue["lang"]이 문자열이면, 앞뒤 ASCII 공백을 제거한다: localizedValue["lang"]. 그런 다음 설정한다: normalizedValue["lang"]을 localizedValue["lang"]으로.
    3. "dir" 항목이 존재하는 localizedValue에서 localizedValue["dir"]이 문자열이면:
      1. 앞뒤 ASCII 공백을 제거한다: localizedValue["dir"].
      2. 텍스트 방향 목록이 다음을 포함하면: localizedValue["dir"], 설정한다: normalizedValue["dir"]을 localizedValue["dir"]로.
  4. "value" 항목이 존재하지 않는 normalizedValue이면 반환한다.
  5. "lang" 항목이 존재하지 않는 normalizedValue이면, 설정한다: normalizedValue["lang"]을 defaultLanguageTag로.
  6. "dir" 항목이 존재하지 않는 normalizedValue이면, 설정한다: normalizedValue["dir"]을 defaultDirection으로.
  7. IsStructurallyValidLanguageTag를 normalizedValue["lang"]으로 호출한 결과 또는 IsStructurallyValidLanguageTag를 defaultLanguageTag로 호출한 결과 중 하나가 false를 반환하면 반환한다.
  8. 설정한다: 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 내 항목에 대해, 사용자 에이전트에 권고되는 동작은 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 매니페스트 적용

처리된 매니페스트는 적용된다. 이는 최상위 탐색 가능 항목에 매니페스트의 멤버가 최상위 탐색 가능 항목의 표시 및/또는 동작에 영향을 미친다는 의미이다. 최상위 탐색 가능 항목이 생성될 때마다 사용자 에이전트는 탐색이 시작되기 전에 매니페스트를 적용할 수 있다.

사용자 에이전트는 기존 최상위 탐색 가능 항목에도 매니페스트를 적용할 수 있다. 활성 문서의 URL이 매니페스트의 범위 내에 있으면, 기존 최상위 탐색 가능 항목은 애플리케이션 컨텍스트가 된다. URL이 범위 내에 있지 않으면, 그 결과로 나타나는 동작은 구현에 따라 정의된다.

참고
참고

매니페스트가 적용된 최상위 탐색 가능 항목을 애플리케이션 컨텍스트라고 한다.

처리된 매니페스트는 최상위 탐색 가능 항목에서 적용 해제될 수도 있다. 이 경우 최상위 탐색 가능 항목은 더 이상 애플리케이션 컨텍스트가 아니다.

참고

사용자 에이전트가 딥 링크로 탐색하도록 요청받은 결과로 애플리케이션 컨텍스트가 생성된 경우, 사용자 에이전트는 historyHandling을 "replace"로 설정하여 즉시 딥 링크로 탐색해야 한다. 그렇지 않고 애플리케이션 컨텍스트가 생성된 경우, 사용자 에이전트는 historyHandling을 "replace"로 설정하여 즉시 시작 URL로 탐색해야 한다.

참고

1.17.6 매니페스트 업데이트

manifest 링크 관계에 지정된 대로, 매니페스트는 페이지를 로드할 때마다 가져오고 처리된다. 매니페스트 처리가 성공하면 사용자 에이전트는 업데이트된 매니페스트를 애플리케이션과 연결된 현재 및 향후의 모든 애플리케이션 컨텍스트에 적용할 수 있다.

사용자 에이전트는 src 멤버가 변경된 경우 매니페스트 이미지 리소스가 업데이트된 것으로 간주해야 한다. src가 변경되지 않은 경우에도 사용자 에이전트는 일부 상황에서 이미지를 다운로드하고 시각적 차이가 있는지 확인할 수 있다.

참고: 아이콘 메타데이터 변경

업데이트를 위해 다음 멤버는 설치 중 및 실행 화면에 표시되므로 보안에 민감한 멤버이다.

  1. short_name 및 short_name_localized의 현지화된 표현,
  2. icons 및 icons_localized의 현지화된 표현,
  3. name 및 name_localized의 현지화된 표현.

매니페스트의 다른 모든 멤버는 보안에 민감하지 않은 멤버로 간주된다.

보안에 민감한 업데이트는 보안에 민감한 멤버에 대한 업데이트이다. 이에 대응하여 보안에 민감하지 않은 업데이트는 보안에 민감하지 않은 멤버에 대한 업데이트이다.

매니페스트 이미지 리소스 유형의 업데이트된 보안에 민감한 멤버(예: icons)를 검토할 때, 사용자 에이전트는 이미지가 시각적으로 크게 다르지 않다고 판단하면 이를 보안에 민감하지 않은 업데이트로 간주할 수 있다.

사용자 에이전트는 모든 보안에 민감하지 않은 업데이트를 즉시 적용해야 한다.

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

참고: 업데이트가 제시될 때 표시되는 사용자 선택 사항의 예

보안에 민감한 멤버는 방향과 관계없이 [UTS55]에 설명된 대로 양방향으로 격리된 방식으로 표시되어야 한다.

사용자가 현지화 설정을 변경하면 사용자 에이전트는 실행 화면에 표시되는 보안에 민감한 멤버를 *_localized 멤버에 지정된 현지화된 표현으로 자동 조정할 수 있다. 이러한 변경 사항은 사용자가 다음에 웹 애플리케이션을 열 때 제시되어야 한다.

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

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

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

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

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

  1. manifest의 클라이언트가 null이면 null을 반환한다.
    참고
  2. request를 새로운 요청으로 둔다.
  3. request의 URL을 image의 src로 설정한다.
  4. request의 대상을 "image"로 설정한다.
  5. request의 클라이언트를 manifest의 클라이언트로 설정한다.
  6. image와 request를 사용하여 이미지 리소스를 가져온 결과를 반환한다.
참고

2.1 purpose 멤버

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

매니페스트 이미지 리소스가 아이콘으로 사용되는 경우, 개발자는 호스트 OS의 컨텍스트에서 이미지가 특별한 용도로 사용되도록 의도되었음을 나타낼 수 있다(즉, 더 나은 통합을 위해). 사용자 에이전트는 명시된 아이콘 용도 이외의 용도로 아이콘을 사용해서는 안 된다.

참고

예를 들어, 용도가 "monochrome"인 아이콘은 단색 채우기가 적용된 배지나 고정 아이콘으로 사용할 수 있으며, 애플리케이션의 풀 컬러 실행 아이콘과 시각적으로 구별된다. 사용자 에이전트는 purpose 멤버의 값을 purpose가 표시되는 위치와 방식을 결정하기 위한 힌트로 사용한다. 개발자가 달리 선언하지 않는 한, 사용자 에이전트는 아이콘을 어떤 용도로든 사용할 수 있다.

아이콘 용도는 다음과 같다.

monochrome
사용자 에이전트는 단색으로 채워진 monochrome 아이콘이 필요한 곳에 이 아이콘을 표시할 수 있다. 아이콘의 색상 정보는 버리고 알파 데이터만 사용한다. 그러면 사용자 에이전트는 이 아이콘을 단색 채우기 위의 마스크처럼 사용할 수 있다.
maskable
이미지는 아이콘 마스크와 안전 영역을 고려하여 설계되므로, 이미지에서 안전 영역 밖에 있는 모든 부분은 사용자 에이전트가 안전하게 무시하고 마스크 처리할 수 있다.
any (기본값)
사용자 에이전트는 특정 purpose가 필요하지 않은 곳에 아이콘을 자유롭게 표시할 수 있다. 예를 들어, 용도가 "any"인 매니페스트 이미지 리소스는 "monochrome"이 필요한 컨텍스트에서는 사용되지 않는다.

아이콘 용도 목록은 목록 « "monochrome", "maskable", "any" »이다.

참고

아이콘에 여러 용도가 포함되어 있으면 해당 용도 중 어느 용도로든 사용할 수 있다. 명시된 용도 중 인식되는 것이 없으면 아이콘은 완전히 무시된다. 예를 들어 아이콘의 용도가 "monochrome fizzbuzz"인 경우, "monochrome"이 유효한 용도이므로 monochrome 아이콘으로 사용할 수 있다. 그러나 아이콘의 용도가 "fizzbuzz"뿐이면 무시된다.

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

  1. json["purpose"]가 존재하지 않거나 json["purpose"]가 문자열이 아닌 경우:
    1. 집합 « "any" »를 반환한다.
  2. keywords를 json["purpose"]를 ASCII 공백에서 분할한 결과로 둔다.
  3. purposes를 새로운 집합으로 둔다.
  4. keywords의 각 keyword에 대해:
    1. 아이콘 용도 목록이 keyword를 포함하지 않으면 계속한다.
    2. 그렇지 않으면 keyword를 purposes에 추가한다.
  5. purposes가 비어 있으면 실패를 반환한다.
  6. purposes를 반환한다.

2.2 콘텐츠 보안 정책

사용자 에이전트가 아이콘 이미지를 가져올 수 있는지를 제어하는 보안 정책은 img-src 지시문 [CSP3]의 적용을 받으며, 이 지시문은 매니페스트 소유자의 Document와 연결된다.

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. 설치 가능한 웹 애플리케이션

모든 웹사이트는 설치 가능한 웹 애플리케이션이다.

사용자 에이전트는 최종 사용자가 자신의 기기에 웹 애플리케이션을 설치할 수 있는 방법을 제공하여, 사용자가 매니페스트의 멤버가 적용된 새로운 최상위 탐색 가능 항목을 인스턴스화할 수 있게 할 수 있다.

웹 애플리케이션이 설치되면 이를 설치된 웹 애플리케이션이라고 한다. 즉, 매니페스트의 멤버 또는 그 기본값이 웹 애플리케이션의 최상위 탐색 가능 항목에 적용된다. 이는 설치된 웹 애플리케이션을 기존 북마크와 구별한다. 기존 북마크에서 웹 페이지를 열면 매니페스트의 속성이 해당 페이지에 적용되지 않기 때문이다.

참고

예를 들어 설치를 지원하는 사용자 에이전트에서는 웹 애플리케이션을 최종 사용자가 네이티브 애플리케이션과 구별할 수 없는 방식으로 표시하고 실행할 수 있다. 예를 들면 홈 화면, 런처 또는 시작 메뉴에 레이블이 있는 아이콘으로 표시할 수 있다. 웹 애플리케이션을 실행할 때 매니페스트는 사용자 에이전트에 의해 적용되며, 그 대상은 최상위 탐색 가능 객체이다. 이는 시작 URL을 불러오기 전에 수행된다. 이를 통해 사용자 에이전트는 매니페스트의 관련 값을 적용할 수 있으며, 경우에 따라 웹 애플리케이션의 디스플레이 모드와 화면 방향을 변경할 수 있다. 또 다른 예로 사용자 에이전트는 웹 애플리케이션을 설치하여 사용자 에이전트 자체의 북마크 목록에 추가할 수 있다.

4.1 애플리케이션 이름

애플리케이션 이름은 name 멤버 또는 short_name 멤버에서 파생된다. 사용자 에이전트에 권고되는 동작은 먼저 현지화된 값을 각각에 대응하는 *_localized 멤버에서 해석하는 것이다.

name 멤버 또는 short_name 멤버 중 하나가 누락되었거나 비어 있거나 잘못된 타입인 경우, 사용자 에이전트가 선택할 수 있는 것은 name 멤버를 short_name 멤버의 대체 값으로 사용하거나 short_name 멤버를 name 멤버의 대체 값으로 사용하는 것이다.

name과 short_name 멤버가 모두 누락되었거나 비어 있거나 잘못된 타입인 경우, 사용자 에이전트가 선택할 수 있는 것은 Document를 사용하여 적합한 대체 항목을 찾는 것이다 누락된 매니페스트 멤버에 대해(예: application-name을 name 또는 short_name 대신 사용). 또는 사용자 에이전트에 권고되는 동작은 플랫폼 규칙을 따르는 기본 이름(예: "제목 없음")을 할당하는 것이다. 또는 사용자 에이전트가 선택할 수 있는 것은 최종 사용자가 일부 텍스트를 입력하고 이를 애플리케이션 이름으로 사용하도록 허용하는 것이다.

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을 시작 URL로 설정한다.
  2. traversable을 target URL과 POST resource를 사용하여 새로운 최상위 탐색 가능 항목을 생성하는 단계를 실행한 결과로 둔다.
  3. manifest를 traversable에 적용한다.
  4. traversable을 반환한다.

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 (기본값)
플랫폼의 하이퍼링크 열기 규칙(예: 브라우저 탭, 새 창)에 따라 웹 애플리케이션을 엽니다.
참고

fullscreen 디스플레이 모드는 Fullscreen API 표준과 직교하며 독립적으로 작동한다. fullscreen 디스플레이 모드는 브라우저 창의 전체 화면 상태에 영향을 미치는 반면, [FULLSCREEN] API는 뷰포트에 포함된 요소를 대상으로 작동한다. 따라서 웹 애플리케이션의 디스플레이 모드를 fullscreen으로 설정해도 document.fullScreenElement가 null을 반환하고 fullscreenEnabled가 false를 반환할 수 있다.

매니페스트가 적용된 최상위 탐색 가능 객체에서 현재 유효한 디스플레이 모드는 적용된 디스플레이 모드이며, 해당 최상위 탐색 가능 객체에 적용된다. 사용자 에이전트는 필요에 따라 보안상의 이유로 적용된 디스플레이 모드를 변경할 수 있다(예: 최상위 탐색 가능 객체가 범위 밖으로 탐색되는 경우). 또한 사용자 에이전트는 필요에 따라 사용자에게 다른 디스플레이 모드로 전환할 수단을 제공할 수 있다.

display 멤버가 누락되었거나 유효한 display 멤버가 없는 경우, 사용자 에이전트는 browser 디스플레이 모드를 적용된 디스플레이 모드로 사용한다. 따라서 사용자 에이전트는 반드시 browser 디스플레이 모드를 지원해야 한다.

모든 디스플레이 모드에는 폴백 체인이 있으며, 이는 디스플레이 모드의 목록이다. 다음에 대한 폴백 체인은 다음과 같다:

  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를 반환한다.
  4. 단언: 이 단계에는 절대 도달하지 않는다.
참고

위 반복문은 단언 전에 값을 반환하는 것이 보장된다. browser가 모든 모드의 폴백 체인에 포함되고 모든 사용자 에이전트가 다음을 지원해야 하기 때문이다: browser 디스플레이 모드.

디스플레이 모드 목록은 목록 « "fullscreen", "standalone", "minimal-ui", "browser" »이다.

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

참고

사용자 에이전트는 적용된 디스플레이 모드를 노출한다 — 이는 반드시 매니페스트에서 선언된 모드인 것은 아니다 — 이 정보는 display-mode 미디어 기능을 통해 노출되며 CSS 또는 JavaScript에서 접근할 수 있다. 이 미디어 기능은 매니페스트가 적용되지 않을 때 웹 페이지의 다른 디스플레이 모드도 반영한다. 예를 들어 최종 사용자가 페이지를 전체 화면으로 전환하면 사용자 에이전트는 이 변경 사항을 CSS와 스크립트에 display-mode 미디어 기능을 통해 반영한다.

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

7.1 개인정보 보호 고려 사항

이 명세는 가치가 높은 데이터를 직접 다루지 않는다. 그러나 설치된 웹 애플리케이션과 그 데이터는 "가치가 높은" 것으로 간주될 수 있다(특히 개인정보 보호 관점에서).

웹 애플리케이션에는 로컬 기기와 원격 호스트와 동시에 상호 작용할 수 있는 콘텐츠가 포함될 수 있으므로, 구현자는 개인 정보를 원격 호스트에 노출함으로써 발생하는 개인정보 보호상의 영향을 고려해야 한다. 완화 및 심층 방어 조치는 구현자의 책임이며 이 명세에서는 규정하지 않는다. 그러나 이러한 조치를 설계할 때 구현자는 사용자가 정보 공유를 인지할 수 있게 하고, 권한을 취소할 수 있는 인터페이스에 쉽게 접근할 수 있도록 하는 것이 권고된다.

사용자 에이전트는 다른 애플리케이션이 시스템에 설치된 애플리케이션을 확인하지 못하도록 하는 것이 권고된다(예: 사용자 에이전트 캐시에 대한 타이밍 공격을 통해). 이는 예를 들어 웹 애플리케이션이 설치된 후 매니페스트에서 연결된 리소스 (예: 아이콘)를 사용자 에이전트의 캐시에서 무효화하거나, 일반적인 웹 탐색에 사용되는 캐시와 완전히 다른 캐시를 사용하여 수행할 수 있다.

바로 가기의 url이 애플리케이션이 브라우저 외부에서 실행되었음을 나타내도록 작성될 수도 있다(예: "url": "/task/?from=homescreen"). 또한 개발자가 사용자를 고유하게 식별하는 문자열(예: 서버가 할당한 UUID)을 url에 인코딩할 수도 있다. 이는 사용자가 인지하지 못할 수 있는 지문 채취/개인정보 보호에 민감한 정보이며, 시작 URL에 인코딩된 식별자와 마찬가지로 사용자가 사이트 데이터를 삭제해도 지워지지 않는다.

시작 URL과 마찬가지로, 사용자 에이전트는 설치할 때 또는 그 이후 언제든지 사용자가 바로 가기의 url을 검사하고 필요한 경우 수정할 수 있도록 하는 것이 권고된다.

7.2 보안 고려 사항

매니페스트 형식은 JSON이며 [UNICODE]를 사용하여 인코딩되므로, [JSON] 및 [UNICODE-SECURITY]에 설명된 보안 고려 사항이 적용된다. 또한 개발자가 사용자 정의 데이터나 제한되지 않은 데이터를 매니페스트에 포함하지 못하도록 막을 방법이 없으므로, 구현자는 그 밖에는 제한되지 않는 멤버 유형의 값에 구현별 제한을 적용해야 한다. 예를 들어 서비스 거부 공격을 방지하거나, 메모리 고갈을 방지하거나, 플랫폼별 제한 사항을 우회하기 위해서이다.

웹 애플리케이션에는 일반적으로 ECMAScript, HTML, CSS 파일과 샌드박스 환경에서 실행되는 기타 미디어가 포함된다. 따라서 구현자는 자신이 지원하는 유형의 보안 영향을 인지해야 한다. 특히 구현자는 최소한 다음 명세에 설명된 보안 영향을 고려해야 한다: [CSS-MIME], [ECMAScript-MIME], [HTML].

이 명세는 매니페스트의 특정 멤버에서 URL을 선언할 수 있도록 허용하므로, 구현자는 [URL] 명세에서 논의된 보안 고려 사항을 고려해야 한다. 매니페스트에서 발견된 IRI와 IDNA 주소를 표시하려는 구현은 [UNICODE-SECURITY]에서 제공하는 보안 권고를 따를 것이 강력히 권고된다.

개발자는 [CSP3] 명세 전반에서 논의된 보안 고려 사항, 특히 매니페스트를 인라인화하기 위한 유효한 소스로 data:를 사용하는 것과 관련된 사항을 인지해야 한다. 이렇게 하면 매니페스트를 문서 자체에 직접 포함할 수 있게 되어 XSS 공격이 가능해질 수 있으므로, 이를 완전히 피하는 것이 가장 좋다.

최종 사용자가 웹 애플리케이션을 설치할 수 있게 하는 UI는 해당 웹 애플리케이션의 아이콘, 이름, 시작 URL, 출처 등을 검사할 수 있도록 하는 것이 권고된다. 이는 최종 사용자가 웹 애플리케이션을 설치하기 전에 관련 정보를 승인하고 필요한 경우 수정할지 신중하게 결정할 기회를 제공하기 위한 것이다. 또한 최종 사용자는 예를 들어 예상치 못한 아이콘이나 이름을 사용하는 방식으로 웹 애플리케이션이 다른 웹 애플리케이션을 사칭하는지 판단할 기회를 얻는다.

웹 애플리케이션이 실행 중일 때 사용자 에이전트는 최종 사용자가 출처, 시작 및/또는 현재 URL, 부여된 권한, 관련 아이콘 등 웹 애플리케이션에 대한 일반적인 정보에 접근할 수 있는 수단을 제공하는 것이 권고된다. 이러한 정보를 최종 사용자에게 노출하는 방법은 구현자에게 맡긴다.

또한 디스플레이 모드를 "browser" 이외의 값으로 설정하는 매니페스트를 적용할 때, 사용자 에이전트는 최종 사용자에게 웹 브라우저의 일반적인 탐색 컨텍스트를 벗어나고 있음을 명확하게 알리는 것이 권고된다. 이상적으로는 웹 애플리케이션을 실행하거나 전환하는 작업이 호스트 플랫폼의 다른 애플리케이션을 실행하거나 전환하는 방식과 일관되게 수행된다. 예를 들어 길고 명확한 애니메이션 전환을 표시하거나 "애플리케이션 X를 실행합니다"라는 텍스트를 음성으로 출력할 수 있다.

display 멤버를 통해 출처는 사용자 에이전트의 네이티브 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 스키마

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

매니페스트 문서의 유효성을 검사하려는 개발자는 schemastore.org에서 비공식 매니페스트 형식용 JSON 스키마를 찾을 수 있다. 이 스키마는 Apache 2.0에 따라 사용이 허가된다. Mads Kristensen이 친절하게 유지 관리하고 있다. 개발자가 JSON 스키마에서 문제를 발견하면 GitHub의 SchemaStore 저장소에 버그를 신고해 주기 바란다.

F. 국제화 고려 사항

이 절은 비규범적이다.

작성자는 다음 옵션 중 하나를 사용하여 매니페스트의 콘텐츠를 현지화할 것으로 예상된다.

매니페스트의 현지화된 값:

작성자는 해당 *_localized 멤버(예: name_localized)를 사용하여 매니페스트의 현지화 가능한 멤버에 대한 현지화된 값을 제공할 수 있다. 개별 현지화 항목은 문자열 또는 현지화된 텍스트 객체일 수 있다. 현지화된 텍스트 객체는 자체 자연어 및 텍스트 방향 메타데이터를 lang 및 dir 속성을 사용하여 지정할 수 있으며, 매니페스트 전체의 lang 및 dir 멤버가 제공하는 기본값을 재정의한다.

사용자 에이전트는 다음 방식 중 하나로 현지화된 값을 처리할 수 있다.

전달형 현지화:
사용자 에이전트는 설치 중 모든 현지화된 값(전체 언어 맵)을 호스트 운영 체제에 전달한다. 사용자가 OS 수준에서 선호 언어를 변경하면 호스트 OS는 사용자 에이전트를 실행할 필요 없이 업데이트된 현지화된 값 (예: 애플리케이션 이름)을 즉시 표시할 수 있다.
주문형/업데이트 시 평가:
사용자 에이전트는 구문 분석 시 사용자의 현재 로케일을 기반으로 현지화된 값을 평가한다. 사용자가 시스템 언어를 변경해도 앱 속성은 즉시 업데이트되지 않는다. 대신 사용자가 다음에 애플리케이션을 방문하거나 백그라운드 업데이트 확인 중에 업데이트되며, 이를 통해 사용자 에이전트는 호스트 OS를 업데이트하기 전에 보안에 민감한 변경 사항(예: 이름 변경)을 검사하고 잠재적으로 사용자 확인을 요청할 수 있다.
언어를 동적으로 설정:
여기에는 예를 들어 최종 사용자에게 선호 언어가 무엇인지 묻고, 해당 언어 기본 설정을 기반으로 문서의 매니페스트 링크 관계를 동적으로 추가하거나 교체하는 것이 포함될 수 있다 (예: "manifest.php?lang=fr"과 같은 URL 사용).
서버 측 언어 협상 또는 지리적 타기팅 사용:
웹 애플리케이션을 호스팅하는 서버는 지리적 타기팅을 사용하거나 언어 협상(예: HTTP "Accept-Language" 헤더 [RFC9110] 또는 사용자 정의 HTTP 헤더)을 수행하여 최종 사용자의 언어를 미리 결정하려고 시도할 수 있다. 자세한 내용과 모범 사례는 W3C 국제화 문서인 로케일 설정에 사용되는 Accept-Language 및 HTTP 헤더, meta 요소 및 언어 정보를 참조한다.

위의 옵션을 고려할 때 개발자는 선호 언어와 관련하여 최종 사용자의 개인정보 보호에 유의해야 한다. 최종 사용자가 웹 애플리케이션에 자신의 언어 기본 설정을 명시적으로 표시한 경우 (즉, 단순히 사용자 에이전트의 기본 언어 설정을 사용하는 것이 아닌 경우), 최종 사용자의 선호 언어를 네트워크를 통해 평문으로 전송하는 것은 일반적으로 허용되지 않는다. 그렇게 하면 최종 사용자에 대한 개인 정보가 노출된다. 따라서 개발자는 웹 애플리케이션에 대한 광범위한 감시 가능성을 줄이기 위해 [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년 5월 29일. W3C 작업 초안. URL: https://www.w3.org/TR/accname-1.2/
[BCP47]
언어 식별용 태그. A. Phillips, 편집자; M. Davis, 편집자. IETF. 2009년 9월. 현행 모범 사례. URL: https://www.rfc-editor.org/info/rfc5646/
[CSP3]
콘텐츠 보안 정책 레벨 3. Mike West; Antonio Sartori. W3C. 2026년 7월 29일. W3C 작업 초안. URL: https://www.w3.org/TR/CSP3/
[css-color-4]
CSS 색상 모듈 레벨 4. Tab Atkins Jr.; Chris Lilley; Lea Verou. W3C. 2026년 7월 28일. 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/info/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. 현행 표준. 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/info/rfc4329/
[fetch]
Fetch 표준. Anne van Kesteren. WHATWG. 현행 표준. URL: https://fetch.spec.whatwg.org/
[HTML]
HTML 표준. Anne van Kesteren; Domenic Denicola; Dominic Farolino; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. 현행 표준. 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. 현행 표준. URL: https://infra.spec.whatwg.org/
[JSON]
JavaScript 객체 표기법(JSON) 데이터 교환 형식. T. Bray, 편집자. IETF. 2017년 12월. 인터넷 표준. URL: https://www.rfc-editor.org/info/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/info/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/info/rfc2119/
[RFC7159]
JavaScript 객체 표기법(JSON) 데이터 교환 형식. T. Bray, 편집자. IETF. 2014년 3월. 제안 표준. URL: https://www.rfc-editor.org/info/rfc7159/
[RFC8174]
RFC 2119 핵심 단어의 대문자와 소문자 간 모호성. B. Leiba. IETF. 2017년 5월. 현행 모범 사례. URL: https://www.rfc-editor.org/info/rfc8174/
[SCREEN-ORIENTATION]
화면 방향. Marcos Caceres; Léonie Watson. W3C. 2026년 7월 24일. W3C 작업 초안. URL: https://www.w3.org/TR/screen-orientation/
[UAX9]
유니코드 양방향 알고리즘. Manish Goregaokar मनीष गोरेगांवकर; Robin Leroy. Unicode Consortium. 2025년 8월 13일. 유니코드 표준 부록 #9. URL: https://www.unicode.org/reports/tr9/tr9-51.html
[UNICODE]
유니코드 표준. Unicode Consortium. URL: https://www.unicode.org/versions/latest/
[UNICODE-SECURITY]
유니코드 보안 고려 사항. Mark Davis; Michel Suignard. Unicode Consortium. 2014년 9월 19일. 유니코드 기술 보고서 #36. URL: https://www.unicode.org/reports/tr36/tr36-15.html
[URL]
URL 표준. Anne van Kesteren. WHATWG. 현행 표준. URL: https://url.spec.whatwg.org/
[UTS55]
유니코드 소스 코드 처리. Robin Leroy; Mark Davis. Unicode Consortium. 2024년 1월 29일. 유니코드 기술 표준 #55. URL: https://www.unicode.org/reports/tr55/tr55-5.html

L.2 비규범 참고문헌

[FULLSCREEN]
Fullscreen API 표준. Philip Jägenstedt. WHATWG. 현행 표준. 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. 현행 표준. URL: https://mimesniff.spec.whatwg.org/
[RFC7258]
광범위한 감시는 공격이다. S. Farrell; H. Tschofenig. IETF. 2014년 5월. 현행 모범 사례. URL: https://www.rfc-editor.org/info/rfc7258/
[RFC8246]
HTTP 불변 응답. P. McManus. IETF. 2017년 9월. 제안 표준. URL: https://httpwg.org/specs/rfc8246.html
[RFC9110]
HTTP 의미론. R. Fielding, 편집자; M. Nottingham, 편집자; J. Reschke, 편집자. IETF. 2022년 6월. 인터넷 표준. URL: https://httpwg.org/specs/rfc9110.html
[SERVICE-WORKERS]
서비스 워커 나이틀리. Monica CHINTALA; Yoshisato Yanagisawa. W3C. 2026년 7월 23일. 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/info/rfc5246/