manifest – Kapital Letter Tech Blog

Manifest?

PWA가 단순한 웹에서 앱이 되는 전환점은 manifest.json에 있다.

이 파일은 브라우저에게 이 웹이 앱처럼 설치될 수 있다는 신호를 준다.

즉, 웹의 메타데이터(metadata) 역할을 하며

아이콘, 이름, 시작 경로, 표시 모드(display mode) 등을 정의한다.

Manifest 파일의 기본 구조

{
  "name": "Lux Store",
  "short_name": "Lux",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#111111",
  "icons": [
    {
      "src": "/icons/icon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

필드	역할
name	앱의 전체 이름, 홈 화면에 표시될 이름
short_name	아이콘 아래 짧은 이름
start_url	앱 실행 시 처음 열릴 경로
display	앱 표시 방식(standalone, fullscreen, minimal-ui, browser)
background_color	스플래시 화면의 배경색
theme_color	브라우저 툴바 색상
icons	설치 아이콘 이미지(192px, 512px 이상 권장)

Display 모드가 바꾸는 UX

display 속성은 앱이 실행될 때의 화면 형태를 결정한다.

일반적으로는 PWA는 standalone을 사용,

사용자는 홈 화면에서 실행했을 때 브라우저 UI가 사라지고 앱 전용 창을 오픈한 경험을 얻는다.

browser: 일반 웹처럼 주소창・탭 노출
minimal-ui: 주소창만 최소화된 브라우저
standalone: 앱처럼 동작, 주소창 없음
fullscreen: 완전한 전체 화면 모드

Add to Home Screen(A2HS) 동작 과정

브라우저는 다음 조건이 충족되면 이 웹을 설치할 수 있다는 프로그래시브 신호를 감지한다.

다음 조건이 만족되면 Chrome, Edge 등은 자동으로 A2HS 가능 상태로 전환한다.

설치 조건
1. HTTPS 환경에서 제공될 것
2. 유효한 manifest.json이 존재할 것
3. Service Worker가 등록되어 있을 것

beforeinstallprompt 이벤트로 제어하기

브라우저가 설치 가능한 상태가 되면, beforeinstallprompt 이벤트가 발생한다.

개발자는 사용자에게 언제, 어떻게 설치 안내를 띄울지 설정할 수 있다.

예를 들어, 페이지 진입 10초후에 설치 배너 표시하려고 할 때:

let deferredPrompt;

window.addEventListener('beforeinstallprompt', (e) => {
  e.preventDefault();
  deferredPrompt = e;

  // 커스텀 설치 버튼 노출
  const installBtn = document.querySelector('#install-btn');
  installBtn.style.display = 'block';

  installBtn.addEventListener('click', async () => {
    deferredPrompt.prompt();
    const choice = await deferredPrompt.userChoice;
    if (choice.outcome === 'accepted') {
      console.log('사용자가 설치를 수락했습니다.');
    }
    deferredPrompt = null;
  });
});

홈 화면에 추가된 후

설치가 완료되면, 브라우저는 manifest의 정보를 기반으로 OS 수준의 앱 아이콘을 생성한다.

설치된 PWA는 이후 브라우저 캐시 및 서비스 워커를 통해 오프라인에서도 실행 가능.

Android: 런처 아이콘으로 표시, 실행 시 standalone 창에서 구동
iOS(Safari): 홈 화면에 추가 수동 트리거 방식(자동 배너 없음)
데스크톱 Chrome: 앱 설치 시 OS 프로그램 목록에도 추가됨

설치 UX를 CTA(Call To Action)로 디자인하면 전환율이 높아진다.

e.g. 앱으로 더 빠르게 열기

manifest 검증과 진단은 어떻게 할까?

Chrome DevTools → Application → Manifest 탭에서 설치 가능 여부를 실시간으로 확인 가능.

[Lighthouse]의 [Progressive Web App] 카테고리를 통해 다음 항목을 자동으로 점검할 수 있다.

manifest 유효성
앱 설치 가능 여부
오프라인 대응 여부
HTTPS 보안 연결 상태

[태그:] manifest

PWA 핵심 구성요소: Manifest