Web App Manifest

Web App Manifest (często określany po prostu jako manifest lub manifest.json) jest plikiem w formacie JSON, który opisuje metadane aplikacji internetowej, umożliwiając jej zachowanie się jak natywna aplikacja na urządzeniach mobilnych i stacjonarnych. Dzięki manifestowi przeglądarki są w stanie wyświetlać ikonę, nazwę, motyw kolorystyczny oraz określać sposób uruchamiania aplikacji po dodaniu jej do ekranu głównego.

Historia i standard

Projekt manifestu został wprowadzony jako część inicjatywy Progressive Web Apps (PWA) oraz specyfikacji W3C. Pierwsza wersja Web App Manifest została zatwierdzona w 2015 roku i od tego czasu jest rozwijana pod egidą grupy WHATWG.

Podstawowa struktura

Plik manifestu zazwyczaj nosi nazwę manifest.json i znajduje się w katalogu głównym serwisu lub pod dowolnym dostępny przez URL. Przykładowa struktura:

{
    "name": "Przykładowa Aplikacja",
    "short_name": "Aplikacja",
    "start_url": "/index.html",
    "display": "standalone",
    "background_color": "#ffffff",
    "theme_color": "#2196f3",
    "icons": [
        {
            "src": "/icons/icon-192.png",
            "sizes": "192x192",
            "type": "image/png"
        },
        {
            "src": "/icons/icon-512.png",
            "sizes": "512x512",
            "type": "image/png"
        }
    ]
}

Powyższy przykład zawiera najważniejsze pola opisane w specyfikacji.

Główne pola manifestu

Pole	Opis	Typ danych
`name`	Pełna nazwa aplikacji wyświetlana w menu systemu i w interfejsie instalatora.	string
`short_name`	Skrócona nazwa, używana tam, gdzie miejsce jest ograniczone (np. pod ikoną na ekranie startowym).	string
`start_url`	Adres URL, otwierany po uruchomieniu aplikacji z ekranu głównego.	string (URL)
`display`	Określa tryb wyświetlania aplikacji: `fullscreen`, `standalone`, `minimal-ui` lub `browser`.	string
`orientation`	Preferowana orientacja ekranu (np. `portrait`, `landscape`).	string
`background_color`	Kolor tła wyświetlany podczas uruchamiania aplikacji.	string (hex, rgba, itp.)
`theme_color`	Kolor motywu używany m.in. w pasku adresu przeglądarki lub w systemowym paska powiadomień.	string (hex, rgba, itp.)
`icons`	Tablica obiektów opisujących ikony aplikacji w różnych rozmiarach.	array of objects
`scope`	Zakres URL, w których manifest wpływa na zachowanie aplikacji.	string (URL)
`related_applications`	Informacje o powiązanych natywnych aplikacjach (np. w Google Play, App Store).	array of objects
`prefer_related_applications`	Flaga wskazująca, czy przeglądarka ma preferować instalację natywnej aplikacji zamiast PWA.	boolean

Implementacja w przeglądarkach

Wsparcie dla Web App Manifest jest dostępne w większości nowoczesnych przeglądarek, w tym:

Google Chrome (od wersji 38)
Mozilla Firefox (od wersji 44)
Microsoft Edge (od wersji 17)
Apple Safari (od wersji 12.1, z ograniczonym wsparciem)

W przeglądarce manifest jest pobierany za pośrednictwem elementu <link rel="manifest" href="manifest.json"> umieszczonego w sekcji <head> strony.

Powiązanie z innymi technologiami PWA

Manifest jest jednym z trzech filarów Progressive Web Apps:

Service Worker – zapewnia działanie offline i powiadomienia push.
Web App Manifest – definiuje wygląd i zachowanie aplikacji w trybie natywnym.
HTTPS – wymóg bezpieczeństwa zapewniający integralność zasobów.

Dzięki współpracy tych elementów przeglądarki mogą instalować aplikację na ekranie głównym, uruchamiać ją w trybie pełnoekranowym i zapewniać dostęp do funkcji offline.

Przykładowe zastosowanie

Załóżmy, że tworzymy prostą aplikację do notatek Notatnik. Aby przekształcić ją w PWA, wykonujemy następujące kroki:

Tworzymy plik manifest.json z odpowiednimi polami (ikonki, kolory, display: "standalone").
Dodajemy w <head> element <link rel="manifest" href="/manifest.json">.
Rejestrujemy service worker, który buforuje zasoby.
Zapewniamy, że cała strona jest serwowana przez HTTPS.

Po spełnieniu tych wymogów użytkownik zobaczy w przeglądarce przycisk „Dodaj do ekranu głównego”, a po instalacji aplikacja będzie wyglądała i zachowywała się jak natywna aplikacja mobilna.

Najczęstsze problemy i ich rozwiązywanie

Brak wyświetlania ikony: Upewnij się, że pola src w sekcji icons wskazują na istniejące pliki oraz że rozmiary są zgodne z wymaganiami platformy (np. 192 px i 512 px dla Androida).
Manifest nie jest wykrywany: Sprawdź, czy element <link rel="manifest"> znajduje się w <head> i że URL jest poprawny.
Problem z kolorem motywu: Niektóre przeglądarki odczytują theme_color tylko w trybie standalone. Upewnij się więc, że display jest ustawiony odpowiednio.
Nieoczekiwane zachowanie przy uruchamianiu: Skonfiguruj pole scope, aby odciąć aplikację od niepowiązanych części witryny.

Przyszłość i rozwój

Obecna specyfikacja przewiduje dodatkowe funkcje, takie jak:

Wsparcie dla Web Share API w kontekście manifestu.
Rozszerzone pola opisujące dostępność (ARIA) aplikacji.
Lepszą integrację z sklepami aplikacji (Google Play, Microsoft Store).

W miarę jak ekosystem PWA będzie się rozwijał, rola Web App Manifest będzie kluczowa w dostarczaniu spójnych doświadczeń użytkownika na różnych platformach.

Źródła i dalsza lektura

Pełną specyfikację oraz przykłady kodu można znaleźć w dokumentacji W3C oraz w materiałach przygotowanych przez społeczność WHATWG. Dodatkowo wartościowe artykuły pojawiają się w sekcjach poświęconych Progressive Web Apps oraz service workerom.