웹 앱 매니페스트는 웹 콘텐츠를 운영체제에서 앱으로 표시하는 방법을 브라우저에 알리기 위해 만드는 파일입니다. 매니페스트에는 앱 이름, 아이콘, 테마 색상과 같은 기본 정보, 원하는 방향 및 앱 바로가기와 같은 고급 환경설정, 스크린샷과 같은 카탈로그 메타데이터가 포함될 수 있습니다.
각 PWA에는 일반적으로 루트 폴더에서 호스팅되고 PWA를 설치할 수 있는 모든 HTML 페이지에 연결되는 애플리케이션당 하나의 매니페스트가 포함되어야 합니다. 공식 확장자는 .webmanifest이므로 매니페스트의 이름을 app.webmanifest과 같이 지정할 수 있습니다.
PWA에 웹 앱 매니페스트 추가
웹 앱 매니페스트를 만들려면 먼저 문자열 값이 있는 name 필드가 하나 이상 포함된 JSON 객체로 텍스트 파일을 만듭니다.
app.webmanifest:
{
"name": "My First Application"
}
하지만 파일을 만드는 것만으로는 충분하지 않습니다. 브라우저는 이 파일의 존재도 알아야 합니다.
매니페스트에 연결
브라우저가 웹 앱 매니페스트를 인식하도록 하려면 PWA의 모든 HTML 페이지에서 <link> HTML 요소와 rel 속성을 manifest로 설정하여 PWA에 연결해야 합니다. 이는 CSS 스타일시트를 문서에 연결하는 방법과 유사합니다.
index.html:
<html lang="en">
<title>This is my first PWA</title>
<link rel="manifest" href="/app.webmanifest">
매니페스트 디버깅
매니페스트가 올바르게 설정되었는지 확인하려면 모든 Chromium 기반 브라우저에서 Firefox와 DevTools의 Inspector를 사용하세요.
Chromium 브라우저
DevTools에서
- 왼쪽 창의 애플리케이션 아래에서 매니페스트를 선택합니다.
- 브라우저에서 파싱한 매니페스트의 필드를 확인합니다.
Firefox
- Inspector를 엽니다.
- 애플리케이션 탭으로 이동합니다.
- 왼쪽 패널에서 매니페스트 옵션을 선택합니다.
- 브라우저에서 파싱한 매니페스트의 필드를 확인합니다.
PWA 환경 설계
이제 PWA가 매니페스트에 연결되었으므로 나머지 필드를 작성하여 사용자 환경을 정의할 차례입니다.
기본 필드
첫 번째 필드 집합은 PWA에 관한 핵심 정보를 나타냅니다. 설치된 PWA의 아이콘과 창을 빌드하고 시작 방법을 결정하는 데 사용됩니다. 이동했습니다.
name- PWA의 전체 이름입니다. 운영체제의 홈 화면, 런처, 도크, 메뉴에 표시되는 아이콘과 함께 표시됩니다.
short_name- 선택사항으로,
name필드의 전체 값을 표시할 공간이 충분하지 않을 때 사용되는 PWA의 짧은 이름입니다. 잘릴 가능성을 최소화하려면 12자(영문 기준) 미만으로 유지하세요. icons- PWA를 나타내야 하는 이미지를 설명하는
src,type,sizes및 선택적purpose필드가 있는 아이콘 객체의 배열입니다. start_url- 사용자가 설치된 아이콘에서 PWA를 시작할 때 PWA가 로드되어야 하는 URL입니다. 절대 경로를 사용하는 것이 좋습니다. PWA의 홈페이지가 사이트의 루트인 경우 PWA를'/'로 설정하여 앱이 시작될 때 열리도록 할 수 있습니다. 시작 URL을 제공하지 않으면 브라우저에서 PWA가 설치된 URL을 시작으로 사용할 수 있습니다. 홈 화면이 아닌 제품 세부정보와 같은 딥 링크를 제공할 수도 있습니다.
display- OS에서 PWA 창을 그리는 방법을 설명하는
fullscreen,standalone,minimal-ui또는browser중 하나입니다. 다양한 디스플레이 모드에 관한 자세한 내용은 앱 디자인 챕터를 참고하세요. 대부분의 사용 사례에서는standalone를 구현합니다. id- 동일한 출처에서 호스팅될 수 있는 다른 PWA와 비교하여 이 PWA를 고유하게 식별하는 문자열입니다. 이 속성이 설정되지 않은 경우
start_url이 대체 값으로 사용됩니다. 향후start_url를 변경하면 (예: 쿼리 문자열 값 변경) 브라우저에서 PWA가 이미 설치되어 있음을 감지하는 기능이 삭제될 수 있습니다.
아이콘
PWA 아이콘은 설치 시 사용자 기기에서 표시되는 시각적 ID이므로 PWA 아이콘을 하나 이상 정의하는 것이 중요합니다. icons 속성은 아이콘 객체의 모음이므로 사용자에게 최적의 아이콘 환경을 제공하기 위해 다양한 형식으로 여러 아이콘을 정의할 수 있습니다. 각 브라우저는 필요 사항과 설치된 운영 체제에 따라 하나 이상의 아이콘을 선택하고, 필요한 사양에 더 가까운 아이콘을 선택합니다.
아이콘 크기를 하나만 선택해야 하는 경우 512x512픽셀이어야 합니다. 그러나 192x192, 384x384, 1024x1024 픽셀 크기의 이미지 등 더 많은 크기를 제공하는 것이 좋습니다.
"icons": [
{
"src": "icons/512.png",
"type": "image/png",
"sizes": "512x512"
},
{
"src": "icons/1024.png",
"type": "image/png",
"sizes": "1024x1024"
}
]
아이콘을 제공하지 않거나 아이콘이 권장 크기가 아니면 일부 플랫폼에서 설치 기준을 통과하지 못합니다. 다른 플랫폼에서는 아이콘이 자동으로 생성됩니다(예: PWA의 스크린샷 또는 일반 아이콘 사용).
마스크 가능한 아이콘
Android와 같은 일부 운영체제에서는 다양한 크기와 모양에 맞게 아이콘을 조정합니다. 예를 들어 Android 12의 여러 제조업체 또는 설정에서 아이콘 모양을 원에서 정사각형으로, 모서리가 둥근 정사각형으로 변경할 수 있습니다. 이러한 종류의 적응형 아이콘을 지원하려면 purpose 필드를 사용하여 마스크 가능한 아이콘을 제공하면 됩니다.
이렇게 하려면 기본 아이콘이 '안전 영역' 내에 포함된 정사각형 이미지 파일을 제공하세요. '안전 영역'은 아이콘의 중심에 있으며 아이콘 너비의 반경 40%인 원입니다. 아래 이미지를 참고하세요. 마스크 가능한 아이콘을 지원하는 기기는 필요에 따라 아이콘을 마스킹합니다.
다음은 흔히 사용되는 여러 도형에서 렌더링된 마스크 가능한 아이콘의 예입니다.
다음 이미지에서 왼쪽의 아이콘을 마스크 가능한 아이콘으로 사용하면 셰이프 마스크가 적용될 때 기기에서 결과가 저하됩니다.
패딩을 더 추가하여 이 이미지를 사용할 수 있습니다.
마스크 가능한 아이콘은 최소한 512x512여야 합니다. 계정을 만든 후 icons 컬렉션에 추가하여 지원되는 기기의 환경을 개선할 수 있습니다.
"icons": [
{
"src": "/icons/512.png",
"type": "image/png",
"sizes": "512x512"
},
{
"src": "/icons/1024.png",
"type": "image/png",
"sizes": "1024x1024"
},
{
"src": "/icons/512-maskable.png",
"type": "image/png",
"sizes": "512x512",
"purpose": "maskable"
},
]
대부분의 경우 마스크 가능한 아이콘이 제대로 표시되지 않으면 패딩을 추가하여 아이콘을 개선할 수 있습니다. Maskable.app은 마스크 가능한 버전의 아이콘을 테스트하고 만드는 무료 온라인 도구입니다.
권장 입력란
다음으로 포함할 필드 세트는 설치 가능성을 위해 필수는 아니지만 사용자 환경을 개선하는 필드입니다.
theme_color- 애플리케이션의 기본 색상으로, 때로 OS에서 사이트를 표시하는 방식에 영향을 미칩니다 (예: 데스크톱의 창과 제목 표시줄 색상 또는 휴대기기의 상태 표시줄 색상). 이 색상은 HTML
theme-color<meta>요소로 재정의할 수 있습니다. background_color- 스타일시트가 로드되기 전에 애플리케이션의 배경에 표시할 자리표시자 색상입니다. iOS, iPadOS, 대부분의 데스크톱 브라우저의 Safari(현재)는 이 입력란을 무시합니다.
scope- PWA의 탐색 범위를 변경하여 설치된 앱의 창에 표시되는 항목과 표시되지 않는 항목을 정의할 수 있습니다. 예를 들어 범위 밖에 있는 페이지로 연결하면 PWA 창 대신 인앱 브라우저에서 렌더링됩니다. 그러나 서비스 워커의 범위는 변경되지 않습니다.
다음 이미지는 PWA를 설치할 때 데스크톱 기기의 제목 표시줄에 theme_color 필드가 사용되는 방식을 보여줍니다.
theme_color 및 background_color 내에서와 같이 매니페스트에서 색상을 정의할 때 이름이 지정된 CSS 색상(예: salmon 또는 orange), RGB 색상(예: #FF5500) 또는 투명도가 없는 색상 함수(예: rgb() 또는 hsl())를 사용해야 합니다. 자세한 내용은 앱 디자인 챕터를 참고하세요.
사용해 보기
스플래시 화면
일부 기기에서는 PWA가 로드되는 동안 정적 이미지가 렌더링되어 사용자에게 즉각적인 피드백을 제공합니다.
Android는 theme_color, background_color, icon 값을 사용하여 스플래시 화면을 생성합니다.
Android에 PWA를 설치하면 다음 다이어그램과 같이 매니페스트에서 가져온 정보가 포함된 스플래시 화면이 기기에 생성됩니다.
반면에 iOS 및 iPadOS의 Safari에서는 웹 앱 매니페스트를 사용하여 스플래시 화면을 생성하지 않습니다. 대신 아이콘을 처리하는 방식과 유사하게 독점 <link> 요소에서 연결된 이미지를 사용합니다. 자세한 내용은 개선사항 챕터를 참고하세요.
확장 필드
다음 필드 모음에서는 PWA에 관한 추가 정보를 제공합니다. 모두 선택사항입니다.
lang- 매니페스트 값의 기본 언어를 지정하는 언어 태그입니다(예: 영어의 경우
en, 포르투갈어(브라질)의 경우pt-BR, 힌디어의 경우in). dir- 방향을 지원하는 매니페스트 필드를 표시하는 방향입니다 (예:
name,short_name,description). 유효한 값은auto,ltr(왼쪽에서 오른쪽) 및rtl(오른쪽에서 왼쪽)입니다. orientation- 설치 후 원하는 앱 방향입니다. 게임에서 가로 모드 전용 방향을 요청하도록 설정할 수 있습니다. 여러 값이 허용되지만 포함되는 경우 일반적으로 명시적으로
portrait또는landscape입니다.
프로모션 필드
네 번째 필드에서는 설치 흐름, 등록정보, 검색결과 등 PWA에 관한 프로모션 정보를 제공할 수 있습니다.
description- PWA의 기능에 관한 설명
screenshots- PWA를 보여주기 위한
src,type,sizes(icons객체와 유사)가 있는 스크린샷 객체의 배열입니다. 크기 제한은 없습니다. categories- PWA가 속해야 하는 카테고리의 배열(선택사항)은 알려진 카테고리 목록에서 선택적으로 사용할 수 있습니다. 이러한 값은 일반적으로 소문자입니다.
iarc_rating_id- PWA용 International Age Rating Coalition 인증 코드(있는 경우) PWA에 적합한 연령을 결정하는 데 사용됩니다.
이러한 프로모션 필드가 실제로 작동하는 것을 볼 수 있습니다. 예를 들어 Android에서 PWA를 설치할 수 있고 개발자가 최소 description 및 screenshots 필드에 값을 제공하면 설치 대화상자 환경이 간단한 '홈 화면에 추가' 정보 표시줄에서 앱 스토어의 설치 대화상자와 유사한 더 풍부한 설치 대화상자로 변환됩니다.
Android에서는 다음 동영상에서 볼 수 있듯이 프로모션 필드에 값을 제공하면 더 멋진 설치 UI를 얻을 수 있습니다.
다음 프로모션 필드를 참조하세요.
Capabilities 필드
마지막으로 기능 챕터에서 다루는 shortcuts, share_target, display_overrides 필드와 같이 PWA가 지원되는 브라우저에서 사용할 수 있는 다양한 기능과 관련된 여러 필드가 있습니다. related_apps 및 prefer_related_apps (자세한 내용은 감지 챕터 참고)와 같은 필드도 있습니다. 이 필드는 주로 앱 스토어에서 설치된 앱에 PWA를 연결합니다.
브라우저가 프로그레시브 웹 앱에 더 많은 기능을 추가하면서 앞으로 많은 새로운 필드가 나타날 수 있습니다.