웹 앱 매니페스트는 웹 콘텐츠가 운영체제에서 앱으로 표시되기를 원하는 방식을 브라우저에 지시하는 파일입니다. 매니페스트에는 앱 이름, 아이콘, 테마 색상과 같은 기본 정보가 포함될 수 있습니다. 원하는 방향, 앱 바로 가기와 같은 고급 환경설정 스크린샷과 같은 카탈로그 메타데이터가 포함됩니다
각 PWA에는 애플리케이션별로 하나의 매니페스트가 포함되어야 하며, 일반적으로 루트 폴더에 호스팅되고 PWA를 설치할 수 있는 모든 HTML 페이지에 연결됩니다. 공식 확장자는 .webmanifest이므로 매니페스트의 이름을 app.webmanifest과 같이 지정할 수 있습니다.
PWA에 웹 앱 매니페스트 추가
웹 앱 매니페스트를 만들려면 먼저 문자열 값이 있는 name 필드가 하나 이상 포함된 JSON 객체로 텍스트 파일을 만듭니다.
app.webmanifest:
{
"name": "My First Application"
}
그러나 파일을 생성하는 것만으로는 충분하지 않습니다. 브라우저에서도 파일이 존재하는지 알아야 합니다.
매니페스트에 연결
브라우저가 웹 앱 매니페스트를 인식하도록 하려면 모든 PWA HTML 페이지에서 <link> HTML 요소와 manifest로 설정된 rel 속성을 사용하여 웹 앱 매니페스트를 PWA에 연결해야 합니다. 이 방법은 CSS 스타일 시트를 문서에 연결하는 방법과 비슷합니다.
index.html:
<html lang="en">
<title>This is my first PWA</title>
<link rel="manifest" href="/app.webmanifest">
매니페스트 디버깅
매니페스트가 올바르게 설정되었는지 확인하려면 Firefox에서 Inspector를 사용하고 모든 Chromium 기반 브라우저에서 DevTools를 사용하면 됩니다.
Chromium 브라우저
DevTools에서
- 왼쪽 창의 애플리케이션 아래에서 매니페스트를 선택합니다.
- 브라우저에서 파싱한 매니페스트의 필드를 확인합니다.
Firefox
- Inspector를 엽니다.
- Application 탭으로 이동합니다.
- 왼쪽 패널에서 Manifest 옵션을 선택합니다.
- 브라우저에서 파싱한 매니페스트의 필드를 확인합니다.
PWA 환경 설계하기
PWA가 매니페스트에 연결되었으므로 이제 나머지 필드를 작성하여 사용자 환경을 정의할 차례입니다.
기본 필드
첫 번째 입력란 모음은 PWA에 관한 핵심 정보를 나타냅니다. PWA는 설치된 PWA의 아이콘과 창을 빌드하고 시작 방법을 결정하는 데 사용됩니다. 각 필터는 다음과 같습니다.
name- PWA의 전체 이름입니다. 운영체제의 홈 화면, 런처, 도크 또는 메뉴에서 아이콘과 함께 표시됩니다.
short_name- 선택사항. 더 짧은 PWA 이름으로,
name필드의 전체 값을 표시할 공간이 충분하지 않을 때 사용됩니다. 잘리지 않도록 12자(영문 기준) 미만으로 유지하세요. iconssrc,type,sizes, 선택적purpose필드가 있는 아이콘 객체의 배열로, PWA를 나타내야 하는 이미지를 설명합니다.start_url- 사용자가 설치된 아이콘에서 PWA를 시작하면 PWA가 로드되어야 하는 URL입니다. 절대 경로를 사용하는 것이 좋습니다. 따라서 PWA 홈페이지가 사이트의 루트인 경우 '/'로 설정할 수 있습니다. 앱이 시작될 때 열 수 있습니다. 시작 URL을 제공하지 않으면 브라우저에서 PWA가 설치된 URL을 시작 시 사용할 수 있습니다. 홈 화면 대신 제품 세부정보와 같은 딥 링크를 사용할 수 있습니다.
display- OS에서 PWA 창을 그리는 방법을 설명하는
fullscreen,standalone,minimal-ui또는browser중 하나입니다. 다양한 디스플레이 모드에 관한 자세한 내용은 앱 디자인 챕터를 참고하세요. 대부분의 사용 사례에서는standalone를 구현합니다. id- 동일한 출처에서 호스팅될 수 있는 다른 PWA에 대해 이 PWA를 고유하게 식별하는 문자열입니다. 설정하지 않으면
start_url이 대체 값으로 사용됩니다. 향후에start_url를 변경하면 (예: 쿼리 문자열 값 변경 시) PWA가 이미 설치되어 있음을 감지하는 브라우저의 기능이 제거될 수 있습니다. 를 통해 개인정보처리방침을 정의할 수 있습니다.
아이콘
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 내에서와 같이 매니페스트에서 색상을 정의할 때는 salmon 또는 orange와 같은 CSS 이름이 지정된 색상, #FF5500와 같은 RGB 색상 또는 투명도가 없는 색상 함수(예: 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를 얻을 수 있습니다.
실제 사용 중인 프로모션 필드는 다음과 같습니다.
기능 필드
마지막으로, 지원되는 브라우저에서 PWA가 사용할 수 있는 다양한 기능과 관련된 여러 필드가 있습니다(예: 기능 장에서 다루는 shortcuts, share_target, display_overrides 필드). related_apps 및 prefer_related_apps와 같은 필드(자세한 내용은 감지 챕터 참고)를 사용하여 PWA를 설치된 앱(주로 앱 스토어에서 설치)에 연결할 수도 있습니다.
브라우저가 프로그레시브 웹 앱에 더 많은 기능을 추가하는 동안 향후 여러 새로운 필드가 나타날 수 있습니다.