웹 앱 매니페스트 추가

브라우저 지원

  • 39
  • 79
  • x
  • x

소스

웹 앱 매니페스트는 프로그레시브 웹 앱 (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_namename

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

icons

사용자가 PWA를 설치할 때 홈 화면, 앱 런처, 작업 전환기, 스플래시 화면 및 다른 위치에서 사용할 브라우저 아이콘 집합을 정의할 수 있습니다.

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

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 요소를 숨깁니다.
독립형 디스플레이가 있는 PWA 창의 예
독립형 UI.
minimal-ui 이 모드는 standalone와 유사하지만 뒤로 및 새로고침 버튼과 같은 탐색을 제어하기 위한 최소한의 UI 요소 집합을 사용자에게 제공합니다.
최소 UI 디스플레이가 있는 PWA 창의 예
최소한 UI.
browser 표준 브라우저 환경입니다.

display_override

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

브라우저에서 display 속성 전에 고려하는 display_override 속성을 사용하여 자체 대체 시퀀스를 설정할 수 있습니다. 값은 나열된 순서대로 고려되는 문자열 시퀀스이며 지원되는 첫 번째 디스플레이 모드가 적용됩니다. 아무것도 지원되지 않으면 브라우저는 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_urlscope 속성에 정의된 경로를 기준으로 합니다.
  • /로 시작하는 start_url는 항상 출처의 루트가 됩니다.

theme_color

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

맞춤 theme_color가 포함된 PWA 창의 예
맞춤 theme_color가 있는 PWA 창의 예

미디어 쿼리의 theme_color

브라우저 지원

  • 93
  • 93
  • 106
  • 15

소스

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 속성은 앱 내의 주요 작업에 빠르게 액세스할 수 있는 앱 바로가기 객체의 배열입니다. 각 구성원은 최소한 nameurl를 포함하는 사전입니다.

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개 표시합니다. 나머지는 무시됩니다.

데스크톱 및 모바일의 다양한 설치 UI 스크린샷
데스크톱과 모바일의 설치 UI가 더욱 풍부해졌습니다.

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

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

매니페스트 테스트

매니페스트가 올바르게 설정되었는지 확인하려면 Chrome DevTools의 애플리케이션 패널에 있는 매니페스트 창을 사용합니다.

매니페스트 탭이 선택된 Chrome Devtools의 애플리케이션 패널
DevTools에서 매니페스트를 테스트합니다.

이 창에서는 많은 매니페스트 속성의 사람이 읽을 수 있는 버전을 제공하며 이를 통해 모든 이미지가 제대로 로드되고 있는지 확인할 수 있습니다.

휴대기기의 스플래시 화면

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

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

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

추가 자료

웹 앱 매니페스트에 추가할 수 있는 다른 속성에 관한 자세한 내용은 MDN 웹 앱 매니페스트 문서를 참고하세요.