홈 화면에 웹 바로가기를 추가하기(A2HS)

웹 앱을 홈 화면 아이콘으로 띄우는 A2HS(Add to Home Screen)를 최소 설정으로 적용하는 방법을 정리한 글이다. HTTPS·웹 앱 매니페스트·서비스 워커 세 조건 중 뒤 둘을 실제 코드로 다루고, 커스텀 설치 버튼을 만드는 `beforeinstallprompt` 처리와 iOS 사파리의 제약까지 짚는다.

핵심 포인트

A2HS 적용 조건은 HTTPS 서비스, 웹 앱 매니페스트 제공, 서비스 워커 등록 세 가지다.
매니페스트의 필수 항목은 `name`, `icons`, `display`, `start_url` 이고 나머지는 부가 항목이다.
서비스 워커는 캐싱을 안 해도 된다. `self.addEventListener("fetch", e => {})` 만 등록해도 A2HS 는 동작한다.
자체 설치 UI 를 만들려면 `beforeinstallprompt` 이벤트 객체를 보관했다가 버튼 클릭 시 `prompt()` 를 호출한다.
iOS 는 사파리에서만 A2HS 를 지원하고 `beforeinstallprompt` 가 없어 커스텀 UI 를 쓸 수 없다. 공유 버튼 → 홈 화면에 추가 순서로 사용자가 직접 해야 한다.

상세 정리

동기: 사용자가 웹 사이트에 오려면 브라우저를 켜고 주소를 입력해야 한다. 홈 화면에서 한 번의 탭으로 열리면 재방문이 늘 수 있다는 것이 출발점이다.
적용 범위: 안드로이드·iOS 네이티브 앱과 웹 앱이 모두 필요한데 개발 여력이 없을 때의 대안으로 제시한다.
매니페스트 파일은 static 루트에 `manifest.webmanifest` 로 만든다. `.webmanifest` 가 W3C 표준 확장자이고 일반 브라우저는 `.json` 도 받는다.
`icons` 는 기기 해상도에 따라 적절한 크기가 선택되므로 192×192 와 512×512 두 개를 두는 편이 좋고, 하나만 넣는다면 512×512 를 쓴다.
`display` 는 fullscreen(상태 바·주소창 없음), standalone(주소창 없음), minimal-ui(안드로이드·데스크톱 한정 최소 UI), browser 중에서 고른다.
`orientation` 은 any·landscape·portrait·natural·primary·secondary 중 선택하고, `scope` 를 벗어난 URL 은 웹 앱이 아니라 브라우저에서 열린다.
등록: `<link rel="manifest" href="/manifest.webmanifest" />` 를 넣되, 사파리는 매니페스트의 icon 컬렉션을 무시하므로 `apple-touch-icon` 을 별도로 명시해야 한다.
서비스 워커의 본래 쓰임은 네트워크 요청을 가로채 캐시된 데이터를 먼저 주는 것이지만, 이 글은 최소 설정이 목표라 빈 fetch 리스너만 등록한다.
등록 코드는 `if ("serviceWorker" in navigator) navigator.serviceWorker.register("/sw.js")` 를 즉시 실행 함수로 감싼 형태다.
커스텀 설치 UI: `beforeinstallprompt` 핸들러에서 이벤트 객체를 state 에 담아 두고, 설치 버튼에서 `deferredPrompt.prompt()` 와 `userChoice` 처리 후 상태를 비우는 훅(`useA2HS`)으로 감쌌다.
iOS 사용자 안내: 사파리 하단 공유 버튼 → "홈 화면에 추가" → 앱 이름 확인 → 추가 순서를 밟으면 브라우저 없이 별도 앱처럼 실행된다.
마무리에서 앱 스토어 검색·인증·설치 시간이 없다는 점을 진입장벽 측면의 이득으로 꼽고, PWA 의 푸시 등 다른 기능으로 확장할 여지를 언급한다.