웹 앱 매니페스트(manifest.json) 검증 도구
manifest.json 내용을 붙여넣기만 하면 PWA 설치 조건을 충족하는지 검증합니다. name, start_url, display, icons 등 필수 항목과 maskable 아이콘 유무를 확인하여 문제점을 목록으로 표시합니다.
Tips
- name과 short_name은 둘 다 지정하는 것이 좋습니다. short_name이 없으면 홈 화면 아이콘 아래에 표시되는 문자열이 name에서 기계적으로 잘려 의도치 않은 표시가 될 수 있습니다.
- purpose: "maskable"을 가진 아이콘이 없으면 Android 등 일부 기기에서 아이콘 주변이 부자연스럽게 잘리거나 배경색이 비쳐 보일 수 있습니다. 기존 icons 배열에 maskable용 항목을 하나 추가하는 것만으로 해결할 수 있습니다.
- icons에는 192x192 이상 크기를 최소 1개, 가능하면 512x512 이상 크기도 준비해 주세요. 전자는 홈 화면 아이콘, 후자는 스플래시 화면 표시에 사용됩니다.
- Chrome 등 브라우저가 실제로 적용하는 PWA 설치 조건은 앞으로 변경될 수 있으므로, 이 도구의 판정 결과는 어디까지나 참고용으로 다루고 최종 확인은 Chrome DevTools의 Application 패널 등에서도 진행하는 것을 권장합니다.
- start_url은 상대 경로(예: "/?source=pwa")여도 문제없습니다. 설치 경로를 측정하고 싶다면 쿼리 파라미터를 붙여 두면 분석 도구에서 PWA를 통한 실행을 구분하기 쉬워집니다.
자주 묻는 질문
여담 ― 웹 앱 매니페스트와 PWA의 관계
웹 앱 매니페스트는 W3C가 제정한 JSON 형식의 사양으로, 웹사이트를 네이티브 앱처럼 홈 화면에 추가·설치하는 데 필요한 정보(앱 이름, 아이콘, 실행 시 표시 모드, 테마 컬러 등)를 정리하여 선언합니다. PWA(Progressive Web App)라는 용어 자체는 2015년 Google 엔지니어가 제안한 개념이지만, 그 핵심을 이루는 기술 요소 중 하나가 바로 이 manifest.json과 오프라인 동작을 담당하는 Service Worker 두 가지입니다.
manifest.json이 올바르게 설정되어 있지 않으면 브라우저는 "설치 가능한 앱"으로 인식하지 않아 홈 화면 추가를 유도하는 프롬프트(Chrome의 "설치" 배너 등)가 표시되지 않습니다. 특히 icons의 해상도 부족이나 display 값의 오타는 JSON 자체는 문법적으로 올바르기 때문에 알아차리기 어렵고, 실제로 설치를 시도할 때까지 발견되지 않는 경우가 많은 문제입니다.
maskable 아이콘(purpose: "maskable")은 비교적 최근의 사양으로, 2019년경부터 Android의 "적응형 아이콘(adaptive icon)"에 대응하기 위해 추가되었습니다. 일반 아이콘은 기기에 따라 원형이나 둥근 사각형 등으로 마스킹 처리되기 때문에, 여백이 없는 아이콘 이미지를 준비하면 로고 일부가 잘려 나갈 수 있습니다. maskable용 아이콘은 세이프존을 고려한 디자인으로 만들어야 하며, 일반 icons 항목과는 별도로 준비하는 것이 일반적입니다.
이 도구는 manifest.json 단독의 정적 검증에 특화되어 있으며, Service Worker 등록 상태나 HTTPS 배포 여부 등 실제 설치 가능 여부를 좌우하는 다른 조건까지는 검증하지 않습니다. 실제 운영 환경에서의 최종 확인에는 브라우저의 개발자 도구(Chrome DevTools의 Application 패널 등)도 함께 활용하는 것을 권장합니다.