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

W3C 워킹 드래프트

이 문서에 대한 자세한 정보
이 버전:
https://www.w3.org/TR/2025/WD-appmanifest-20250505/
최신 공개 버전:
https://www.w3.org/TR/appmanifest/
최신 편집자 초안:
https://w3c.github.io/manifest/
이력:
https://www.w3.org/standards/history/appmanifest/
커밋 이력
편집자:
Marcos Cáceres (Apple)
Kenneth Rohde Christiansen (Intel Corporation)
Diego González (Microsoft Corporation)
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)
피드백:
GitHub w3c/manifest (풀 리퀘스트, 새 이슈, 오픈 이슈)
브라우저 지원:
caniuse.com

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

요약

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

이러한 메타데이터를 활용하여, 사용자 에이전트는 개발자에게 네이티브 애플리케이션과 비교할 수 있는 사용자 경험을 제공할 수 있습니다.

이 문서의 상태

이 섹션은 이 문서가 공개된 시점에서의 상태를 설명합니다. 현재 W3C 출판물 목록과 이 기술 보고서의 최신 개정판은 W3C 표준 및 초안 색인 https://www.w3.org/TR/ 에서 확인할 수 있습니다.

경고

이 문서는 웹 애플리케이션 워킹 그룹에서 권고 트랙을 사용하여 워킹 드래프트로 공개되었습니다.

워킹 드래프트로 공개되었다고 해서 W3C 및 회원사의 지지를 의미하지는 않습니다.

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

이 문서는 W3C 특허 정책하에 운영되는 그룹에서 작성되었습니다. W3C는 공개된 특허 목록을 관리합니다. 해당 페이지에는 특허 공개 방법도 포함되어 있습니다. 개별적으로 필수 클레임이 포함된 특허를 알고 있는 경우, W3C 특허 정책 섹션 6에 따라 정보를 공개해야 합니다.

이 문서는 2023년 11월 3일자 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/" 경로 내의 문서에만 scope가 적용됩니다. 예를 들어 "/racer/race1.html", "/racer/race2.html" 등은 모두 scope에 속하지만, "/elsewhere/"나 루트 "/"는 scope 밖으로 매니페스트가 적용되지 않습니다. 오직 한 개의 scope 경로만 지원됩니다. 기술적인 세부사항은 5. 탐색 범위에서 확인하세요.

매니페스트 적용이란, 매니페스트에 정의된 표시 관련 멤버가 적용되는 것을 의미하며, 예를 들어 표시 모드 "fullscreen"이나 특정 화면 방향이 적용됩니다. 애플리케이션이 scope 내 URL로 탐색되는 동안에는 브라우저가 매니페스트를 계속 적용합니다. 하지만 "scope" 밖으로 이동하면 매니페스트 적용이 중단되고, 브라우저는 자체 기본값을 적용합니다. 예를 들어, 애플리케이션이 더 이상 전체 화면으로 표시되지 않고 브라우저 탭의 일반 웹페이지로 표시됩니다. scope 안팎으로 웹페이지가 이동할 때 어떻게 처리할지는 구현자에게 맡깁니다. 자세한 기술 사항은 1.16.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 멤버 처리를 하려면, 순서있는 맵 json과 순서있는 맵 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의 well-formed 생성 규칙과 일치하는 문자열입니다.

참고

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

lang 멤버 처리를 하려면, 순서있는 맵 json과 순서있는 맵 manifest를 사용합니다:

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

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 멤버 처리를 하려면, 순서있는 맵 json과 순서있는 맵 manifest를 사용합니다:

  1. manifest["scope"]를 파싱 결과 "."(현재 경로)을 manifest["start_url"]을 기준으로 처리한 값으로 설정한다.
  2. json["scope"]가 빈 문자열이면 반환한다.
  3. scope을 파싱 결과 json["scope"]를 manifest URL 기준으로 처리한 값으로 설정한다.
  4. scope이 실패면 반환한다.
  5. scope의 쿼리와 프래그먼트를 null로 설정한다.
  6. manifest["start_url"]이 scope 내에 없으면 반환한다.
  7. 그 외의 경우 manifest["scope"]를 scope로 설정한다.

1.7 icons 멤버

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

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

참고

1.8 display 멤버

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

display 멤버 처리를 하려면, 순서있는 맵 json과 순서있는 맵 manifest를 사용합니다:

  1. manifest["display"]를 "browser"로 설정한다.
  2. json["display"]가 존재하지 않거나 json["display"]가 문자열이 아니면 반환한다.
  3. 앞뒤 ASCII 공백 제거를 json["display"]에 적용한다.
  4. ASCII 소문자화를 json["display"]에 적용한다.
  5. 표시 모드 목록에 json["display"]가 포함되지 않으면 반환한다.
  6. manifest["display"]를 json["display"]로 설정한다.

1.9 orientation 멤버

매니페스트의 orientation 멤버는 문자열로, 모든 최상위 브라우징 컨텍스트의 기본 화면 방향을 지정합니다. 값은 OrientationLockType 열거형의 값들이며, 이 명세에서는 orientation 값이라 부릅니다(예: "any", "natural", "landscape", "portrait", "portrait-primary", "portrait-secondary", "landscape-primary", "landscape-secondary").

사용자 에이전트가 orientation 멤버의 값을 기본 화면 방향으로 지원할 경우, 웹 애플리케이션의 수명 동안(실행 중 다른 방법으로 덮어쓰지 않는 한) 해당 값이 기본 화면 방향이 됩니다. 즉, 사용자 에이전트는 화면 방향이 잠금 해제되거나 [SCREEN-ORIENTATION] 또는 최상위 브라우징 컨텍스트가 탐색될 때 반드시 기본 화면 방향으로 되돌려야 합니다.

참고

명세는 [SCREEN-ORIENTATION]의 OrientationLockType에 의존하지만, 사용자 에이전트가 [SCREEN-ORIENTATION] API를 반드시 구현해야 하는 것은 아닙니다. 물론 구현하는 것이 권장됩니다.

UI/UX 및 플랫폼 관행에 따라 일부 화면 방향과 동시에 사용할 수 없는 경우가 있습니다. 어떤 화면 방향과 표시 모드가 동시에 사용할 수 없는지는 구현자 재량에 맡깁니다. 예를 들어, 일부 사용자 에이전트에서는 browser 표시 모드에서 애플리케이션의 기본 화면 방향을 변경할 필요가 없을 수도 있습니다.

참고

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

orientation 멤버 처리를 하려면, 순서있는 맵 json과 순서있는 맵 manifest를 사용합니다:

  1. json["orientation"]이 존재하지 않거나 json["orientation"]이 문자열이 아니면 반환한다.
  2. 앞뒤 ASCII 공백 제거를 json["orientation"]에 적용한다.
  3. ASCII 소문자화를 json["orientation"]에 적용한다.
  4. json["orientation"]이 포함된 값이 orientation 값 중 하나가 아니면 반환한다.
  5. manifest["orientation"]을 json["orientation"]로 설정한다.

1.10 start_url 멤버

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

start_url 멤버는 권고 사항일 뿐이며, 사용자 에이전트는 선택적으로 무시하거나 최종 사용자에게 사용하지 않을 선택권을 제공할 수 있습니다. 예를 들어, 웹 애플리케이션의 북마크를 생성할 때나 이후에도 사용자가 URL을 수정할 수 있게 할 수 있습니다.

start_url 멤버 처리를 하려면, 순서있는 맵 json, 순서있는 맵 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이 실패면 반환한다.
  6. start URL이 document URL과 동일 출처가 아니면 반환한다.
  7. 그 외의 경우 manifest["start_url"]을 start URL로 설정한다.

1.10.1 개인정보 보호 사항: start_url 추적

start_url이 브라우저 외부에서 애플리케이션이 실행된 것을 나타내도록 작성될 수 있습니다(예: "start_url": "index.html?launcher=homescreen"). 이는 분석 및 기타 맞춤화에 유용할 수 있습니다. 하지만 개발자가 start_url에 서버에서 할당한 식별자 등, 사용자를 고유하게 식별하는 문자열을 넣을 수도 있습니다(예: "?user=123", "/user/123/", "https://user123.foo.bar"). 이러한 정보는 지문/개인정보에 민감하며 사용자에게 인식되지 않을 수 있습니다.

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

개발자가 start URL에 사용자를 고유하게 식별하는 정보를 포함하는 것은 좋지 않은 관행입니다. 이는 사용자가 사이트 데이터를 지워도 사라지지 않는 지문이 될 수 있습니다. 그러나 이 명세에서 이를 실질적으로 방지할 방법은 없습니다.

위와 같은 이유로, 설치 시 또는 이후 언제든지 사용자 에이전트가 애플리케이션의 start URL을 사용자에게 보여주고, 필요하면 수정할 수 있도록 하는 것이 권장됩니다.

사용자 에이전트는 선택적으로 이런 형태의 지문에 대한 추가 보호 기능을 제공할 수 있습니다. 예를 들어, 사용자가 오리진의 데이터를 지우면, 사용자 에이전트가 해당 오리진 scope 내 애플리케이션을 제거하도록 제안할 수 있습니다. 이렇게 하면 애플리케이션의 start URL에 남아 있는 지문을 제거할 수 있습니다.

1.11 id 멤버

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

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

참고: 프래그먼트 제외가 모범 사례
참고

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

참고

identity는 URL처럼 처리되지만 탐색 가능한 리소스를 가리키는 것은 아니므로 scope 내에 있을 필요는 없습니다.

id 멤버 처리를 하려면, 순서있는 맵 json, 순서있는 맵 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가 실패면 반환한다.
  7. id가 start_url과 동일 출처가 아니면 반환한다.
  8. id의 프래그먼트를 null로 설정한다.
  9. manifest["id"]를 id로 설정한다.

1.12 theme_color 멤버

manifest의 theme_color 멤버는 애플리케이션 컨텍스트의 기본 테마 색상 역할을 합니다. 테마 색상의 정의는 [HTML]에서 확인할 수 있습니다.

사용자 에이전트가 theme_color 멤버 값을 기본 테마 색상으로 적용하는 경우, 해당 색상은 manifest가 적용되는 모든 브라우징 컨텍스트의 테마 색상으로 동작합니다. 하지만, 사용자 에이전트는 MAY 기본 테마 색상을 다음 조건에서 오버라이드할 수 있습니다. 즉, 문서의 URL이 범위 내에 있을 때, 해당 애플리케이션 컨텍스트의 manifest에 meta 요소가 있고, name 속성이 "theme-color"인 경우입니다. 그러나, 사용자 에이전트는 SHOULD NOT manifest의 기본 테마 색상을 meta 요소의 name 속성 값이 "theme-color"인 문서의 URL이 범위 내가 아닌 경우에는 오버라이드해서는 안 됩니다. 애플리케이션이 해당 문서들에 대한 제어권이 없기 때문입니다.

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

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

참고

manifest 처리 시, 색상 멤버 처리 알고리즘이 theme_color 멤버 처리에 사용됩니다.

1.13 background_color 멤버

manifest의 background_color 멤버는 웹 애플리케이션의 예상되는 배경색을 설명합니다. 이는 이미 애플리케이션 스타일시트에 정의된 내용이지만, 사용자 에이전트가 manifest를 인식해서 실제 파일들이 네트워크에서 불러오거나 디스크에서 가져오기 전에 웹 애플리케이션의 배경색을 그릴 때 사용할 수 있습니다.

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

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

참고

manifest 처리 시, 색상 멤버 처리 알고리즘이 background_color 멤버 처리에 사용됩니다.

1.14 shortcuts 멤버

manifest의 shortcuts 멤버는 웹 애플리케이션에서 주요 작업에 접근할 수 있도록 하는 목록 형태의 shortcut item들을 포함합니다.

참고

shortcuts의 표현 방식과 사용자에게 몇 개가 표시될지는 사용자 에이전트 또는 운영체제의 재량에 따릅니다.

shortcuts 멤버 처리를 위해, ordered map json, ordered map manifest, 그리고 URL manifest URL을 사용합니다:

  1. processedShortcuts라는 새로운 목록을 만듭니다.
  2. manifest["shortcuts"]에 processedShortcuts를 할당합니다.
  3. json["shortcuts"]가 존재하지 않거나 json["shortcuts"]가 목록이 아니면 반환합니다.
  4. 각 entry에 대해 json["shortcuts"]:
    1. shortcut을 process a shortcut 알고리즘을 사용해 entry, manifest URL, manifest["scope"], manifest["dir"]로 처리합니다.
    2. shortcut이 실패(failure)이면 건너뜁니다.
    3. processedShortcuts에 shortcut을 추가합니다.

사용자 에이전트는 SHOULD 호스트 운영체제의 앱 아이콘 컨텍스트 메뉴 노출과 일관된 방식으로 shortcuts를 제공합니다(예: 우클릭, 롱 프레스 등). 사용자 에이전트는 SHOULD manifest에서 제공된 순서대로 shortcuts를 렌더링해야 하며, SHOULD 호스트 운영체제의 컨텍스트 메뉴와 일관된 방식으로 shortcuts를 표현해야 합니다. 운영체제의 관행이나 제한에 맞춰 shortcuts 목록을 잘라(truncate) 표시할 수 있습니다(MAY).

1.15 *_localized 멤버

로컬라이즈 가능한 멤버(localizable member)란 manifest 멤버 중 지역화가 가능한 멤버를 의미합니다. 각 로컬라이즈 가능한 멤버는 manifest에서 대응되는 *_localized 멤버를 가집니다. 여기서 *는 멤버명을 뜻합니다.

language map은 ordered map으로, 키는 language tag, 값은 localized value입니다. localized value란 해당 키의 언어로 지역화된 콘텐츠입니다.

로컬라이즈 가능한 멤버에 할당된 값이 기본 표현(default representation)입니다. *_localized 멤버에는 language map이 들어 있으며, 애플리케이션에서 해당 로컬라이즈 가능한 멤버에 대한 localized value들을 정의합니다. 사용자 에이전트는 SHOULD 사용자의 지역화 설정에 따라 language tag가 가장 잘 맞는 localized value를 선택해야 합니다. 만약 해당 localized value가 없으면, 기본 표현을 사용합니다.

1.15.1 텍스트 값 지역화

localized text object란 다음 속성을 가진 ordered map입니다:

value
지역화된 문자열(string)입니다.
dir (선택)
텍스트 방향(text-direction)입니다.
lang (선택)
language tag입니다.

로컬라이즈 가능한 멤버가 문자열(string)을 허용하는 경우, *_localized 멤버의 language map은 문자열(string)이나 localized text object를 localized value로 받을 수 있습니다.

문자열(string)이 사용되거나, dir 멤버가 localized text object에 없을 경우, 기본 방향(default direction)(manifest의 dir 멤버)이 적용됩니다.

참고

문자열(string)이 사용되거나, lang 멤버가 localized text object에 없을 경우, language map의 키에 있는 language tag가 적용됩니다.

참고

*_localized 텍스트 멤버 처리를 위해, ordered map json, ordered map map, 문자열(string) member, 기본 텍스트 방향(defaultDirection)을 사용합니다:

  1. member가 json에 존재하지 않으면 반환합니다.
  2. languageMap을 json[member]로 지정합니다.
  3. languageMap이 ordered map이 아니면 반환합니다.
  4. languageTags를 languageMap의 키들로 지정합니다.
  5. map[member]에 새로운 ordered map을 할당합니다.
  6. 각 languageTag에 대해 languageTags를 순회하며, process a localized text object 알고리즘을 languageMap[languageTag], languageTag, map, member, defaultDirection으로 호출합니다.

localized text object 처리를 위해, 문자열(string) 또는 ordered map localizedValue, 기본 language tag(defaultLanguageTag), ordered map map, member, 그리고 기본 텍스트 방향(defaultDirection)을 사용합니다:

  1. normalizedValue에 ordered map을 할당합니다.
  2. localizedValue가 문자열(string)이면, 앞뒤 ASCII 공백 제거 후 normalizedValue["value"]에 할당합니다.
  3. localizedValue가 ordered map이면:
    1. "value"가 존재하고 문자열이면, 앞뒤 ASCII 공백 제거 후 normalizedValue["value"]에 할당합니다.
    2. "lang"이 존재하고 문자열이면, 앞뒤 ASCII 공백 제거 후 normalizedValue["lang"]에 할당합니다.
    3. "dir"이 존재하고 문자열이면:
      1. 앞뒤 ASCII 공백 제거
      2. text-direction list에 포함되어 있다면 normalizedValue["dir"]에 할당합니다.
  4. "value"가 normalizedValue에 없으면 반환합니다.
  5. "lang"이 normalizedValue에 없으면, 기본 language tag를 할당합니다.
  6. "dir"이 normalizedValue에 없으면, 기본 텍스트 방향을 할당합니다.
  7. IsStructurallyValidLanguageTag를 normalizedValue["lang"] 또는 defaultLanguageTag에 호출해서 false가 나오면 반환합니다.
  8. map[member][defaultLanguageTag]에 normalizedValue를 할당합니다.
참고

localized text object 처리 알고리즘은 문자열(string)이나 localized text object 모두를 localized value로 받아들이지만, 반환 결과는 항상 localized text object로서 value, lang, dir 속성이 포함됩니다.

1.15.2 이미지 리소스 지역화

지역화 가능한 멤버 중 이미지 리소스 리스트를 허용하는 경우, *_localized 멤버의 language map은 이미지 리소스 리스트를 지역화 값(localized value)으로 허용합니다.

*_localized 이미지 리소스 멤버 처리를 위해, ordered map json, ordered map map, 문자열(string) member, URL manifest URL을 사용합니다:

  1. member가 json에 존재하지 않으면 반환합니다.
  2. languageMap을 json[member]로 지정합니다.
  3. languageMap이 ordered map이 아니면 반환합니다.
  4. languageTags를 languageMap의 키들로 지정합니다.
  5. map[member]에 새로운 ordered map을 할당합니다.
  6. 각 languageTag에 대해 languageTags를 순회하며:
    1. IsStructurallyValidLanguageTag를 languageTag에 호출해서 false가 나오면 continue합니다.
    2. process image resources 알고리즘을 실행합니다. languageMap[languageTag]을 이미지 리소스 리스트로, map[member], manifest URL, languageTag를 member로 넘깁니다.

1.16 Manifest 생명주기

이 섹션은 manifest 처리와 manifest 적용 알고리즘을 정의합니다.

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

1.16.1 Manifest 처리

무시하라는 지시를 받을 때, 사용자 에이전트는 해당 manifest, 멤버, 값이 없는 것처럼 동작해야 합니다(MUST).

다음 알고리즘은 처리 확장 지점을 제공합니다. manifest에 새로운 멤버를 추가하는 다른 명세들은 이 알고리즘의 이 지점에 자신을 연결할 수 있습니다. 기존 manifest 객체의 값을 수정해서는 SHOULD NOT 안 됩니다.

참고

처리 확장 지점은 몽키패칭 관련 문제를 피하는 데 도움을 줍니다.

manifest 처리 단계는 다음 알고리즘에 의해 결정됩니다. 이 알고리즘은 URL 문서 URL, URL manifest URL, 그리고 byte sequence bodyBytes를 입력값으로 받습니다.

  1. json을 JSON 바이트를 Infra 값으로 파싱해 bodyBytes로 얻습니다.
  2. json이 파싱 예외이거나, json이 ordered map이 아닌 경우:
    1. json을 빈 ordered map으로 설정합니다.
  3. manifest를 빈 ordered map으로 만듭니다.
  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. 문서의 processed manifest가 null이 아니고, 문서의 processed manifest의 id가 manifest["id"]와 같지 않으면 반환합니다.
  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. orientation 멤버 처리를 json, manifest에 대해 실행합니다.
  20. shortcuts 멤버 처리를 json, manifest, manifest URL에 대해 실행합니다.
  21. 처리 확장 지점: 이 시점에서 독자적인 혹은 기타 지원되는 멤버들을 처리합니다.
  22. 문서의 processed manifest를 manifest로 지정합니다.

1.16.2 색상 멤버 처리

참고: 지원 색상

sRGB 색상 및 사용자 에이전트가 별도의 정보 없이 sRGB로 변환할 수 있는 색상만 지원됩니다(예: "AliceBlue"). 예를 들어, lab(…)나 color(display-p3, …)는 외부 정보 없이 sRGB로 변환할 수 있지만, color(--custom-profile, …)는 manifest에서 명시할 수 없는 "@color-profile" 규칙을 찾아야 하므로 지원되지 않습니다.

색상 멤버 처리는 다음 입력값을 사용합니다: ordered map json, ordered map map, 문자열(string) member:

  1. json[member]가 존재하지 않거나, json[member]가 문자열(string)이 아니면 반환합니다.
  2. 앞뒤 ASCII 공백 제거를 json[member]에 적용합니다.
  3. color를 CSS 색상으로 파싱한 결과로 설정합니다.
  4. color가 실패이면 반환합니다.
  5. color가 사용자 에이전트가 자체적으로 알고 있는 정보만으로 sRGB로 변환할 수 있다면 color를 sRGB로 변환합니다.
  6. color가 sRGB 색상이 아니면 반환합니다.
  7. map[member]에 color를 할당합니다.

1.16.3 텍스트 멤버 처리

텍스트 멤버 처리를 위해서는 다음과 같은 입력값이 필요합니다: ordered map json, ordered map map, 문자열(string) member:

  1. json[member]가 존재하지 않거나, json[member]가 문자열(string)이 아니면 반환합니다.
  2. 앞뒤 ASCII 공백을 제거합니다 json[member]에서.
  3. map[member]에 json[member]의 값을 할당합니다.

1.16.4 문서 없이 manifest 처리

manifest 처리 단계는 [HTML]의 link 요소 처리 단계에서 호출되지만, MAY 사용자 에이전트가 관련된 문서(document) 없이 manifest를 처리하는 경우에도 호출될 수 있습니다.

이 경우, [HTML]의 해당 단계에서 제공하는 보장과 일치시키기 위해, 사용자 에이전트는 SHOULD 적어도 과거 어느 시점에:

참고: 이러한 검사 이유

1.16.5 manifest 적용

처리된 manifest는 적용됨 상태가 되며, 최상위 브라우징 컨텍스트(top-level browsing context)에 적용됩니다. 즉, manifest의 멤버들이 해당 브라우징 컨텍스트의 표시(presentation) 및 동작(behavior)에 영향을 미칩니다. 최상위 브라우징 컨텍스트가 생성될 때마다, 사용자 에이전트는 MAY manifest를 적용할 수 있으며, 이는 네비게이션(navigation) 시작 전에 이루어질 수 있습니다.

참고

manifest가 적용된 최상위 브라우징 컨텍스트를 애플리케이션 컨텍스트(application context)라고 합니다.

애플리케이션 컨텍스트가 사용자가 네비게이트(navigate)하도록 요청해서 딥 링크(deep link)로 생성된 경우, 사용자 에이전트는 MUST 즉시 네비게이트를 딥 링크(deep link)로 하고, historyHandling을 "replace"로 설정해야 합니다. 그렇지 않으면, 애플리케이션 컨텍스트가 생성될 때, 사용자 에이전트는 MUST 즉시 네비게이트를 start URL로 하고, historyHandling을 "replace"로 설정해야 합니다.

참고

1.16.6 매니페스트 업데이트

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

업데이트 목적상, 다음 멤버들은 설치 및 실행 화면에서 표시되므로 보안 민감 멤버로 간주합니다:

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

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

사용자 에이전트는 SHOULD NOT 사용자의 명시적 허가 없이 보안 민감 멤버에 대한 변경 사항을 자동으로 적용해서는 안 됩니다.

대신, 사용자 에이전트는 SHOULD 보안 민감 멤버의 변경사항을 적절한 관리 옵션과 함께 사용자에게 표시하여 사용자가 웹 애플리케이션 업데이트에 대해 정보를 바탕으로 결정할 수 있도록 해야 합니다.

만약 업데이트에 보안 민감 멤버에 대한 변경이 포함되지 않았다면, 사용자 에이전트는 MAY 자동으로 변경사항을 적용할 수 있습니다.

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

참고: 사용자 에이전트는 부분 업데이트를 적용하지 않음

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

각 매니페스트 이미지 리소스는 이미지 리소스이며, 웹 애플리케이션의 일부로 개념적으로 포함되어 다양한 상황에서 사용할 수 있습니다(예: 애플리케이션 메뉴의 아이콘 등). 어떤 멤버가 해당 객체를 사용하느냐에 따라 용도가 달라집니다.

매니페스트 이미지 리소스는 이미지 리소스와 다르게 purpose 멤버를 추가로 가질 수 있습니다.

사용자 에이전트는 MAY 매니페스트 이미지 리소스와 연결된 이미지를 플랫폼의 시각 스타일에 더 잘 맞게 변경하여 사용자에게 표시할 수 있습니다. 예를 들어, 모서리를 둥글게 하거나 특정 색상으로 칠할 수 있습니다. 개발자는 이러한 상황에 대비하여 이미지 리소스를 준비하는 것이 좋으며, 색상 변화나 모서리 잘림 등으로 중요한 정보가 손실되는 것을 피해야 합니다.

2.1 purpose 멤버

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

매니페스트 이미지 리소스가 아이콘으로 사용되는 경우, 개발자는 해당 이미지가 호스트 OS에서 특별한 용도를 위해 제공된 것임을 힌트로 줄 수 있습니다(즉, 더 나은 통합을 위해). 사용자 에이전트는 SHOULD NOT 명시된 아이콘 용도와 다른 용도로 아이콘을 사용해서는 안 됩니다.

참고

예를 들어, purpose가 "monochrome"인 아이콘은 배지(badge)나 고정 아이콘(pinned icon) 등 단색 채움(solid fill)이 필요한 곳에 사용될 수 있습니다. 이는 애플리케이션의 풀컬러 런치 아이콘과 시각적으로 구별됩니다. 사용자 에이전트는 purpose 멤버의 값을 힌트로 삼아 어디서, 어떻게 purpose를 표시할지 결정합니다. 개발자가 별도로 명시하지 않은 경우, 사용자 에이전트는 아이콘을 임의 용도로 사용할 수 있습니다.

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

monochrome
사용자 에이전트는 단색 채움(monochrome icon with a solid fill)이 필요한 곳에 이 아이콘을 표시할 수 있습니다. 아이콘에 포함된 색상 정보는 버려지고 알파 데이터만 사용됩니다. 이 아이콘은 사용자 에이전트에서 단색 채움 위에 마스크처럼 사용할 수 있습니다.
maskable
이미지는 아이콘 마스크 및 안전 구역(icon masks and safe zone)을 염두에 두고 디자인되어, 이미지의 안전 구역(safe zone) 외부 영역은 사용자 에이전트에 의해 안전하게 무시되고 마스킹될 수 있습니다.
any (기본값)
사용자 에이전트는 purpose가 요구되지 않는 곳에 자유롭게 아이콘을 표시할 수 있습니다. 예를 들어, "any" purpose를 가진 매니페스트 이미지 리소스는 "monochrome"이 요구되는 상황에서는 사용되지 않습니다.

아이콘 용도 리스트는 다음 목록(list)입니다: « "monochrome", "maskable", "any" ».

참고

아이콘에 여러 용도가 포함된 경우, 그 중 어느 용도로든 사용할 수 있습니다. 명시된 용도가 인식되지 않으면 아이콘은 완전히 무시됩니다. 예를 들어, purpose가 "monochrome fizzbuzz"인 아이콘의 경우, "monochrome"은 유효한 용도이므로 단색 아이콘으로 사용할 수 있습니다. 그러나 purpose가 "fizzbuzz"만 있을 경우, 해당 아이콘은 무시됩니다.

이미지의 용도 결정을 위해, ordered map json이 필요합니다:

  1. json["purpose"]가 존재하지 않거나, json["purpose"]가 문자열(string)이 아니면:
    1. set « "any" »를 반환합니다.
  2. keywords를 ASCII 공백으로 분리(split on ASCII whitespace)한 json["purpose"]로 설정합니다.
  3. purposes를 새로운 set으로 만듭니다.
  4. 각 keyword에 대해 keywords를 순회합니다:
    1. 아이콘 용도 리스트에 keyword가 포함되지 않으면 continue합니다.
    2. 그렇지 않으면, append keyword를 purposes에 추가합니다.
  5. purposes가 비어 있으면(is empty), 실패(failure)를 반환합니다.
  6. purposes를 반환합니다.

2.2 콘텐츠 보안 정책

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

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

일부 플랫폼은 고유의 아이콘 형태를 선호하지만, 웹 애플리케이션은 여러 플랫폼에서 동작해야 하므로 maskable 용도를 추가함으로써 아이콘에 사용자 에이전트가 지정한 마스크를 적용할 수 있음을 나타낼 수 있습니다. 이를 통해 플랫폼은 아이콘이 플랫폼과 잘 어우러지도록 하며, 서로 다른 위치에서 다양한 마스크와 배경색을 적용할 수 있습니다.

안전 구역은 maskable 아이콘에서 항상 보이는 영역입니다. 아이콘 중심을 기준으로 한 원이며, 반지름이 아이콘 크기의 2/5(40%)입니다. 만약 아이콘이 정사각형이 아니면, 너비와 높이 중 더 작은 값을 기준으로 합니다.

참고

maskable 아이콘을 디자인하는 경우 모든 중요한 부분이 안전 구역 안에 있도록 해야 합니다.

safe zone illustrated
그림 1 안전 구역은 아이콘의 너비와 높이 중 더 작은 값의 2/5(40%) 반지름을 갖는 중심 원입니다.

이 구역 내의 모든 픽셀은 모든 마스크에서 반드시 보이게 됩니다. 안전 구역 밖의 픽셀은 마스크에 따라 보이지 않을 수도 있습니다.

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

사용자 에이전트는 MUST NOT 안전 구역 내의 픽셀을 투명하게 만들어서는 안 됩니다.

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

아이콘에 투명 픽셀이 포함된 경우, 사용자 에이전트는 MUST 아이콘을 사용자 에이전트가 선택한 단색 배경(예: 흰색) 위에 합성해야 합니다.

참고

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

2.3.1 마스크 예시

참고

안전 구역 내에 아이콘을 배치하면, 대부분의 아이콘에 위, 아래, 왼쪽, 오른쪽에 약 10%의 패딩이 생깁니다(내용 또는 필수적이지 않은 내용 없음). 개발자는 안전 구역만 남기고 나머지가 마스킹되었을 때 아이콘을 반드시 확인해야 합니다.

2.3.1.1 "maskable" 용도의 아이콘
체커보드 배경 위의 아이콘
그림 2 이미지 투명 배경의 기본 이미지
노란색 배경 위 보라색 원(크기의 40%) 안의 아이콘
그림 3 안전 구역 아이콘 크기의 2/5(40%) 반지름 원
2.3.1.2 마스크 예시
보라색 배경 위 노란색 둥근 사각형 안의 아이콘
그림 4 둥근 사각형 Android
보라색 배경 위 노란색 매우 둥근 사각형 안의 아이콘
그림 5 스퀴클(squircle) Android
보라색 배경 위 노란색 둥근 원 안의 아이콘
그림 6 원(circle) Android
보라색 배경 위 다소 둥근 노란색 사각형 안의 아이콘
그림 7 둥근 사각형 iOS
노란색 배경의 아이콘
그림 8 풀블리드(fullbleed) Windows

2.4 단색 아이콘과 단색 채움

일부 플랫폼은 아이콘이 단색 채움 (단일 색상)으로 표시되어야 하며, 아이콘의 투명도만 매니페스트에서 지정할 수 있습니다. 웹 애플리케이션이 여러 플랫폼에서 동작해야 하므로, monochrome 용도를 추가함으로써 사용자 에이전트가 지정한 색상을 아이콘에 적용할 수 있음을 나타낼 수 있습니다. 이를 통해 플랫폼은 아이콘이 플랫폼과 잘 어우러지도록 하며, 서로 다른 위치에서 다양한 색상과 패딩을 적용할 수 있습니다.

monochrome 아이콘을 표시할 때, 사용자 에이전트는 MUST NOT 픽셀의 빨간색, 초록색, 파란색 컴포넌트를 독립적으로 표시해서는 안 됩니다. 사용자 에이전트는 SHOULD 각 픽셀의 원래 알파 값은 유지하되, 빨강, 초록, 파랑 값은 사용자 에이전트가 선택한 값으로 표시해야 합니다. RECOMMENDED로 모든 픽셀에 동일한 색상 값을 쓰는 것이 좋습니다.

참고

monochrome 아이콘을 디자인할 때 모든 픽셀을 검정으로 하고 투명도를 활용해 아이콘의 실루엣을 표현할 수 있습니다.

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

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

2.4.1 단색 아이콘 사용 예시

2.4.1.1 사용 예시
체커보드 배경 위 검정 아이콘
그림 9 이미지 색상 없는 기본 이미지.
체커보드 배경 위 어두운 그라데이션 아이콘
그림 10 그라데이션 채움 이미지에 그라데이션 채움 적용.
연회색 배경 위 어두운 노란색 아이콘
그림 11 단색 채움과 패딩 매니페스트의 테마 색상으로 채움.

2.5 이미지 리소스 처리

이미지 리소스 처리를 위해, list images, ordered map map, manifest URL 그리고 문자열(string) member가 필요합니다:

  1. imageResources를 새로운 list로 만듭니다.
  2. map[member]에 imageResources를 할당합니다.
  3. images가 list가 아니면 반환합니다.
  4. 각 potential image에 대해 images를 순회합니다:
    1. image에 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이며, 웹 앱 내의 주요 작업 또는 페이지로 연결되는 링크를 나타냅니다. 다음 멤버를 가집니다:

사용자 에이전트는 이 멤버들을 사용해 운영체제에서 웹 앱 아이콘을 조작할 때 표시되는 컨텍스트 메뉴를 조립할 수 있습니다. 사용자가 운영체제 메뉴에서 바로가기를 실행하면, 사용자 에이전트는 SHOULD 바로가기 실행을 수행해야 합니다.

3.1 name 멤버

바로가기 항목의 name 멤버는 문자열(string)로, 컨텍스트 메뉴에서 사용자에게 보통 표시되는 바로가기의 이름을 나타냅니다.

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

3.2 short_name 멤버

바로가기 항목의 short_name 멤버는 문자열(string)로, 바로가기의 이름을 짧게 표현한 버전입니다. 전체 이름을 표시할 공간이 충분하지 않을 때 사용됩니다.

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

3.3 description 멤버

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

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

3.4 url 멤버

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

3.5 icons 멤버

바로가기 항목의 icons 멤버는 다양한 상황에서 바로가기를 상징적으로 나타내는 이미지 목록입니다.

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

3.6 바로가기 실행

바로가기 항목 shortcut과 manifest가 호출될 때, 웹 애플리케이션 실행을 manifest와 shortcut.url로 수행합니다.

3.7 바로가기 항목 처리

바로가기 항목 처리를 위해, ordered map item, URL manifest URL, URL scope, 그리고 기본 텍스트 방향(defaultDirection) defaultDirection이 필요합니다:

  1. 다음 조건 중 하나라도 해당하면 실패(failure)를 반환합니다:
  2. url에 파싱 결과를 item["url"]과 manifest URL을 기준(base URL)으로 지정합니다.
  3. url이 실패이면 실패를 반환합니다.
  4. url이 scope 범위 내가 아니면 실패를 반환합니다.
  5. shortcut에 ordered map «[ "url" → url, "name" → item["name"] ]»를 할당합니다.
  6. *_localized 텍스트 멤버 처리를 item, shortcut, "name_localized", defaultDirection으로 실행합니다.
  7. "short_name"이 존재하며, item["short_name"]이 문자열(string)이면, shortcut["short_name"]에 할당합니다.
  8. *_localized 텍스트 멤버 처리를 item, shortcut, "short_name_localized", defaultDirection으로 실행합니다.
  9. "description"이 존재하며, item["description"]이 문자열(string)이면, shortcut["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. 설치 가능한 웹 애플리케이션

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

사용자 에이전트는 최종 사용자가 웹 애플리케이션을 자신의 기기에 설치할 수 있도록 방법을 제공할 수 있습니다. 이로써 사용자는 manifest의 멤버들이 적용된 새로운 최상위 브라우징 컨텍스트를 인스턴스화할 수 있습니다.

웹 애플리케이션이 설치되면 설치된 웹 애플리케이션이라고 합니다. 즉, manifest의 멤버 또는 기본값이 적용되어 해당 웹 애플리케이션의 최상위 브라우징 컨텍스트에 반영됩니다. 이것이 설치된 웹 애플리케이션과 기존 즐겨찾기의 차이점이며, 즐겨찾기를 통해 웹 페이지를 여는 경우 manifest의 속성이 적용되지 않습니다.

참고

예를 들어 설치를 지원하는 사용자 에이전트에서 웹 애플리케이션은 네이티브 애플리케이션과 구분되지 않는 방식으로 표시 및 실행될 수 있습니다. 예: 홈 화면, 런처, 시작 메뉴에 라벨이 붙은 아이콘으로 나타날 수 있습니다. 웹 애플리케이션 실행 시, manifest가 적용되어 최상위 브라우징 컨텍스트에 반영된 후 start URL이 로드됩니다. 이 과정에서 manifest의 관련 값이 적용되어 디스플레이 모드나 화면 방향이 변경될 수 있습니다. 또는 사용자 에이전트 자체의 즐겨찾기 목록에 웹 애플리케이션을 설치할 수도 있습니다.

4.1 애플리케이션 이름

애플리케이션 이름은 name 멤버 또는 short_name 멤버에서 유래합니다. 사용자 에이전트는 SHOULD 해당 *_localized 멤버에서 먼저 지역화 값을 확인해야 합니다.

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

name 및 short_name 멤버가 누락되었거나 비어 있거나 타입이 잘못된 경우, 사용자 에이전트는 MAY Document에서 적절한 대체값을 찾아 manifest 멤버를 보완할 수 있습니다(예: application-name을 name 또는 short_name 대신 사용). 또는 사용자 에이전트는 SHOULD 플랫폼 규약에 따라 "제목 없음" 등 기본 이름을 부여할 수 있습니다. 또는 사용자 에이전트는 MAY 최종 사용자가 직접 애플리케이션 이름을 입력하도록 허용할 수 있습니다.

name 및 short_name 멤버가 모두 있을 때, 어느 멤버를 사용할지는 구현에 따라 공간에 맞게 결정됩니다(예: short_name 멤버가 아이콘 아래에 표시되기에 더 적합할 수 있음).

4.2 웹 애플리케이션 실행

운영체제 또는 사용자 에이전트의 재량에 따라, 웹 애플리케이션 실행 단계를 처리된 manifest를 이용해 수행합니다.

참고

이는 사용자가 앱 실행 UI(예: 홈 화면, 런처, 시작 메뉴)에서 설치된 웹 앱을 선택할 때 일반적으로 발생합니다.

웹 애플리케이션 실행 단계는 다음 알고리즘에 따라 수행됩니다. 이 알고리즘은 처리된 manifest manifest, 선택적으로 URL target URL, 선택적으로 POST resource POST resource를 받아 애플리케이션 컨텍스트를 반환합니다.

target URL이 주어진 경우, MUST manifest의 범위 내에 있어야 합니다.

다른 명세에서 이 알고리즘을 자신만의 단계로 대체할 수 있습니다(MAY). 대체 시 모든 웹 애플리케이션 실행 호출에 적용됩니다.

참고

이 알고리즘은 실험적 launch_handler manifest 필드를 통해 모든 웹 앱 실행 동작을 구성할 수 있도록 교체가 가능합니다. 교체 알고리즘은 기본적으로 새 애플리케이션 컨텍스트 생성을 호출하지만, 특정 조건에서는 다르게 동작합니다.

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

새 애플리케이션 컨텍스트 생성 단계는 다음 알고리즘에 따라 수행됩니다. 이 알고리즘은 처리된 manifest manifest, 선택적으로 URL target URL, 선택적으로 POST resource POST resource를 받아 애플리케이션 컨텍스트를 반환합니다.

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

4.3 개인정보 및 보안 고려사항

웹 애플리케이션을 설치할 수 있게 하는 UI는 아이콘, 이름, start URL, origin 등 웹 애플리케이션 관련 정보를 검사할 수 있게 해야 합니다(RECOMMENDED). 이는 최종 사용자가 설치 전 웹 애플리케이션 정보를 승인 또는 수정할 기회를 갖게 하기 위함입니다. 또한 사용자가 아이콘이나 이름을 예기치 않게 사용하여 다른 앱을 사칭하는지 구별할 수 있도록 합니다.

사용자 에이전트는 다른 애플리케이션이 시스템에 어떤 애플리케이션이 설치되어 있는지 알 수 없도록 해야 합니다(RECOMMENDED). 예를 들어, 사용자 에이전트의 캐시에서 manifest에 연결된 리소스(예: 아이콘)를 설치 후 무효화하거나, 일반 웹 브라우징과 다른 캐시를 사용할 수 있습니다.

4.4 제거

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

제거 시점에 사용자 에이전트가 권한, 영구 저장소 등 애플리케이션과 연결된 기타 영구 데이터 및 설정을 철회할 기회를 사용자에게 제공하는 것이 RECOMMENDED입니다.

6. 디스플레이 모드

디스플레이 모드는 웹 애플리케이션이 OS에서 어떤 방식으로 표시되는지를 나타냅니다(예: 전체 화면 등). 디스플레이 모드는 특정 플랫폼에서 사용되는 사용자 인터페이스(UI) 은유와 기능에 대응합니다. 디스플레이 모드의 UI 규약은 권고 사항일 뿐이며, 구현자는 자유롭게 해석할 수 있습니다.

이 명세는 다음 디스플레이 모드를 정의합니다:

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

fullscreen 디스플레이 모드는 Fullscreen API 현행 표준과 독립적으로 동작합니다. fullscreen 디스플레이 모드는 브라우저 창의 전체 화면 상태에 영향을 주지만, [FULLSCREEN] API는 뷰포트 내의 요소에 대해 작동합니다. 따라서 웹 애플리케이션이 디스플레이 모드를 fullscreen으로 설정해도, document.fullScreenElement는 null, fullscreenEnabled는 false를 반환할 수 있습니다.

사용자 에이전트가 특정 디스플레이 모드를 적용하면, 해당 모드는 기본 디스플레이 모드가 되어 최상위 브라우징 컨텍스트에서 사용됩니다(즉, 윈도우가 네비게이트될 때 디스플레이 모드로 사용됨). 사용자 에이전트는 보안(예: 최상위 브라우징 컨텍스트가 다른 origin으로 네비게이트된 경우 등) 또는 사용자에게 디스플레이 모드 전환 수단을 제공할 수 있습니다(MAY).

display 멤버가 없거나, 유효하지 않으면 사용자 에이전트는 browser 디스플레이 모드를 기본 디스플레이 모드로 사용합니다. 따라서 사용자 에이전트는 browser 디스플레이 모드를 MUST 지원해야 합니다.

모든 디스플레이 모드는 폴백 체인(fallback chain)을 가지며, 이는 디스플레이 모드 목록입니다. 각 폴백 체인은 다음과 같습니다:

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

웹 앱의 선택된 디스플레이 모드 결정 단계 는 다음 알고리즘에 따라 수행됩니다. 이 알고리즘은 처리된 manifest manifest를 받아 디스플레이 모드를 반환합니다.

  1. 처리 확장 지점: 이 단계에서 독자적/기타 지원되는 디스플레이 모드를 처리합니다.
  2. 사용자 에이전트가 manifest["display"]를 지원하면, manifest["display"]를 반환합니다.
  3. 각 fallback_mode에 대해 폴백 체인에서 반복합니다:
    1. 사용자 에이전트가 fallback_mode를 지원하면, fallback_mode를 반환합니다.
참고

위 반복문은 항상 값을 반환합니다. 왜냐하면 browser가 모든 모드의 폴백 체인에 포함되어 있고, 모든 사용자 에이전트가 browser 디스플레이 모드를 지원해야 하기 때문입니다.

디스플레이 모드 리스트는 다음 목록(list)입니다: « "fullscreen", "standalone", "minimal-ui", "browser" ».

사용자 에이전트는 웹 애플리케이션에 적용된 디스플레이 모드를 display-mode 미디어 특성에 반영해야 합니다(MUST) [MEDIAQUERIES-5].

참고

사용자 에이전트는 실제로 적용된 디스플레이 모드(반드시 manifest에 선언된 모드일 필요는 없음)를 display-mode 미디어 특성을 통해 노출합니다(CSS 또는 JavaScript로 접근 가능). 이 미디어 특성은 manifest가 적용되지 않은 경우에도 다른 웹 페이지의 디스플레이 모드를 반영합니다. 예: 사용자가 전체 화면으로 페이지를 전환하면, 사용자 에이전트는 display-mode 미디어 특성을 통해 CSS 및 스크립트에 이 변경을 반영합니다.

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

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

매니페스트 형식은 JSON이고 [UNICODE]로 인코딩됩니다. [JSON] 및 [UNICODE-SECURITY]에 기술된 보안 고려사항이 적용됩니다. 또한, 개발자가 매니페스트에 맞춤/제약 없는 데이터를 포함하는 것을 막을 방법이 없으므로, 구현자는 제약 없는 멤버 타입의 값에 대해 자체 구현 제한을 두어야 합니다(예: 서비스 거부 공격 방지, 메모리 부족 방지, 플랫폼별 제한 대응 등).

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

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

이 명세는 매니페스트의 특정 멤버에서 URL 선언을 허용하므로, 구현자는 [URL] 명세에서 논의된 보안 고려사항을 검토해야 합니다. 매니페스트에서 찾은 IRIs 및 IDNA 주소를 표시하려는 구현은 [UNICODE-SECURITY]의 보안 조언을 반드시 따르길 권장합니다.

개발자는 [CSP3] 명세 전체에서 논의된 보안 사항, 특히 data:를 매니페스트 인라인 소스로 허용하는 경우를 인지해야 합니다. 이렇게 하면 매니페스트가 문서 내에 직접 포함될 수 있게 되어 XSS 공격이 가능해지므로, 완전히 피하는 것이 최선입니다.

웹 애플리케이션을 설치할 수 있는 UI는 아이콘, 이름, start URL, origin 등 웹 애플리케이션 정보를 검사할 수 있게 해야 합니다(RECOMMENDED). 이는 사용자가 설치 전에 웹 애플리케이션 정보를 승인 또는 수정할 기회를 갖게 하기 위함입니다. 또한 웹 애플리케이션이 아이콘이나 이름을 통해 다른 앱을 사칭하는지 구별하는 데에도 도움이 됩니다.

사용자 에이전트는 다른 애플리케이션이 시스템에 어떤 앱이 설치되어 있는지 알 수 없도록 해야 합니다(RECOMMENDED). 예를 들어, 웹 애플리케이션 설치 후, 매니페스트에 연결된 리소스(예: 아이콘)를 캐시에서 무효화하거나, 일반 웹 브라우징과는 별도의 캐시를 사용하는 방식 등이 있습니다.

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

웹 애플리케이션이 실행 중일 때, 사용자 에이전트는 사용자가 웹 애플리케이션의 origin, 시작 및 현재 URL, 부여된 권한, 연관 아이콘 등 일반 정보를 확인할 수 있는 수단을 제공하는 것이 RECOMMENDED입니다. 이러한 정보가 어떻게 노출되는지는 구현자에게 맡깁니다.

또한, manifest가 디스플레이 모드를 "browser"가 아닌 값으로 설정할 때, 사용자 에이전트는 사용자가 일반 브라우저 컨텍스트를 벗어났음을 명확히 표시하는 것이 RECOMMENDED입니다. 이상적으로는 웹 애플리케이션 실행/전환이 호스트 플랫폼의 다른 앱 실행/전환과 일관되게 이루어져야 합니다(예: 길고 명확한 애니메이션 전환, "애플리케이션 X 실행" 음성 안내 등).

display 멤버는 origin이 사용자 에이전트의 네이티브 UI 일부를 제어할 수 있게 합니다. 전체 화면을 점유한 후, 다른 앱의 UI를 모방하려 할 수도 있습니다. 이는 'display-mode' 미디어 특성 [MEDIAQUERIES-5]을 통해서도 가능하며, 스크립트가 웹 애플리케이션의 디스플레이 모드를 알 수 있습니다.

A. IANA 고려사항

mime 타입 application/manifest+json 은 application manifest 미디어 타입입니다. mime 타입과 .webmanifest 파일 확장자는 등록됨 (IANA).

A.1 미디어 타입 등록

매니페스트가 전송되는 프로토콜이 [MIME-TYPES] 명세를 지원한다면(예: HTTP), 매니페스트에 application manifest 미디어 타입을 RECOMMENDED로 라벨링해야 합니다.

타입 이름:
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입니다.

참고

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

B.1 확장성

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

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

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

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

편집자가 명세를 작성하면서 임시로 이 명세를 패치하고 싶을 경우 구현이 따라갈 수 있도록 이슈를 등록해 커뮤니티에 알리세요.

B.1.1 독자적 매니페스트 멤버

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

독자적 확장은 바람직하지 않지만, 현실적으로 피할 수 없습니다. user agent가 본 명세에 없는 매니페스트 JSON 멤버를 해석하고자 한다면, 신중히 처리해야 합니다.

독자적 확장을 추가하는 구현자는 그것이 표준이 될 수 있는지(즉, 지금은 관심을 보이지 않더라도 다른 플랫폼의 user agent가 해당 멤버를 활용할 수 있을지) 고민해보세요. 표준화가 가능하다면, 벤더 중립적으로 API를 설계하여 표준 제안을 해주세요. 진정한 독자적(특정 생태계에만 의미가 있는) 멤버라면, 이름 충돌 방지를 위해 해당 생태계의 짧은 이름으로 접두어를 붙이세요.

표준이 되면 접두어를 제거할 의도로 접두어를 붙이는 관행은 지양하세요(영원히 남게 됩니다). 현재와 미래에 모두 의미가 있는 접두어만 사용하세요.

독자적 확장은 Extensions Registry에 추가하는 것을 권장합니다. 커뮤니티가 벤더/웹 커뮤니티가 정의·문서화한 확장 기능을 추적할 수 있습니다. 주기적으로 표준화 대상으로 검토할 예정입니다.

아래는 세 가지 가상의 독자적 확장 예시입니다.

예시 13: 독자적 확장 
{
...
"kpl_fancy_feature": "some/url/img",
"gmpc_awesome_thing": { ... },
"blitzly_site_verification": "KEY_9864D0966935"
...
}
참고

이 예시에서 의도적으로 (가공의) 외부 사이트 또는 서비스 이름을 사용했습니다. 브라우저나 브라우저 벤더 이름이 아닙니다. 이는 브라우저가 만든 벤더 프리픽스가 아니라, 독자적 서비스의 프리픽스입니다.

C. 애플리케이션 정보

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

Web Application Manifest의 여러 멤버는 디지털 스토어, 설치 다이얼로그, 기타 웹 애플리케이션이 홍보·배포되는 환경에서 웹 애플리케이션 표시 방식과 관련된 추가 메타데이터를 제공합니다. 이러한 사용 사례를 더 잘 지원하기 위해, 다음 멤버는 Web App Manifest - Application Information로 이동되었습니다:

E. JSON 스키마

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

매니페스트 문서를 검증하고자 하는 개발자는 매니페스트 포맷용 비공식 JSON 스키마를 schemastore.org에서 확인할 수 있습니다. Apache 2.0 라이선스로 제공되며, Mads Kristensen가 관리합니다. 만약 개발자가 JSON 스키마에 문제를 발견하면, SchemaStore repository의 GitHub에서 버그를 등록해 주세요.

참고: Web Manifest JSON 스키마

F. 국제화

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

작성자는 매니페스트 내용을 지역화할 때 다음 옵션 중 하나를 사용할 것으로 예상됩니다:

매니페스트 내 지역화 값:
작성자는 지역화 가능한 멤버에 대해 지역화 값을 매니페스트에 명시할 수 있습니다. 사용자 에이전트는 모든 지역화 값을 호스트 운영체제에 전달합니다. 사용자가 locale을 OS 수준에서 변경하면, OS는 설치된 웹 애플리케이션의 업데이트된 지역화 값을 표시할 수 있습니다.
언어 동적 설정:
예를 들어, 최종 사용자에게 선호하는 언어를 물은 뒤, 그 언어에 맞춰 manifest link 관계를 동적으로 추가/교체할 수 있습니다(예: "manifest.php?lang=fr" 같은 URL 사용).
서버에서 content-negotiation, 지오타겟팅 등 사용:
웹 애플리케이션을 호스팅하는 서버가 지오타겟팅 또는 content negotiation(예: HTTP "Accept-Language" 헤더 [RFC9110], 또는 커스텀 HTTP 헤더 등)을 통해 사용자의 언어를 미리 결정할 수 있습니다.

위 옵션을 고려할 때, 개발자는 최종 사용자의 언어 선호도와 관련된 개인정보에 유의해야 합니다: 사용자가 웹 애플리케이션에 명시적으로 언어 선호도를 지정한 경우(즉, 사용자 에이전트의 기본 언어 설정만 사용하는 것이 아닐 때), 선호 언어를 평문으로 전송하는 것은 일반적으로 바람직하지 않습니다. 이렇게 하면 최종 사용자의 개인정보가 노출될 수 있습니다. 따라서 개발자는 [TLS]를 사용하여 웹 애플리케이션의 광범위한 모니터링 가능성을 줄일 것을 권장합니다([RFC7258]).

G. 사용 사례 및 요구사항

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

H. 이슈 요약

이 명세에는 등재된 이슈가 없습니다.

I. 변경 로그

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

다음은 최초 공개 워킹 드래프트 이후에 이루어진 주요 변경사항입니다:

J. 감사의 글

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

본 문서는 [HTML] 명세의 텍스트를 해당 명세의 라이선스가 허용하는 범위 내에서 재사용하였습니다.

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

Claudio Gomboli는 아이콘 예시 이미지에 기여했습니다.

인디애나 대학교 블루밍턴의 보안 연구자들은 범위 밖 네비게이션과 관련된 잠재적 위험을 보고함으로써 본 명세에 기여하였습니다.

K. 색인

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

K.2 참조로 정의된 용어

L. 참고 문헌

L.1 규범적 참고 문헌

[accname-1.2]
Accessible Name and Description Computation 1.2. Bryan Garaventa; Melanie Sumner. W3C. 2025년 4월 3일. W3C 워킹 드래프트. URL: https://www.w3.org/TR/accname-1.2/
[BCP47]
언어 식별 태그(Tags for Identifying Languages). A. Phillips, Ed.; M. Davis, Ed. IETF. 2009년 9월. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc5646
[CSP3]
콘텐츠 보안 정책 3(Content Security Policy Level 3). Mike West; Antonio Sartori. W3C. 2025년 4월 30일. W3C 워킹 드래프트. URL: https://www.w3.org/TR/CSP3/
[css-color-4]
CSS 색상 모듈 4단계(CSS Color Module Level 4). Chris Lilley; Tab Atkins Jr.; Lea Verou. W3C. 2025년 4월 24일. CRD. URL: https://www.w3.org/TR/css-color-4/
[CSS-MIME]
text/css 미디어 타입(The text/css Media Type). H. Lie; B. Bos; C. Lilley. IETF. 1998년 3월. 정보성. URL: https://www.rfc-editor.org/rfc/rfc2318
[css-syntax-3]
CSS 구문 모듈 3단계(CSS Syntax Module Level 3). Tab Atkins Jr.; Simon Sapin. W3C. 2021년 12월 24일. CRD. URL: https://www.w3.org/TR/css-syntax-3/
[dom]
DOM 현행 표준(DOM Standard). Anne van Kesteren. WHATWG. 현행 표준. URL: https://dom.spec.whatwg.org/
[ECMA-402]
ECMAScript 국제화 API 명세(ECMAScript Internationalization API Specification). Ecma International. URL: https://tc39.es/ecma402/
[ECMAScript-MIME]
스크립트 미디어 타입(Scripting Media Types). B. Hoehrmann. IETF. 2006년 4월. 정보성. URL: https://www.rfc-editor.org/rfc/rfc4329
[fetch]
Fetch 현행 표준(Fetch Standard). Anne van Kesteren. WHATWG. 현행 표준. URL: https://fetch.spec.whatwg.org/
[HTML]
HTML 현행 표준(HTML Standard). Anne van Kesteren; Domenic Denicola; Dominic Farolino; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. 현행 표준. URL: https://html.spec.whatwg.org/multipage/
[image-resource]
이미지 리소스(Image Resource). Aaron Gustafson; Rayan Kanso; Marcos Caceres. W3C. 2021년 6월 4일. W3C 워킹 드래프트. URL: https://www.w3.org/TR/image-resource/
[infra]
Infra 현행 표준(Infra Standard). Anne van Kesteren; Domenic Denicola. WHATWG. 현행 표준. URL: https://infra.spec.whatwg.org/
[JSON]
자바스크립트 객체 표기법(JSON) 데이터 교환 형식(The JavaScript Object Notation (JSON) Data Interchange Format). T. Bray, Ed. IETF. 2017년 12월. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc8259
[MEDIAQUERIES-5]
미디어 쿼리 5단계(Media Queries Level 5). Dean Jackson; Florian Rivoal; Tab Atkins Jr.; Daniel Libby. W3C. 2021년 12월 18일. W3C 워킹 드래프트. URL: https://www.w3.org/TR/mediaqueries-5/
[MIME-TYPES]
다목적 인터넷 메일 확장(Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types). N. Freed; N. Borenstein. IETF. 1996년 11월. Draft Standard. URL: https://www.rfc-editor.org/rfc/rfc2046
[permissions]
권한(Permissions). Marcos Caceres; Mike Taylor. W3C. 2024년 12월 20일. W3C 워킹 드래프트. URL: https://www.w3.org/TR/permissions/
[RFC2119]
RFC에서 요구 수준을 나타내기 위한 키워드(Key words for use in RFCs to Indicate Requirement Levels). S. Bradner. IETF. 1997년 3월. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC7159]
자바스크립트 객체 표기법(JSON) 데이터 교환 형식(The JavaScript Object Notation (JSON) Data Interchange Format). T. Bray, Ed. IETF. 2014년 3월. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7159
[RFC8174]
RFC 2119 키워드의 대소문자 모호성(Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words). B. Leiba. IETF. 2017년 5월. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
[SCREEN-ORIENTATION]
화면 방향(Screen Orientation). Marcos Caceres. W3C. 2023년 8월 9일. W3C 워킹 드래프트. URL: https://www.w3.org/TR/screen-orientation/
[UAX9]
유니코드 양방향 알고리즘(Unicode Bidirectional Algorithm). Manish Goregaokar मनीष गोरेगांवकर; Robin Leroy. Unicode Consortium. 2024년 9월 2일. Unicode Standard Annex #9. URL: https://www.unicode.org/reports/tr9/tr9-50.html
[UNICODE]
유니코드 현행 표준(The Unicode Standard). Unicode Consortium. URL: https://www.unicode.org/versions/latest/
[UNICODE-SECURITY]
유니코드 보안 고려사항(Unicode Security Considerations). Mark Davis; Michel Suignard. Unicode Consortium. 2014년 9월 19일. Unicode Technical Report #36. URL: https://www.unicode.org/reports/tr36/tr36-15.html
[URL]
URL 현행 표준(URL Standard). Anne van Kesteren. WHATWG. 현행 표준. URL: https://url.spec.whatwg.org/
[UTS55]
유니코드 소스코드 처리(Unicode Source Code Handling). Robin Leroy; Mark Davis. Unicode Consortium. 2024년 1월 29일. Unicode Technical Standard #55. URL: https://www.unicode.org/reports/tr55/tr55-5.html

L.2 비규범적 참고 문헌

[FULLSCREEN]
전체화면 API 현행 표준(Fullscreen API Standard). Philip Jägenstedt. WHATWG. 현행 표준. URL: https://fullscreen.spec.whatwg.org/
[i18n-glossary]
국제화 용어집(Internationalization Glossary). Richard Ishida; Addison Phillips. W3C. 2024년 10월 17일. W3C 워킹 그룹 노트. URL: https://www.w3.org/TR/i18n-glossary/
[manifest-app-info]
웹 앱 매니페스트 - 애플리케이션 정보(Web App Manifest - Application Information). Aaron Gustafson. W3C. 2023년 8월 21일. W3C 워킹 그룹 노트. URL: https://www.w3.org/TR/manifest-app-info/
[mimesniff]
MIME 스니핑 현행 표준(MIME Sniffing Standard). Gordon P. Hemsley. WHATWG. 현행 표준. URL: https://mimesniff.spec.whatwg.org/
[RFC7258]
Pervasive Monitoring Is an Attack. S. Farrell; H. Tschofenig. IETF. 2014년 5월. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc7258
[RFC9110]
HTTP 시맨틱스(HTTP Semantics). R. Fielding, Ed.; M. Nottingham, Ed.; J. Reschke, Ed. IETF. 2022년 6월. Internet Standard. URL: https://httpwg.org/specs/rfc9110.html
[SERVICE-WORKERS-1]
서비스 워커(Service Workers). Yoshisato Yanagisawa; Monica CHINTALA. W3C. 2025년 3월 6일. CRD. URL: https://www.w3.org/TR/service-workers/
[TLS]
전송 계층 보안(TLS) 프로토콜 1.2(The Transport Layer Security (TLS) Protocol Version 1.2). T. Dierks; E. Rescorla. IETF. 2008년 8월. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc5246
[webidl]
Web IDL 현행 표준(Web IDL Standard). Edgar Chen; Timothy Gu. WHATWG. 현행 표준. URL: https://webidl.spec.whatwg.org/