웹 앱 매니페스트 manifest.json 를 작성해보자.

 

 

프로젝트에 PWA(Progressive Web App)을 도입하기 위해서는 manifest.json 파일을 필수적으로 작성해야 한다고 한다. 그래서 처음 접하게 된 manifest.... manifest는 무슨 파일일까?

 

manifest는 처음이라...

컴퓨팅 분야에서 manifest 파일은 한 그룹의 *메타정보를 담고있는 파일을 말한다. 이름, 버전번호, 라이센스 등의 정보를 담을 수 있다.
*메타정보: 다른 데이터를 설명해주는 역할을 하는 구조화된 데이터

위키의 설명에 따르면, 이 용어는 'ship manifest'라는 세관 용어에서 유래했다고 한다. 'ship manifest'는 수하물 목록, 승객 목록 등을 정리한 문서이다.

영단어 'manifest'는 명확한 또는 명백하게 만든다는 뜻을 갖고 있기도 하다.

1907년 기록한 ship manifest

 

오늘 작성법을 알아볼 manifest 파일은 웹 manifest 파일으로, json 형식으로 작성한다.
W3C에서 관리하는 표준은 여기서 볼 수 있다.

작성한 manifest.json 파일은 웹 서버의 루트디렉토리에 위치시키면 된다.

 

 

반드시 작성해야 하는 것

manifest_version

manifest_version 은 앱에서 사용하는 manifest.json의 버전을 나타낸다. 현재 기준으로 이 값을 항상 2로 설정 해야한다.

"manifest_version": 2

version

version 은 '.'으로 구분된 숫자나 아스키문자로 표현한다. 

"version": "0.1"

자바스크립트 코드상에서 버전을 확인하고 싶다면 아래의 코드를 사용할 수 있다.

console.log(browser.runtime.getManifest().version);
// "0.1"

name

name은 사용자에게 보여지는 애플리케이션의 이름을 지정하는 문자열이다. 

"name": "Awesome application"

 

PWA라면, 반드시 작성해야 하는 것

display

display는 개발자가 선호하는 디스플레이 모드를 지정해두는 문자열이다.

'fullscreen', 'standalone' 'minimal-ui' 'browser' 의 값을 가질 수 있다. 만약 값을 지정하지 않으면 기본 값은 'browser'인데, PWA에서는 이 값을 'fullscreen', 'standalone', 'minimal-ui' 중 하나의 값으로 설정해야해서, 반드시 값을 설정해야 한다.

'fullscreen'은 디스플레이 면적이 모두 해당 애플리케이션을 표시하는데 사용되고, 크롬의 UI는 전혀 보이지 않는다.
'standalone'은 별도의 윈도우, 별도의 런처 아이콘 등을 가지고 독자적인 애플리케이션처럼 구성되는 것이다. 이 모드에서는 크롬의 내비게이션 같은 컨트롤 UI는 보여주지 않지만, 상태표시줄 같은 UI는 보여질 수도 있다.
'minimal-ui'는 'standalone'과 비슷하지만, 최소한의 내비게이션 UI를 갖는다. (어떤 모양의 UI인지는 브라우저마다 다르다.)
'browser'는 기존의 브라우저 탭이나, 새 창을 띄워서 그 플랫폼 위에서 앱을 표시한다.

"display": "standalone"

icons

icons는 각각의 상황에서 사용할 수 있는 아이콘의 배열을 담는다. PWA에서는 192px, 512px 짜리 아이콘을 반드시 포함해야 한다.

"icons": [
  {
    "src": "icon/lowres.webp",
    "sizes": "48x48",
    "type": "image/webp"
  },
  {
    "src": "icon/lowres",
    "sizes": "48x48"
  },
  {
    "src": "icon/hd_hi.ico",
    "sizes": "72x72 96x96 128x128 256x256"
  },
  {
    "src": "icon/hd_hi.svg",
    "sizes": "72x72"
  }
]

start_url

start_url은 사용자가 디바이스에서 아이콘을 눌러 애플리케이션을 시작했을 때 어떤 URL로 연결해서 홈스크린으로 보여줄지 지정하는 문자열이다.

"start_url": "https://example.com"

prefer_related_application

prefer_related_application은 related_applications라는 다른 프로퍼티에 지정된 애플리케이션들을 웹 애플리케이션보다 우선으로 할지 여부를 나타내는 boolean 값이다. 만약 true로 설정한다면, 사용자 에이전트는 웹 앱 대신에 related_applications 중에 하나를 설치할 것을 권유한다. 생략되어있으면 기본 값은 false이다. PWA에서는 이 값이 false로 되어있거나 아예 설정하지 말아야 한다.

"prefer_related_applications": true

 

선택적으로 작성할 수 있는 것

short_name

short_name에 name 값을 좀 더 간단하게 설정해둘 수 있다. 설정해두면, name이 너무 길 경우, short_name의 값이 사용된다. short_name은 12자를 넘지 않도록 하는 것을 추천한다. 만약 short_name을 지정하지 않으면 그냥 name을 사용하고, 길다면 name의 끝이 조금 잘릴 수 있다.

"short_name": "My Extension"

author

author는 작성자를 브라우저 UI상에 표시하기 위해 설정한다. 만약 developer의 name이 설정되어있다면, 그 값이 이 author의 값을 덮어쓰게 된다. 여러명의 author를 표시하는 방법은 없다.

"author": "Walt Whitman"

developer

developer는 개발자의 이름과 홈페이지 URL을 브라우저 UI에 표시하기 위해 설정한다. name과 url 프로퍼티 중 원하는 것만 추가할 수있다. name 프로퍼티를 넣으면 author 가 덮어써지고, url 프로퍼티를 넣으면 homepage_url 이 덮어써진다. author와 마찬가지로 단 하나의 이름과 url을 지원한다.

"developer": {
  "name": "Walt Whitman",
  "url": "https://en.wikipedia.org/wiki/Walt_Whitman"
}

description

description은 앱에 대한 간단한 설명을 브라우저 UI상에 표시하기 위해 설정한다.

"description": "Replaces pictures with pictures of cats."

 

 

참고자료

MDN - manifest

web.dev - Install criteria

web.dev - Add a web app manifest