# Progressive Web App (PWA) Guide (Polski) 🌐 **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) · 🇰🇷 [ko](../../../ko/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) · 🇵🇹 [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) --- title: "Przewodnik po Progressive Web App (PWA)" version: 3.8.40 lastUpdated: 2026-06-28 --- # Przewodnik po Progressive Web App (PWA) OmniRoute jest dostarczany jako w pełni instalowalna Progressive Web App. Gdy otworzysz dashboard w dowolnej przeglądarce mobilnej — Android (Chrome) lub iOS (Safari) — możesz wybrać „Dodaj do ekranu głównego” i uzyskać doświadczenie zbliżone do natywnej aplikacji, bez sklepu z aplikacjami. ## Czym jest PWA? Progressive Web App zamienia webowy dashboard OmniRoute w coś, co wygląda i działa jak natywna aplikacja mobilna. Po zainstalowaniu: - Uruchamia się z ekranu głównego z własną ikoną - Otwiera się na pełnym ekranie — bez paska adresu przeglądarki ani interfejsu kart - Działa offline dzięki dedykowanej stronie łączności - Buforuje zasoby statyczne w celu szybszego ładowania - Obsługuje orientację pionową i poziomą ## Instalacja ### Android (Chrome) 1. Otwórz dashboard OmniRoute w Chrome: `http://YOUR_IP:20128` 2. Chrome automatycznie pokaże baner **"Add OmniRoute to Home screen"**, albo: - Stuknij menu **⋮** (trzy kropki) → **"Add to Home screen"** lub **"Install app"** 3. Potwierdź monity 4. OmniRoute pojawi się na ekranie głównym jako samodzielna aplikacja ### iOS (Safari) 1. Otwórz dashboard OmniRoute w Safari: `http://YOUR_IP:20128` 2. Stuknij przycisk **Share** (kwadrat ze strzałką) 3. Przewiń w dół i stuknij **"Add to Home Screen"** 4. Nadaj nazwę (domyślnie „OmniRoute”) i stuknij **Add** 5. OmniRoute pojawi się na ekranie głównym z ikoną aplikacji ### Desktop (Chrome / Edge) 1. Otwórz dashboard OmniRoute 2. Kliknij **ikona instalacji** na pasku adresu (lub ⋮ → "Install OmniRoute...") 3. Potwierdź monity 4. OmniRoute otworzy się jako samodzielne okno — bez kart i paska adresu ## Funkcje ### Tryb pełnoekranowy Manifest jest skonfigurowany z ustawieniem `display: "fullscreen"`, co oznacza, że zainstalowana aplikacja wykorzystuje cały ekran — bez elementów interfejsu przeglądarki i bez nakładania się na pasek stanu. Dzięki temu panel sprawia wrażenie prawdziwie natywnego. ### Obsługa trybu offline OmniRoute zawiera service workera (`sw.js`), który zapewnia inteligentne buforowanie: | Typ zasobu | Strategia | Działanie | | ------------------------------------------------------ | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | **Powłoka aplikacji** | Najpierw pamięć podręczna | `/`, `/offline`, manifest i ikony są wstępnie buforowane podczas instalacji | | **Zasoby statyczne** (CSS, JS, obrazy, czcionki) | Najpierw sieć, z użyciem pamięci podręcznej w razie niepowodzenia | Pobiera aktualne zasoby z sieci; w trybie offline korzysta z pamięci podręcznej | | **Pakiety Next.js** (`/_next/`) | Najpierw sieć, z aktualizacją pamięci podręcznej | Pobiera zasoby z sieci i aktualizuje pamięć podręczną; w trybie offline udostępnia wersję z pamięci podręcznej | | **Żądania nawigacyjne** | Pomijanie (nigdy nie są przechwytywane) | Przeglądarka zarządza przełączaniem awaryjnym HTTP/3→HTTP/2; nieaktywny socket QUIC nie może skutkować `Response.error()` | | **Trasy API / panelu** (`/api/`, `/a2a`, `/dashboard`) | Pomijanie (nigdy nie są buforowane) | Zawsze trafiają bezpośrednio do serwera — nigdy nie są przechwytywane przez service workera | ### Strona trybu offline Gdy sieć jest niedostępna, a użytkownik przechodzi do nowej strony, service worker wyświetla dedykowaną stronę `/offline`, która: - Wyświetla jasny komunikat **„Problem z połączeniem”** - Pokazuje aktualizowany w czasie rzeczywistym **wskaźnik stanu online/offline** - Udostępnia przycisk **„Ponów połączenie”**, który umożliwia ponowne załadowanie strony po przywróceniu łączności - Zawiera łącze do **strony stanu** umożliwiającej diagnostykę ### Ikony aplikacji OmniRoute udostępnia ikony zoptymalizowane dla poszczególnych platform: | Plik | Rozmiar | Zastosowanie | | ---------------------- | ------------------- | ---------------------------------------------------- | | `icon-512.png` | 512×512 | Monit instalacji w systemie Android, ekran powitalny | | `apple-touch-icon.png` | 180×180 | Ikona na ekranie głównym systemu iOS | | `icon-192.svg` | 192×192 (wektorowa) | Adaptacyjna ikona systemu Android | | `apple-touch-icon.svg` | 180×180 (wektorowa) | Ikona zapasowa dla urządzeń Apple | | `favicon.svg` | Wektorowy | Karty przeglądarki | | `favicon.ico` | Wiele rozmiarów | Starsze przeglądarki | ### Automatyczna rejestracja Service worker jest rejestrowany automatycznie za pośrednictwem komponentu `` w głównym układzie. Użytkownik nie musi podejmować żadnych działań — aplikację można zainstalować, gdy tylko przeglądarka wykryje prawidłowy manifest i service workera. ## Architektura techniczna ### Manifest aplikacji internetowej (`manifest.webmanifest`) Generowany przez Next.js za pośrednictwem `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" } ] } ``` ### Service Worker (`public/sw.js`) Standardowy service worker (bez zależności od frameworków), obejmujący: - **Faza instalacji**: Wstępnie zapisuje w pamięci podręcznej szkielet aplikacji (stronę główną, stronę trybu offline, manifest i ikony) - **Faza aktywacji**: Usuwa stare wersje pamięci podręcznej i przejmuje kontrolę nad wszystkimi klientami - **Faza pobierania**: Inteligentnie kieruje żądania na podstawie ich typu (nawigacja, zasób statyczny, API) - **Wersjonowanie pamięci podręcznej**: `omniroute-pwa-v3` — zwiększ tę wartość, aby wymusić utworzenie nowej pamięci podręcznej po aktualizacji ### Metadane układu (`src/app/layout.tsx`) Układ główny zawiera wszystkie metatagi wymagane do zapewnienia zgodności z PWA: - Łącze `manifest` do `/manifest.webmanifest` - `apple-web-app-capable: true` dla trybu autonomicznego w systemie iOS - `apple-web-app-status-bar-style: black-translucent` - `mobile-web-app-capable: yes` dla przeglądarki Chrome na Androidzie - `theme-color: #0b0f1a` - `viewport-fit: cover` dla renderowania od krawędzi do krawędzi ### Komponent: `PwaRegister` Znajdujący się w `src/shared/components/PwaRegister.tsx` komponent kliencki: 1. Uruchamia się po zamontowaniu (wyłącznie po stronie klienta) 2. Sprawdza obsługę `serviceWorker` w przeglądarce 3. Rejestruje `/sw.js` bez komunikatów (błędy są ignorowane, aby uniknąć blokowania aplikacji) 4. Niczego nie renderuje (`return null`) — jest to komponent służący wyłącznie do wykonywania efektów ubocznych ## Użycie z Termux (Android) Przy uruchamianiu OmniRoute na Androidzie przez Termux PWA działa bezproblemowo: 1. Uruchom OmniRoute w Termux: `npx omniroute` 2. Otwórz Chrome na tym samym telefonie: `http://localhost:20128` 3. Zainstaluj PWA przez "Add to Home Screen" 4. PWA łączy się z lokalnym serwerem Termux — wszystko działa na urządzeniu Ta kombinacja oznacza, że telefon z Androidem jest jednocześnie **serwerem** (Termux) i **klientem** (PWA) — kompletna, samodzielna brama AI. ## Użycie z innych urządzeń Zainstaluj PWA na dowolnym urządzeniu, które ma dostęp przeglądarkowy do serwera OmniRoute: - **Inny telefon/tablet**: przejdź do `http://PHONE_IP:20128` i zainstaluj PWA - **Laptop**: otwórz Chrome/Edge i zainstaluj jako desktopowe PWA - **Smart TV z przeglądarką**: otwórz dashboard na pełnym ekranie ## Dostosowywanie ### Nazwa instancji Tytuł PWA respektuje ustawienie **Instance Name** z `Dashboard → Settings`. Jeśli zmienisz nazwę instancji na „My AI Gateway”, zainstalowane PWA pokaże tę nazwę. ### Własny favicon Jeśli wgrasz własny favicon przez `Dashboard → Settings`, ikona PWA na desktopie odzwierciedli tę ikonę. Ikony ekranu głównego na mobile używają wbudowanych plików `icon-512.png` i `apple-touch-icon.png`. ## Ograniczenia - **Brak push notifications** — service worker nie implementuje Push API. Powiadomienia obsługuje aplikacja Electron. - **Brak background sync** — akcje offline nie są kolejkowane do ponownego odtworzenia. PWA jest przede wszystkim przeglądarką dashboardu. - **Ograniczenia iOS** — Safari na iOS nie obsługuje wszystkich funkcji PWA (np. monity instalacji są ręczne, a background service workers są ograniczone). - **Rozmiar cache** — service worker buforuje wyłącznie zasoby statyczne. Duże payloady odpowiedzi z tras `/api/` nigdy nie trafiają do cache. - **Własne ikony na mobile** — zmiana faviconu w ustawieniach nie aktualizuje ikony ekranu głównego na mobile (wymaga to regeneracji ikon PWA). ## Referencja plików | Plik | Przeznaczenie | | --------------------------------------- | -------------------------------------------------------------- | | `src/app/manifest.ts` | Trasa manifestu Next.js (generuje `manifest.webmanifest`) | | `public/sw.js` | Service worker z logiką cache | | `src/shared/components/PwaRegister.tsx` | Komponent kliencki rejestrujący service worker | | `src/app/offline/page.tsx` | Strona fallback offline z żywym wskaźnikiem statusu | | `src/app/layout.tsx` | Root layout z metadanymi PWA (apple-web-app, theme-color itd.) | | `public/icon-512.png` | Ikona PNG 512×512 (Android, splash screen) | | `public/apple-touch-icon.png` | Ikona PNG 180×180 (ekran główny iOS) | | `public/icon-192.svg` | Ikona SVG 192×192 (Android adaptive) | | `public/apple-touch-icon.svg` | Ikona SVG 180×180 (fallback Apple) |