스마트폰 바탕화면에 앱처럼 아이콘을 추가하고 전체화면으로 실행되는 PWA(Progressive Web App) 구현
모바일 웹 사이트를 단독 앱처럼 바탕화면에 추가하고 전체화면 또는 독립 창으로 실행하도록 만드는 PWA 구현 방식을 다룹니다. 서비스 워커와 웹 앱 매니페스트를 설정하여 스마트폰 환경에서 설치 가능한 형태로 구동하는 원리와 실제 적용 방법을 설명합니다.
PWA 실행 원리와 디스플레이 모드
PWA는 웹 기술로 작성된 애플리케이션을 스마트폰이나 데스크톱 환경에 설치하여 네이티브 앱처럼 실행할 수 있게 돕는 기술입니다. 브라우저 엔진을 기반으로 동작하지만, 홈 화면에 아이콘을 생성하고 상단 주소창을 숨겨 독립적인 앱 경험을 제공합니다.
PWA의 화면 표시 형태는 manifest.json 파일의 display 속성으로 결정됩니다. 기본적으로 네 가지 디스플레이 모드가 존재합니다.
standalone: 상단 상태 표시줄은 남겨 두고 브라우저 UI(주소창, 탐색 버튼)를 제거하여 네이티브 앱과 가장 유사하게 실행됩니다.fullscreen: 기기의 전체 화면을 사용하여 상단 상태 표시줄까지 모두 숨깁니다.minimal-ui: 최소한의 탐색 UI만 남겨 둔 형태로 실행됩니다.browser: 일반적인 웹 브라우저 탭 형태로 실행됩니다.
PWA 구현을 위한 필수 코드
PWA가 모바일 기기에서 정상 설치되고 독립 모드로 실행되려면 웹 앱 매니페스트 파일과 서비스 워커 등록이 필수입니다. 보안을 위해 서비스는 허락받은 서버 환경 및 유효한 SSL 인증서가 적용된 HTTPS 환경(기본 443 포트)에서 작동해야 합니다.
아래는 앱 아이콘 및 실행 모드를 정의하는 manifest.json 예제입니다.
{
"short_name": "내앱",
"name": "내 PWA 애플리케이션",
"icons": [
{
"src": "/images/icon-192.png",
"type": "image/png",
"sizes": "192x192"
},
{
"src": "/images/icon-512.png",
"type": "image/png",
"sizes": "512x512"
}
],
"start_url": "/",
"background_color": "#ffffff",
"theme_color": "#000000",
"display": "standalone"
}다음으로 메인 HTML 파일에서 매니페스트를 연결하고 서비스 워커를 등록합니다.
<!DOCTYPE html>
<html lang="ko">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<!-- 웹 앱 매니페스트 연결 -->
<link rel="manifest" href="/manifest.json">
<title>PWA 앱</title>
</head>
<body>
<h1>PWA 앱에 오신 것을 환영합니다</h1>
<script>
// 브라우저의 서비스 워커 지원 여부 확인
if ('serviceWorker' in navigator) {
window.addEventListener('load', () => {
// 서비스 워커 스크립트 등록
navigator.serviceWorker.register('/sw.js')
.then((registration) => {
console.log('서비스 워커 등록 성공:', registration.scope);
})
.catch((error) => {
console.log('서비스 워커 등록 실패:', error);
});
});
}
</script>
</body>
</html>기본 동작을 담당하는 서비스 워커 스크립트(sw.js) 파일의 예시입니다.
// 서비스 워커 설치 이벤트 처리
self.addEventListener('install', (event) => {
console.log('서비스 워커가 설치되었습니다.');
});
// 네트워크 요청 수신 이벤트 처리
self.addEventListener('fetch', (event) => {
// 필요 시 오프라인 캐싱 로직을 여기에 구현합니다.
event.respondWith(fetch(event.request));
});필수 배포 조건과 설정 시 주의사항
PWA 패키징 및 독립 앱 구동을 완료하려면 아래 조건을 모두 만족해야 합니다.
- HTTPS 적용: 유효한 SSL/TLS 인증서가 필요하며, 표준 443 포트를 통해 서비스되어야 모바일 브라우저에서 설치 가능한 PWA로 인식합니다.
- 서비스 워커 정상 작동: 유효한 서비스 워커가 등록되어 있어야 Web-APK 형태로 변환되어 모바일 기기에 설치됩니다.
- 매니페스트 파일 완성도: 아이콘 규격,
start_url,display속성이 올바르게 지정되어야 합니다.
자주 겪는 문제
- 증상: 바탕화면에 추가했으나 브라우저 창으로만 열리고 독립 앱(standalone)으로 실행되지 않음.
원인: 서비스 워커가 등록되지 않았거나, HTTPS 443 포트 환경이 아닌 비보안 HTTP 주소로 접속함.
해결: 유효한 SSL/TLS 인증서를 설치하여 HTTPS 포트로 서비스를 호스팅하고 브라우저 개발자 도구의 Application 탭에서 서비스 워커 등록 상태를 확인합니다.
- 증상:
manifest.json에display: fullscreen을 설정했으나 모바일이나 데스크톱 환경에서 스탠드얼론 형태로 표출됨.
원인: 일부 운영체제 및 브라우저 플랫폼은 보안이나 UI 정책상fullscreen설정을 지원하지 않고standalone으로 대체 동작함.
해결: 앱의 주 용도에 맞춰standalone을 기본값으로 사용하거나 플랫폼별 동작 표준을 공식 문서에서 확인합니다.
- 증상: 도메인 연동 및 웹-앱 연동 확인 시 연동 오류 발생.
원인:assetlinks.json파일 설정 시 도메인 주소의 호스트 이름이 실제 서빙 주소(www포함 여부 등)와 일치하지 않음.
해결: 도메인 호스트명을 정확히 확인하여www.mywebsite.com과mywebsite.com구분을 명확히 설정하고 도메인 검증 도구로 체크합니다.
정리
- PWA는
manifest.json과 서비스 워커를 활용하여 웹 사이트를 스마트폰 바탕화면의 독립 실행형 앱으로 전환합니다. - 앱처럼 실행하기 위해서는 HTTPS 보안 통신 적용과 서비스 워커의 정상 등록이 필수 요구사항입니다.
- 운영체제와 브라우저 환경에 따라 디스플레이 표현 방식에 차이가 있으므로
standalone모드를 기본으로 구동을 테스트하는 것을 권장합니다.
참고 자료
- PWA running fullscreen in Chrome Android does not honor Display-mode: standalone — Stack Exchange stackoverflow · CC BY-SA
- Android - PWA does not open in standalone mode with service worker — Stack Exchange stackoverflow · CC BY-SA
- Progressive web app — Wikipedia · CC BY-SA
- tecdrop/pwa-display-test — GitHub · MIT
공개한 자료는 무료이며, 사용에 따른 결과는 보증하지 않습니다. 상업적 이용이나 재배포 전에는 한 번 문의해 주시면 감사하겠습니다.
댓글 · 문의 0
댓글은 로그인 후 남기실 수 있습니다. 가입은 무료입니다.
로그인 · 회원가입아직 댓글이 없습니다. 첫 질문을 남겨 주세요.