# Progressive Web App (PWA) Guide (한국어)

🌐 **Languages:** 🇺🇸 [English](../../../../guides/PWA_GUIDE.md) · 🇪🇹 [am](../../../am/docs/guides/PWA_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/guides/PWA_GUIDE.md) · 🇦🇿 [az](../../../az/docs/guides/PWA_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/guides/PWA_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/guides/PWA_GUIDE.md) · 🇧🇦 [bs](../../../bs/docs/guides/PWA_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/guides/PWA_GUIDE.md) · 🇩🇰 [da](../../../da/docs/guides/PWA_GUIDE.md) · 🇩🇪 [de](../../../de/docs/guides/PWA_GUIDE.md) · 🇬🇷 [el](../../../el/docs/guides/PWA_GUIDE.md) · 🇪🇸 [es](../../../es/docs/guides/PWA_GUIDE.md) · 🇪🇪 [et](../../../et/docs/guides/PWA_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/guides/PWA_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/guides/PWA_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/guides/PWA_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/guides/PWA_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/guides/PWA_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/guides/PWA_GUIDE.md) · 🇮🇱 [he](../../../he/docs/guides/PWA_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/guides/PWA_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/guides/PWA_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/guides/PWA_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/guides/PWA_GUIDE.md) · 🇮🇩 [id](../../../id/docs/guides/PWA_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/guides/PWA_GUIDE.md) · 🇮🇹 [it](../../../it/docs/guides/PWA_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/guides/PWA_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/guides/PWA_GUIDE.md) · 🇰🇭 [km](../../../km/docs/guides/PWA_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/guides/PWA_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/guides/PWA_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/guides/PWA_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/guides/PWA_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/guides/PWA_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/guides/PWA_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/guides/PWA_GUIDE.md) · 🇲🇲 [my](../../../my/docs/guides/PWA_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/guides/PWA_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/guides/PWA_GUIDE.md) · 🇳🇴 [no](../../../no/docs/guides/PWA_GUIDE.md) · 🇮🇳 [or](../../../or/docs/guides/PWA_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/guides/PWA_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/guides/PWA_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/guides/PWA_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/guides/PWA_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/PWA_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/guides/PWA_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/guides/PWA_GUIDE.md) · 🇱🇰 [si](../../../si/docs/guides/PWA_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/guides/PWA_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/guides/PWA_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/guides/PWA_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/guides/PWA_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/guides/PWA_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/guides/PWA_GUIDE.md) · 🇮🇳 [te](../../../te/docs/guides/PWA_GUIDE.md) · 🇹🇭 [th](../../../th/docs/guides/PWA_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/guides/PWA_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/PWA_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/guides/PWA_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/guides/PWA_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/guides/PWA_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/guides/PWA_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/PWA_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/PWA_GUIDE.md)

---

OmniRoute는 완전히 설치 가능한 프로그레시브 웹 앱으로 제공됩니다. Android(Chrome) 또는 iOS(Safari) 등 모바일 브라우저에서 대시보드에 접속하면 앱 스토어 없이도 "홈 화면에 추가"하여 네이티브 앱과 같은 환경을 이용할 수 있습니다.

## PWA란 무엇인가요?

프로그레시브 웹 앱은 OmniRoute 웹 대시보드를 네이티브 모바일 앱처럼 보이고 작동하도록 만들어 줍니다. 설치하면 다음과 같은 기능을 제공합니다.

- 자체 아이콘을 사용하여 홈 화면에서 실행
- 브라우저 주소 표시줄이나 탭 UI 없이 전체 화면으로 실행
- 전용 연결 상태 페이지를 통해 오프라인에서도 작동
- 더 빠른 로딩을 위해 정적 자산 캐싱
- 세로 및 가로 화면 방향 모두 지원

## 설치

### Android (Chrome)

1. Chrome에서 OmniRoute 대시보드를 엽니다: `http://YOUR_IP:20128`
2. Chrome에 **"OmniRoute를 홈 화면에 추가"** 배너가 자동으로 표시됩니다. 또는 다음 단계를 따릅니다.
   - **⋮** 메뉴(점 3개) → **"홈 화면에 추가"** 또는 **"앱 설치"**를 탭합니다.
3. 메시지를 확인합니다.
4. OmniRoute가 홈 화면에 독립 실행형 앱으로 표시됩니다.

### iOS (Safari)

1. Safari에서 OmniRoute 대시보드를 엽니다: `http://YOUR_IP:20128`
2. **공유** 버튼(화살표가 있는 상자)을 탭합니다.
3. 아래로 스크롤하여 **"홈 화면에 추가"**를 탭합니다.
4. 이름을 지정하고(기본값: "OmniRoute") **추가**를 탭합니다.
5. OmniRoute가 앱 아이콘과 함께 홈 화면에 표시됩니다.

### 데스크톱 (Chrome / Edge)

1. OmniRoute 대시보드를 엽니다.
2. 주소 표시줄에서 **설치 아이콘**을 클릭하거나 ⋮ → "OmniRoute 설치..."를 선택합니다.
3. 메시지를 확인합니다.
4. OmniRoute가 탭이나 주소 표시줄이 없는 독립 실행형 창으로 열립니다.

## 기능

### 전체 화면 환경

매니페스트는 `display: "fullscreen"`으로 구성되어 있으므로 설치된 앱이 브라우저 UI나 상태 표시줄 겹침 없이 전체 화면을 사용합니다. 이를 통해 대시보드가 진정한 네이티브 앱처럼 느껴집니다.

### 오프라인 지원

OmniRoute에는 지능형 캐싱을 제공하는 서비스 워커(`sw.js`)가 포함되어 있습니다.

| 자산 유형                                               | 전략                           | 동작                                                                                                    |
| ------------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------- |
| **앱 셸**                                               | 캐시 우선                      | 설치 시 `/`, `/offline`, 매니페스트 및 아이콘을 미리 캐싱                                               |
| **정적 자산** (CSS, JS, 이미지, 글꼴)                   | 네트워크 우선 및 캐시 폴백     | 네트워크에서 최신 항목을 가져오며, 오프라인이면 캐시로 폴백                                             |
| **Next.js 번들** (`/_next/`)                            | 네트워크 우선 및 캐시 업데이트 | 네트워크에서 가져와 캐시를 업데이트하며, 오프라인이면 캐시된 버전을 제공                                |
| **탐색 요청**                                           | 우회(절대 가로채지 않음)       | 브라우저가 HTTP/3→HTTP/2 폴백을 처리하며, 응답하지 않는 QUIC 소켓이 `Response.error()`가 되어서는 안 됨 |
| **API / 대시보드 경로** (`/api/`, `/a2a`, `/dashboard`) | 우회(절대 캐싱하지 않음)       | 항상 서버로 직접 전달되며 서비스 워커가 절대 가로채지 않음                                              |

### 오프라인 페이지

네트워크를 사용할 수 없는 상태에서 사용자가 새 페이지로 이동하면 서비스 워커가 전용 `/offline` 페이지를 제공합니다. 이 페이지는 다음 기능을 제공합니다.

- 명확한 **"연결 문제"** 메시지 표시
- 실시간으로 업데이트되는 **온라인/오프라인 상태 표시기** 제공
- 연결이 복구되었을 때 다시 로드할 수 있는 **"연결 재시도"** 버튼 제공
- 진단을 위한 **상태 페이지** 링크 제공

### 앱 아이콘

OmniRoute는 각 플랫폼에 최적화된 아이콘을 제공합니다.

| 파일                   | 크기          | 사용 위치                      |
| ---------------------- | ------------- | ------------------------------ |
| `icon-512.png`         | 512×512       | Android 설치 메시지, 시작 화면 |
| `apple-touch-icon.png` | 180×180       | iOS 홈 화면 아이콘             |
| `icon-192.svg`         | 192×192(벡터) | Android 적응형 아이콘          |
| `apple-touch-icon.svg` | 180×180(벡터) | Apple 폴백                     |
| `favicon.svg`          | 벡터          | 브라우저 탭                    |
| `favicon.ico`          | 다중 크기     | 레거시 브라우저                |

### 자동 등록

서비스 워커는 루트 레이아웃의 `<PwaRegister />` 컴포넌트를 통해 자동으로 등록됩니다. 사용자가 별도로 조치할 필요가 없으며, 브라우저가 유효한 매니페스트와 서비스 워커를 감지하는 즉시 앱을 설치할 수 있습니다.

## 기술 아키텍처

### 웹 앱 매니페스트 (`manifest.webmanifest`)

Next.js가 `src/app/manifest.ts`를 통해 생성합니다.

```json
{
  "name": "OmniRoute",
  "short_name": "OmniRoute",
  "description": "OmniRoute is an AI gateway for multi-provider LLMs. One endpoint for all your AI providers.",
  "start_url": "/",
  "scope": "/",
  "display": "fullscreen",
  "orientation": "any",
  "background_color": "#0b0f1a",
  "theme_color": "#0b0f1a",
  "icons": [
    {
      "src": "/icon-512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "any maskable"
    },
    { "src": "/apple-touch-icon.png", "sizes": "180x180", "type": "image/png" }
  ]
}
```

### 서비스 워커 (`public/sw.js`)

프레임워크 종속성이 없는 순수 서비스 워커이며, 다음 기능을 제공합니다.

- **설치 단계**: 앱 셸(루트, 오프라인 페이지, 매니페스트, 아이콘)을 미리 캐시합니다
- **활성화 단계**: 이전 캐시 버전을 정리하고 모든 클라이언트를 제어합니다
- **가져오기 단계**: 요청 유형(탐색, 정적 자산, API)에 따라 지능적으로 라우팅합니다
- **캐시 버전 관리**: `omniroute-pwa-v3` — 업데이트 시 새 캐시를 강제로 사용하려면 이 값을 올리세요

### 레이아웃 메타데이터 (`src/app/layout.tsx`)

루트 레이아웃은 PWA 요구 사항을 준수하는 데 필요한 모든 메타 태그를 제공합니다.

- `/manifest.webmanifest`를 가리키는 `manifest` 링크
- iOS 독립 실행형 모드를 위한 `apple-web-app-capable: true`
- `apple-web-app-status-bar-style: black-translucent`
- Android Chrome을 위한 `mobile-web-app-capable: yes`
- `theme-color: #0b0f1a`
- 화면 가장자리까지 렌더링하기 위한 `viewport-fit: cover`

### 컴포넌트: `PwaRegister`

`src/shared/components/PwaRegister.tsx`에 있는 이 클라이언트 컴포넌트는 다음과 같이 동작합니다.

1. 마운트 시 실행됩니다(클라이언트 측에서만)
2. 브라우저의 `serviceWorker` 지원 여부를 확인합니다
3. `/sw.js`를 조용히 등록합니다(앱 실행을 방해하지 않도록 오류는 무시됩니다)
4. 아무것도 렌더링하지 않습니다(`return null`) — 부수 효과만 수행하는 컴포넌트입니다

## Termux(Android)에서 사용

Termux를 통해 Android에서 OmniRoute를 실행하면 PWA가 원활하게 작동합니다.

1. Termux에서 OmniRoute를 시작합니다: `npx omniroute`
2. 같은 휴대전화에서 Chrome을 엽니다: `http://localhost:20128`
3. "홈 화면에 추가"를 통해 PWA를 설치합니다
4. PWA가 로컬 Termux 서버에 연결되며, 모든 것이 기기 내에서 실행됩니다

이 조합을 사용하면 Android 휴대전화가 **서버**(Termux)이자 **클라이언트**(PWA)가 되어 완전한 독립형 AI 게이트웨이로 작동합니다.

## 다른 기기에서 사용

OmniRoute 서버에 브라우저로 접근할 수 있는 모든 기기에 PWA를 설치할 수 있습니다.

- **다른 휴대전화/태블릿**: `http://PHONE_IP:20128`로 이동하여 PWA를 설치합니다
- **노트북**: Chrome/Edge에서 열고 데스크톱 PWA로 설치합니다
- **브라우저가 있는 스마트 TV**: 대시보드를 전체 화면으로 이용합니다

## 사용자 지정

### 인스턴스 이름

PWA 제목에는 `Dashboard → Settings`의 **Instance Name** 설정이 반영됩니다. 인스턴스 이름을 "My AI Gateway"로 변경하면 설치된 PWA에 해당 이름이 표시됩니다.

### 사용자 지정 파비콘

`Dashboard → Settings`에서 사용자 지정 파비콘을 업로드하면 데스크톱의 PWA 아이콘에 해당 사용자 지정 아이콘이 반영됩니다. 모바일 홈 화면 아이콘에는 미리 빌드된 `icon-512.png` 및 `apple-touch-icon.png` 파일이 사용됩니다.

## 제한 사항

- **푸시 알림 미지원** — 서비스 워커는 Push API를 구현하지 않습니다. 대신 Electron 앱에서 알림을 처리합니다.
- **백그라운드 동기화 미지원** — 오프라인 작업은 나중에 재실행할 수 있도록 대기열에 추가되지 않습니다. PWA는 주로 대시보드 뷰어로 사용됩니다.
- **iOS 제한 사항** — iOS의 Safari는 모든 PWA 기능을 지원하지 않습니다(예: 설치 프롬프트를 수동으로 실행해야 하며 백그라운드 서비스 워커 기능이 제한됩니다).
- **캐시 크기** — 서비스 워커는 정적 자산만 캐시합니다. `/api/` 경로의 대용량 응답 페이로드는 캐시되지 않습니다.
- **모바일의 사용자 지정 아이콘** — 설정에서 파비콘을 변경해도 모바일의 홈 화면 아이콘은 업데이트되지 않습니다(이를 위해서는 PWA 아이콘을 다시 생성해야 합니다).

## 파일 참조

| 파일                                    | 용도                                                                 |
| --------------------------------------- | -------------------------------------------------------------------- |
| `src/app/manifest.ts`                   | Next.js 매니페스트 경로(`manifest.webmanifest` 생성)                 |
| `public/sw.js`                          | 캐싱 로직이 포함된 서비스 워커                                       |
| `src/shared/components/PwaRegister.tsx` | 서비스 워커를 등록하는 클라이언트 컴포넌트                           |
| `src/app/offline/page.tsx`              | 실시간 상태 표시기가 포함된 오프라인 대체 페이지                     |
| `src/app/layout.tsx`                    | PWA 메타데이터가 포함된 루트 레이아웃(apple-web-app, theme-color 등) |
| `public/icon-512.png`                   | 512×512 PNG 아이콘(Android, 스플래시 화면)                           |
| `public/apple-touch-icon.png`           | 180×180 PNG 아이콘(iOS 홈 화면)                                      |
| `public/icon-192.svg`                   | 192×192 SVG 아이콘(Android 적응형)                                   |
| `public/apple-touch-icon.svg`           | 180×180 SVG 아이콘(Apple 대체용)                                     |