Manifest aplikacji internetowej

Manifest aplikacji internetowej to plik JSON, który informuje przeglądarkę, jak zainstalować stronę jako aplikację: jakiej nazwy użyć, jaką ikonę wyświetlić, jaki adres URL uruchomić, jaki schemat kolorów zastosować oraz w jakim trybie wyświetlania uruchomić aplikację (standalone, fullscreen, browser).

Odwołuj się do manifestu na każdej stronie, którą można zainstalować: <link rel="manifest" href="/manifest.webmanifest"> w sekcji head. Przeglądarka pobiera go raz i zapisuje w pamięci podręcznej; zmiany w manifeście zostaną uwzględnione przy kolejnych ładowaniach.

Aby przeglądarka mogła zaoferować opcję „Zainstaluj aplikację”, manifest musi zawierać co najmniej: name (pełna nazwa), short_name (etykieta na ekranie głównym, około 12 znaków), start_url, display (zwykle „standalone”) oraz tablicę icons zawierającą co najmniej pliki PNG w rozmiarach 192x192 i 512x512.

Adres URL uruchamiany po dotknięciu ikony zainstalowanej aplikacji. Często jest to / dla strony głównej; można też dodać parametry zapytania na potrzeby analityki: "start_url": "/?source=pwa" pozwala odróżnić sesje zainstalowanej aplikacji od sesji w przeglądarce.

display może mieć wartość „browser” (standardowe elementy interfejsu przeglądarki), „minimal-ui” (część elementów interfejsu), „standalone” (brak elementów interfejsu przeglądarki — wygląd aplikacji) lub „fullscreen” (brak paska stanu). Standalone to typowy wybór dla PWA.

Dołącz ikonę z przeznaczeniem „maskable”, aby system Android mógł dopasować jej kształt do pozostałych ikon na ekranie głównym: { src: "/icon-mask.png", sizes: "192x192", purpose: "maskable" }. Ikony maskable zawierają bezpieczny obszar, który system może przyciąć.

theme_color ustawia odcień paska adresu, gdy aplikacja działa w przeglądarce. background_color jest wyświetlany jako kolor tła ekranu powitalnego przed załadowaniem strony. Aby uruchamianie wyglądało profesjonalnie, dopasuj te wartości do głównych kolorów systemu projektowego.

"orientation": "portrait" blokuje aplikację w orientacji pionowej po jej zainstalowaniu. Alternatywami są „any”, „landscape” i „portrait-primary”. Większość uniwersalnych aplikacji PWA pozostawia to pole nieustawione i pozwala urządzeniu decydować o orientacji.

Aby przeglądarka wyświetliła opcję „Zainstaluj”, strona musi być udostępniana przez HTTPS, rejestrować service workera obsługującego zdarzenia fetch, zawierać prawidłowo połączony manifest z minimalnym zestawem pól oraz spełniać kryteria zaangażowania (użytkownik musiał wejść w interakcję ze stroną).

Przeglądarki zapisują manifest w pamięci podręcznej. Aby wymusić odświeżenie po wprowadzeniu zmian, zmień adresy URL ikon (zadziała parametr zapytania unieważniający pamięć podręczną) albo poczekaj — większość przeglądarek sprawdza je okresowo. Nie ma API do wymuszania aktualizacji, dlatego należy założyć, że użytkownicy mogą przez pewien czas korzystać z nieco nieaktualnego manifestu.

Zakładka Application w Chrome DevTools pokazuje sparsowany manifest, obliczone wartości i błędy walidacji. Audyt PWA w Lighthouse sprawdza wszystkie wymagania instalacji i informuje, czego brakuje. Podczas tworzenia używaj obu narzędzi, aby potwierdzić możliwość zainstalowania aplikacji.

Co robi wartość display: "standalone" w manifeście aplikacji internetowej?

Manifest aplikacji internetowej (manifest.webmanifest) informuje przeglądarkę, jak zainstalować stronę jako aplikację: name, short_name, start_url, display, theme_color oraz ikony (192 i 512, a także maskable dla Androida). Dołącz go za pomocą <link rel="manifest">, zapewnij HTTPS i service workera, aby umożliwić instalację, a następnie testuj aplikację w Chrome DevTools i podczas audytu PWA w Lighthouse.