웹 앱 매니페스트

매니페스트란

웹 앱 매니페스트(Web App Manifest)는 앱이 설치됐을 때 어떻게 보이고 동작할지를 브라우저에 알려 주는 JSON 파일이다. head에서 <link rel="manifest">로 거는 방법과 meta 태그 대신 매니페스트를 쓰는 이유는 문서 head와 메타데이터에 있다.

• 앱 하나에 매니페스트 하나. 보통 루트에 두고, 설치할 수 있는 모든 HTML 페이지에서 링크한다.
• 확장자는 .webmanifest를 권장한다. 이름은 자유지만 application/manifest+json(또는 JSON 계열 MIME)으로 서빙해야 한다. 옛 앱은 manifest.json을 많이 쓴다.
• 모르는 필드는 무시될 뿐 매니페스트가 무효가 되지 않는다.
• Chromium은 DevTools 애플리케이션 > 매니페스트, Firefox는 애플리케이션 탭에서 확인한다. Safari에는 디버깅 화면이 없어 실제로 설치해 본다. 매니페스트가 안 잡히면 파일이 로드되는지, 콘텐츠 유형이 맞는지부터 본다.

{
  "id": "/",
  "name": "레시피 노트",
  "short_name": "레시피",
  "start_url": "/?source=pwa",
  "scope": "/",
  "display": "standalone",
  "theme_color": "#1f6feb",
  "background_color": "#ffffff",
  "icons": [
    { "src": "/icons/192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icons/512.png", "sizes": "512x512", "type": "image/png" },
    { "src": "/icons/maskable-512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
  ]
}

기본 필드

id와 start_url은 함부로 바꾸지 않는다

브라우저는 id(없으면 start_url)로 "같은 앱"인지 판단한다. id 없이 start_url의 쿼리 하나만 바꿔도 이미 설치된 앱을 다른 앱으로 볼 수 있다. 처음부터 id를 명시하고, 그다음에는 바꾸지 않는다. id를 바꾸면 새 앱으로 취급된다.

아이콘

• 마스크 가능 아이콘은 핵심 그림을 중앙의 반지름 40% 원(safe zone) 안에 두고, 512px 이상으로 만든다. "purpose": "maskable". 결과가 어색하면 여백을 더 준다.
• 아이콘이 없거나 크기가 안 맞으면 플랫폼에 따라 설치 기준을 못 맞추거나, 화면 캡처나 일반 아이콘으로 대체된다.

색과 테마

<!-- 다크 모드용 테마 색은 meta로 나눈다 -->
<meta name="theme-color" content="#ffffff" media="(prefers-color-scheme: light)">
<meta name="theme-color" content="#0d1117" media="(prefers-color-scheme: dark)">

색은 단색만 쓴다. 이름 있는 색, hex, 투명도 없는 rgb()·hsl()이다. 투명도(rgba()), CSS 변수, 그라디언트는 결과가 제각각이다. 폼 컨트롤 색은 매니페스트가 아니라 CSS accent-color가 맡는다(PWA 앱 경험 설계와 창 관리).

표시 방식: display와 display_override

flowchart LR
  subgraph ov["display_override: 먼저 평가"]
    o1["window-controls-overlay"] --> o2["tabbed"] --> o3["minimal-ui"]
  end
  subgraph df["display: 기본 대체 순서"]
    d1["fullscreen"] --> d2["standalone"] --> d3["minimal-ui"] --> d4["browser"]
  end
  o3 -->|"지원하는 값이 없으면 display로 내려간다"| d1

window-controls-overlay(제목 표시줄 영역을 앱이 그린다)와 tabbed(앱 창 안의 탭) 같은 새 값은 display가 아니라 display_override에 넣는다. 모르는 브라우저가 앱을 망가뜨리지 않게 하려는 구조다.

선택 필드

앱 바로 가기(shortcuts)

아이콘을 오른쪽 클릭하거나 길게 누르면 나오는 딥 링크 목록이다. 데스크톱 OS 대부분과 WebAPK로 설치된 Android에서 보인다.

"shortcuts": [
  { "name": "새 레시피", "short_name": "새로", "url": "/new?source=shortcut",
    "icons": [{ "src": "/icons/new-96.png", "sizes": "96x96" }] },
  { "name": "즐겨찾기", "url": "/favorites" }
]

• name과 url(스코프 안)은 필수, short_name·description·icons는 선택이다.
• 몇 개를 보일지, 아이콘을 쓸지는 브라우저가 정한다. Android Chrome은 앞의 몇 개만 보이므로 중요한 순서로 넣는다.
• 설치 뒤에는 매니페스트 업데이트가 반영돼야 바뀐다.

iOS·iPadOS가 따로 쓰는 것

apple-mobile-web-app-capable 같은 옛 meta 태그는 매니페스트 이전의 방식이다. start_url·scope를 무시하므로 새로 쓰지 않는다. iOS·iPadOS 26부터는 매니페스트가 없어도 홈 화면에 추가한 사이트가 기본으로 웹 앱으로 열리지만, 매니페스트가 있으면 이름·아이콘·시작 URL·범위가 그대로 반영된다.

바뀐 메타데이터가 반영되는 시점

정리

• 매니페스트 하나를 루트에 두고 설치 가능한 모든 페이지에서 링크한다.
• id를 처음부터 명시하고 바꾸지 않는다. start_url도 함부로 바꾸지 않는다.
• 아이콘은 불투명한 정사각형 192·512px + 마스크 가능 512px.
• 색은 단색만. 다크 모드 테마 색은 meta로 나눈다.
• 새 표시 방식은 display_override에, 큰 설치 화면을 원하면 description·screenshots를 넣는다.
• iOS 스플래시·상태 표시줄은 별도 link·meta로 다룬다.

관련 노트: 문서 head와 메타데이터, PWA 설치와 설치 유도, PWA 앱 경험 설계와 창 관리, PWA와 서비스 워커 캐시 전략