웹 앱 매니페스트 추가

François Beaufort

Pete LePage

Thomas Steiner

Alexey Rodionov

웹 앱 매니페스트는 브라우저에 프로그레시브 웹 앱(PWA)이 사용자의 데스크톱 또는 휴대기기에 설치될 때 어떻게 동작해야 하는지 알려주는 JSON 파일입니다. 일반적인 매니페스트 파일에는 다음이 포함됩니다.

• 앱의 이름
• 앱에서 사용해야 하는 아이콘
• 앱이 실행될 때 열려야 하는 URL

매니페스트 파일 만들기

매니페스트 파일의 이름은 무엇이든 지정할 수 있지만 일반적으로 manifest.json이며 루트(웹사이트의 최상위 디렉터리)에서 제공됩니다. 사양에서는 확장자가 .webmanifest여야 한다고 제안하지만 JSON 파일을 사용하여 매니페스트를 더 명확하게 읽을 수 있도록 할 수 있습니다.

일반적인 매니페스트는 다음과 같습니다.

{
  "short_name": "Weather",
  "name": "Weather: Do I need an umbrella?",
  "icons": [
    {
      "src": "/images/icons-vector.svg",
      "type": "image/svg+xml",
      "sizes": "512x512"
    },
    {
      "src": "/images/icons-192.png",
      "type": "image/png",
      "sizes": "192x192"
    },
    {
      "src": "/images/icons-512.png",
      "type": "image/png",
      "sizes": "512x512"
    }
  ],
  "id": "/?source=pwa",
  "start_url": "/?source=pwa",
  "background_color": "#3367D6",
  "display": "standalone",
  "scope": "/",
  "theme_color": "#3367D6",
  "shortcuts": [
    {
      "name": "How's the weather today?",
      "short_name": "Today",
      "description": "View weather information for today",
      "url": "/today?source=pwa",
      "icons": [{ "src": "/images/today.png", "sizes": "192x192" }]
    },
    {
      "name": "How's the weather tomorrow?",
      "short_name": "Tomorrow",
      "description": "View weather information for tomorrow",
      "url": "/tomorrow?source=pwa",
      "icons": [{ "src": "/images/tomorrow.png", "sizes": "192x192" }]
    }
  ],
  "description": "Weather forecast information",
  "screenshots": [
    {
      "src": "/images/screenshot1.png",
      "type": "image/png",
      "sizes": "540x720",
      "form_factor": "narrow"
    },
    {
      "src": "/images/screenshot2.jpg",
      "type": "image/jpg",
      "sizes": "720x540",
      "form_factor": "wide"
    }
  ]
}

주요 매니페스트 속성

short_name 및 name

매니페스트에 short_name 또는 name 중 하나 이상을 제공해야 합니다. 둘 다 제공하는 경우 name는 앱이 설치될 때 사용되고 short_name는 사용자의 홈 화면, 런처 또는 공간이 제한된 다른 위치에서 사용됩니다.

icons

사용자가 PWA를 설치하면 브라우저에서 홈 화면, 앱 런처, 작업 전환 도구, 시작 화면, 기타 위치에 사용할 아이콘 세트를 정의할 수 있습니다.

icons 속성은 이미지 객체의 배열입니다. 각 객체에는 src, sizes 속성, 이미지의 type가 포함되어야 합니다. Android에서 적응형 아이콘이라고도 하는 마스킹 가능한 아이콘을 사용하려면 icon 속성에 "purpose": "any maskable"를 추가합니다.

Chromium의 경우 192x192픽셀 아이콘과 512x512픽셀 아이콘을 제공해야 합니다. 이 두 가지 아이콘 크기만 제공되면 Chrome은 기기에 맞게 아이콘 크기를 자동으로 조정합니다. 자체 아이콘의 크기를 조정하고 픽셀 정밀도로 조정하려면 48dp 단위로 아이콘을 제공하세요.

id

id 속성을 사용하면 애플리케이션에 사용되는 식별자를 명시적으로 정의할 수 있습니다. 매니페스트에 id 속성을 추가하면 start_url의 종속 항목이나 매니페스트의 위치가 삭제되고 나중에 이를 업데이트할 수 있습니다. 자세한 내용은 웹 앱 매니페스트 ID 속성으로 PWA 고유 식별을 참고하세요.

start_url

start_url는 필수 속성입니다. 실행 시 브라우저에 앱의 시작 위치를 알려주고 사용자가 홈 화면에 앱을 추가할 때 어떤 페이지에 있든 앱이 시작되지 않도록 합니다.

start_url는 사용자를 제품 방문 페이지가 아닌 앱으로 바로 연결해야 합니다. 사용자가 앱을 연 직후 무엇을 하고 싶어할지 생각해 보고 그 위치에 배치합니다.

background_color

background_color 속성은 애플리케이션이 모바일에서 처음 실행될 때 스플래시 화면에 사용됩니다.

display

앱이 실행될 때 표시되는 브라우저 UI를 맞춤설정할 수 있습니다. 예를 들어 주소 표시줄과 브라우저 사용자 인터페이스 요소를 숨길 수 있습니다. 게임을 전체 화면으로 실행하도록 설정할 수도 있습니다. display 속성은 다음 값 중 하나를 사용합니다.

속성	동작
fullscreen	브라우저 UI 없이 웹 앱을 열고 사용 가능한 모든 디스플레이 영역을 차지합니다.
standalone	웹 앱을 열어 독립형 앱처럼 보이게 합니다. 앱은 브라우저와 별도의 창에서 실행되며 주소 표시줄과 같은 표준 브라우저 UI 요소를 숨깁니다.
minimal-ui	이 모드는 standalone와 유사하지만 뒤로 및 새로고침 버튼과 같이 탐색을 제어하기 위한 최소한의 UI 요소 집합을 사용자에게 제공합니다.
browser	표준 브라우저 환경

display_override

웹 앱이 표시되는 방식을 선택하려면 앞서 설명한 대로 매니페스트에서 display 모드를 설정합니다. 브라우저는 모든 디스플레이 모드를 지원할 필요는 없지만 사양 정의 대체 체인("fullscreen" → "standalone" → "minimal-ui" → "browser")을 지원해야 합니다. 특정 모드를 지원하지 않는 경우 체인의 다음 디스플레이 모드로 대체됩니다. 드물지만 이러한 대체 방법으로 인해 문제가 발생할 수 있습니다. 예를 들어 개발자는 "minimal-ui"가 지원되지 않는 경우 "browser" 디스플레이 모드로 강제로 돌아가지 않고는 "minimal-ui"를 요청할 수 없습니다. 또한 현재 동작으로 인해 대체 체인에 위치하지 않으므로 이전 버전과 호환되는 방식으로 새 디스플레이 모드를 도입할 수 없습니다.

display_override 속성을 사용하여 자체 대체 시퀀스를 설정할 수 있습니다. 이 속성은 브라우저에서 display 속성보다 먼저 고려합니다. 값은 나열된 순서대로 고려되는 문자열의 시퀀스이며 지원되는 첫 번째 디스플레이 모드가 적용됩니다. 지원되는 항목이 없으면 브라우저는 display 필드 평가로 대체합니다. display 필드가 없으면 브라우저는 display_override를 무시합니다.

다음은 display_override를 사용하는 방법을 보여주는 예입니다. "window-control-overlay"의 세부정보는 이 페이지의 범위에 해당하지 않습니다.

{
  "display_override": ["window-control-overlay", "minimal-ui"],
  "display": "standalone",
}

이 앱을 로드할 때 브라우저는 먼저 "window-control-overlay"를 사용하려고 시도합니다. 사용할 수 없는 경우 "minimal-ui"로 대체된 후 display 속성에서 "standalone"로 대체됩니다. 이러한 방법을 사용할 수 없는 경우 브라우저는 표준 대체 체인으로 돌아갑니다.

scope

앱의 scope는 브라우저가 앱의 일부로 간주하는 URL의 집합입니다. scope는 앱의 모든 진입 지점과 종료 지점을 포함하는 URL 구조를 제어하고 브라우저에서는 이를 사용하여 사용자가 앱을 떠난 시점을 확인합니다.

scope에 관한 몇 가지 참고사항은 다음과 같습니다.

• 매니페스트에 scope를 포함하지 않으면 묵시적인 scope가 시작 URL이 되지만 파일 이름, 쿼리, 프래그먼트는 삭제됩니다.
• scope 속성은 상대 경로 (../) 또는 웹 앱에서 탐색 범위를 확대할 수 있는 상위 수준 경로 (/)일 수 있습니다.
• start_url가 범위에 있어야 합니다.
• start_url는 scope 속성에 정의된 경로를 기준으로 합니다.
• /로 시작하는 start_url는 항상 출처의 루트가 됩니다.

theme_color

theme_color는 툴바의 색상을 설정하며 작업 전환 도구의 앱 미리보기에 반영될 수 있습니다. theme_color은 문서 헤드에 지정된 meta 테마 색상과 일치해야 합니다.

미디어 쿼리의 theme_color

meta 테마 색상 요소의 media 속성을 사용하여 미디어 쿼리에서 theme_color를 조정할 수 있습니다. 예를 들어 이 방법으로 밝은 모드용 색상과 어두운 모드용 색상을 각각 정의할 수 있습니다. 그러나 매니페스트에서는 이러한 환경설정을 정의할 수 없습니다. 자세한 내용은 w3c/manifest#975 GitHub 문제를 참고하세요.

<meta name="theme-color" media="(prefers-color-scheme: light)" content="white">
<meta name="theme-color" media="(prefers-color-scheme: dark)"  content="black">

shortcuts

shortcuts 속성은 앱 내 주요 작업에 빠르게 액세스할 수 있는 앱 바로가기 객체의 배열입니다. 각 구성원은 name 및 url를 하나 이상 포함하는 사전입니다.

description

description 속성은 앱의 목적을 설명합니다.

Chrome의 모든 플랫폼에서 설명의 최대 길이는 300자(영문 기준)입니다. 설명이 이보다 길면 브라우저에서 말줄임표 문자로 잘립니다. Android의 경우 설명은 최대 7줄의 텍스트를 사용해야 합니다.

screenshots

screenshots 속성은 일반적인 사용 시나리오에서 앱을 나타내는 이미지 객체 배열입니다. 각 객체는 src, sizes 속성, 이미지의 type를 포함해야 합니다. form_factor 속성은 선택사항입니다. 넓은 화면에만 적용되는 스크린샷의 경우 "wide"로, 좁은 스크린샷의 경우 "narrow"로 설정할 수 있습니다.

Chrome에서 이미지는 다음 기준을 충족해야 합니다.

• 너비와 높이는 320픽셀 이상 3840픽셀 이하여야 합니다.
• 최대 크기는 최소 크기 길이의 2.3배를 초과할 수 없습니다.
• 적절한 폼 팩터와 일치하는 모든 스크린샷은 가로세로 비율이 동일해야 합니다.
  • Chrome 109부터는 form_factor가 "wide"로 설정된 스크린샷만 데스크톱에 표시됩니다.
• Chrome 109부터 form_factor가 "wide"로 설정된 스크린샷은 Android에서 무시됩니다. 이전 버전과의 호환성을 위해 form_factor가 없는 스크린샷도 계속 표시됩니다.

데스크톱의 Chrome에는 이 기준을 충족하는 스크린샷이 1개 이상 8개 이하로 표시됩니다. 나머지는 무시됩니다.

Android의 Chrome에서는 이러한 기준을 충족하는 스크린샷을 1~5개 표시합니다. 나머지는 무시됩니다.

페이지에 웹 앱 매니페스트 추가

매니페스트를 만든 후 프로그레시브 웹 앱의 모든 페이지에 <link> 태그를 추가합니다. 예를 들면 다음과 같습니다.

<link rel="manifest" href="/manifest.json">

매니페스트 테스트

매니페스트가 올바르게 설정되었는지 확인하려면 Chrome DevTools의 Application 패널에 있는 Manifest 창을 사용하세요.

이 창은 매니페스트의 여러 속성을 사람이 읽을 수 있는 버전으로 제공하며 모든 이미지가 제대로 로드되는지 확인할 수 있습니다.

모바일의 스플래시 화면

앱이 모바일에서 처음 실행되면 브라우저가 시작되고 초기 콘텐츠가 렌더링되기까지 잠시 시간이 걸릴 수 있습니다. 사용자에게 앱이 작동하지 않는 것으로 생각할 수 있는 흰색 화면을 표시하는 대신 브라우저는 첫 번째 페인트까지 스플래시 화면을 표시합니다.

Chrome은 매니페스트에 지정된 name, background_color, icons에서 자동으로 스플래시 화면을 생성합니다. 스플래시 화면에서 앱으로 원활하게 전환하려면 background_color을 로드 페이지와 동일한 색상으로 만듭니다.

Chrome은 스플래시 화면의 기기 해상도와 가장 근접한 아이콘을 선택합니다. 대부분의 경우 192픽셀 및 512픽셀 아이콘을 제공하면 충분하지만 더 나은 일치를 위해 아이콘을 추가로 제공할 수 있습니다.

추가 자료

웹 앱 매니페스트에 추가할 수 있는 다른 속성에 관해 알아보려면 MDN 웹 앱 매니페스트 문서를 참고하세요.