← 포럼 · 소프트웨어
소프트웨어

스마트폰 바탕화면에 앱처럼 아이콘을 추가하고 전체화면으로 실행되는 PWA(Progressive Web App) 구현

2026.11.19조회 2댓글 0

모바일 웹 사이트를 단독 앱처럼 바탕화면에 추가하고 전체화면 또는 독립 창으로 실행하도록 만드는 PWA 구현 방식을 다룹니다. 서비스 워커와 웹 앱 매니페스트를 설정하여 스마트폰 환경에서 설치 가능한 형태로 구동하는 원리와 실제 적용 방법을 설명합니다.

PWA 실행 원리와 디스플레이 모드

PWA는 웹 기술로 작성된 애플리케이션을 스마트폰이나 데스크톱 환경에 설치하여 네이티브 앱처럼 실행할 수 있게 돕는 기술입니다. 브라우저 엔진을 기반으로 동작하지만, 홈 화면에 아이콘을 생성하고 상단 주소창을 숨겨 독립적인 앱 경험을 제공합니다.

PWA의 화면 표시 형태는 manifest.json 파일의 display 속성으로 결정됩니다. 기본적으로 네 가지 디스플레이 모드가 존재합니다.

  • standalone: 상단 상태 표시줄은 남겨 두고 브라우저 UI(주소창, 탐색 버튼)를 제거하여 네이티브 앱과 가장 유사하게 실행됩니다.
  • fullscreen: 기기의 전체 화면을 사용하여 상단 상태 표시줄까지 모두 숨깁니다.
  • minimal-ui: 최소한의 탐색 UI만 남겨 둔 형태로 실행됩니다.
  • browser: 일반적인 웹 브라우저 탭 형태로 실행됩니다.

PWA 구현을 위한 필수 코드

PWA가 모바일 기기에서 정상 설치되고 독립 모드로 실행되려면 웹 앱 매니페스트 파일과 서비스 워커 등록이 필수입니다. 보안을 위해 서비스는 허락받은 서버 환경 및 유효한 SSL 인증서가 적용된 HTTPS 환경(기본 443 포트)에서 작동해야 합니다.

아래는 앱 아이콘 및 실행 모드를 정의하는 manifest.json 예제입니다.

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 파일에서 매니페스트를 연결하고 서비스 워커를 등록합니다.

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) 파일의 예시입니다.

javascript
// 서비스 워커 설치 이벤트 처리
self.addEventListener('install', (event) => {
  console.log('서비스 워커가 설치되었습니다.');
});

// 네트워크 요청 수신 이벤트 처리
self.addEventListener('fetch', (event) => {
  // 필요 시 오프라인 캐싱 로직을 여기에 구현합니다.
  event.respondWith(fetch(event.request));
});

필수 배포 조건과 설정 시 주의사항

PWA 패키징 및 독립 앱 구동을 완료하려면 아래 조건을 모두 만족해야 합니다.

  1. HTTPS 적용: 유효한 SSL/TLS 인증서가 필요하며, 표준 443 포트를 통해 서비스되어야 모바일 브라우저에서 설치 가능한 PWA로 인식합니다.
  2. 서비스 워커 정상 작동: 유효한 서비스 워커가 등록되어 있어야 Web-APK 형태로 변환되어 모바일 기기에 설치됩니다.
  3. 매니페스트 파일 완성도: 아이콘 규격, 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 모드를 기본으로 구동을 테스트하는 것을 권장합니다.

참고 자료

공개한 자료는 무료이며, 사용에 따른 결과는 보증하지 않습니다. 상업적 이용이나 재배포 전에는 한 번 문의해 주시면 감사하겠습니다.

댓글 · 문의 0

아직 댓글이 없습니다. 첫 질문을 남겨 주세요.

찾으시는 내용이 없다면

만들고 싶은 것이나 막힌 부분을 알려주시면 검토해 드립니다.