Przewodnik po manifestach aplikacji internetowych
Manifest aplikacji internetowej (site.webmanifest) to plik JSON, który informuje przeglądarki instalacyjne o nazwie, kolorach, trybie wyświetlania i rozmiarach ikon aplikacji na ekranie głównym. Połączenie go z `<link rel='manifest' href='/site.webmanifest'>` włącza monit instalacyjny Chrome i Edge PWA na komputerze stacjonarnym i Android. Połącz go z ikonami 192×192 i 512×512 PNG — obie wyeksportowane przez favicon generator — aby uzyskać kompletną konfigurację favikon PWA.
Manifest aplikacji internetowej to plik tekstowy JSON udostępniany z typem MIME `application/manifest+json`. Znajduje się pod dowolnym wybranym adresem URL, ale w katalogu głównym domeny obowiązuje konwencja /site.webmanifest. Łączysz go z HTML za pomocą `<link rel='manifest' href='/site.webmanifest'>` wewnątrz elementu `<head>`. Przeglądarka odczytuje manifest, gdy ocenia, czy wyświetlić monit o instalację lub jak wyrenderować aplikację po instalacji.
Tablica ikon jest najbardziej istotną częścią manifestu związaną z faviconami. Każdy wpis określa src (adres URL obrazu), rozmiary (wymiary w pikselach), typ (typ MIME) i opcjonalnie cel (albo „dowolny”, „maskowalny” lub „dowolny maskowalny”). Podaj co najmniej 192 × 192 PNG dla ikony programu uruchamiającego i 512 × 512 PNG dla ekranu powitalnego. Bez nich Chrome nie wyświetli monitu o instalację.
Ikona 192×192 jest używana przez Android Chrome w programie uruchamiającym aplikacje, przełączniku najnowszych aplikacji i obszarze powiadomień, gdy PWA wysyła powiadomienie web push. Musi to być PNG, dostępny pod zadeklarowanym adresem URL bez przekierowań i dostarczany z odpowiednimi nagłówkami CORS, jeśli znajduje się w innej domenie niż Twój manifest. favicon generator eksportuje plik android-chrome-192x192.png gotowy do bezpośredniego użycia.
Ikona 512×512 jest używana na ekranie powitalnym PWA wyświetlanym podczas ładowania aplikacji po uruchomieniu na ekranie głównym, w podglądzie okna dialogowego instalacji w Chrome i Edge na komputerze oraz w programie uruchamiającym aplikacje systemu operacyjnego Chrome. Brakujący wpis 512×512 w manifeście nie blokuje instalacji, ale powoduje wyświetlenie ogólnej ikony przeglądarki na ekranie powitalnym. Zawsze dołączaj go, aby zapewnić dopracowaną instalację.
Ikony z możliwością maskowania są ulepszeniem specyficznym dla Android. Adaptacyjny system ikon Android stosuje maski geometryczne (okrąg, zawijas, łza, zaokrąglony prostokąt) do ikon aplikacji, a ich kształt różni się w zależności od producenta urządzenia. Krawędzie standardowej „dowolnej” ikony mogą zostać przycięte przez te maski. Ikona „maskowalna” zawiera wyściółkę bezpiecznej strefy — najważniejsze grafiki powinny znajdować się pośrodku 80% obrazu (okrąg bezpiecznej strefy) — dzięki czemu można zastosować dowolną maskę bez przycinania logo.
Aby zadeklarować ikonę maskującą w manifeście, dodaj drugi wpis o tym samym rozmiarze z `'purpose': 'maskable'`: `{ "src": "/android-chrome-512x512-maskable.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }`. Możesz także połączyć: `'purpose': 'any maskable'` w jednym wpisie. Wygeneruj ikonę maskowalną z dodatkowym wypełnieniem, korzystając z opcji eksportu maskowalnego generatora.
Pola nazwa i krótka nazwa określają sposób oznaczania aplikacji na ekranie głównym i w szufladzie aplikacji. `name` to pełna nazwa aplikacji wyświetlana w monicie instalacji. `short_name` to etykieta pod ikoną na ekranie głównym — nie powinna przekraczać 12 znaków, aby uniknąć obcięcia na mniejszych ekranach. Aby pojawił się monit o instalację, wymagane są oba pola.
Pole topic_color ustawia kolor paska adresu przeglądarki na Android Chrome, gdy użytkownik przejdzie do Twojej witryny (nie tylko wtedy, gdy PWA jest zainstalowany). Ustawia również kolor paska narzędzi w samodzielnym trybie PWA. Użyj podstawowego koloru marki jako wartości szesnastkowej. Dodaj pasujący ciąg „<meta name='theme-color' content='#YOUR_COLOR'>” do HTML dla przeglądarek, które nie czytają motywu_koloru manifestu.
Pole kolor tła kontroluje kolor tła ekranu powitalnego pokazywany pomiędzy uruchomieniem PWA a pierwszym malowaniem zawartości aplikacji. Ustaw go tak, aby pasował do tła aplikacji (zwykle biały lub podstawowy kolor marki), aby zapobiec drażniącemu błyskowi. Jeśli kolor tła nie odpowiada rzeczywistemu tłu aplikacji, użytkownicy widzą przeskok kolorów podczas uruchamiania.
Pole wyświetlacza określa wygląd PWA po instalacji. `standalone` ukrywa pasek adresu przeglądarki i przyciski nawigacyjne, dzięki czemu aplikacja wygląda jak aplikacja natywna. `minimal-ui` utrzymuje minimalny pasek nawigacyjny. `fullscreen` usuwa wszystko łącznie z paskiem stanu. `browser` pokazuje pełny interfejs przeglądarki. Dla większości PWA właściwym wyborem jest `standalone`. Monit o instalację nie pojawia się, jeśli wyświetlacz jest ustawiony na `browser`.
Pole start_url określa, który adres URL otwiera się, gdy użytkownik uruchomi zainstalowany PWA z ekranu głównego. Zawsze dołączaj tę informację — bez niej Android otwiera adres URL, pod którym odkryto manifest, który może być stroną z precyzyjnymi linkami, a nie stroną główną. Użyj `'start_url': '/'` w przypadku większości witryn lub konkretnego adresu URL, jeśli aplikacja musi zaczynać się od określonej trasy.
Debugowanie problemów z manifestem jest proste w Chrome DevTools. Otwórz DevTools (F12), przejdź do karty Aplikacja i kliknij Manifest w lewym panelu. Chrome pokazuje przeanalizowany widok manifestu, wszelkie błędy analizy, błędy pobierania ikon oraz listę kontrolną „Możliwość instalacji”, która wyjaśnia, dlaczego monit o instalację może się nie wyświetlać. Typowe problemy to: nie znaleziono ikon (404), nieprawidłowy typ MIME lub brak ikony 192×192.
Prawidłowe udostępnienie manifestu wymaga dwóch konfiguracji po stronie serwera. Po pierwsze, plik musi być dostarczony z `Content-Type: application/manifest+json`. Po drugie, jeśli Twoje ikony znajdują się w sieci CDN lub w innym pochodzeniu niż manifest, odpowiedzi dotyczące ikon muszą zawierać odpowiednie nagłówki CORS (`Access-Control-Allow-Origin: *` lub Twoja domena). Brakujące nagłówki CORS w plikach ikon spowodują, że przeglądarka potraktuje manifest jako nieprawidłowy.
W przypadku platform, które automatycznie generują manifest, sprawdź, czy wygenerowany plik zawiera rzeczywiste rozmiary i kolory ikon. Next.js generuje manifest na podstawie eksportu /app/manifest.ts. Utwórz aplikację React generuje plik /public/manifest.json. Vite domyślnie nie generuje manifestu — utwórz go ręcznie. We wszystkich przypadkach zaktualizuj tablicę ikon, aby odnosiła się do rzeczywistych plików ikon marki, a nie do domyślnych ikon zastępczych.
Jak to działa
- 1
Wygeneruj ikony 192×192 i 512×512 PNG
Prześlij swoje logo 512×512 PNG lub SVG do [favicon generator](tool:favicon-generator). Pakiet do pobrania zawiera pliki Android-chrome-192x192.png i Android-chrome-512x512.png gotowe do bezpośredniego użycia.
- 2
Utwórz site.webmanifest
Utwórz plik JSON zawierający co najmniej: `name`, `short_name`, `icons` (192 i 512 wpisów), `theme_color`, `background_color` i `display: 'standalone'`. Pakiet generatora zawiera wstępnie wypełniony szablon manifestu.
- 3
Podaj manifest z poprawnym typem MIME
Skonfiguruj swój serwer do obsługi plików .webmanifest z `Content-Type: application/manifest+json`. Na Apache dodaj `AddType application/manifest+json .webmanifest` do .htaccess. W Nginx dodaj typ MIME do mime.types.
- 4
Połącz manifest w HTML
Dodaj `<link rel='manifest' href='/site.webmanifest'>` wewnątrz swojego `<head>`. Dodaj także `<meta name='theme-color' content='#YOUR_COLOR'>` dla przeglądarek, które nie czytają manifestu topic_color.
- 5
Sprawdź za pomocą Chrome DevTools
Otwórz Chrome DevTools > Aplikacja > Manifest. Upewnij się, że nie są wyświetlane żadne błędy, a wszystkie ikony zostały rozwiązane. Sprawdź sekcję Możliwość instalacji, aby dowiedzieć się, jakie kryteria zostały spełnione lub nie w przypadku monitu o instalację PWA.
- 6
Przetestuj monit instalacyjny
Na Android Chrome przejdź do swojej witryny. Jeśli wszystkie kryteria są spełnione, Chrome wyświetla baner instalacyjny lub opcję „Dodaj do ekranu głównego” w menu przeglądarki. Po instalacji sprawdź, czy kolor tła ekranu powitalnego i ikona ekranu głównego są poprawnie renderowane.
Wypróbuj teraz
Wygeneruj pakiet ikon PWA
Generator FaviconFAQ
Czy w przypadku podstawowej witryny internetowej wymagany jest manifest aplikacji internetowej?+
Nie — tylko jeśli chcesz, aby PWA był wyświetlany na ekranie głównym na Android i komputerze stacjonarnym Chrome/Edge. Sam favicon.ico obsługuje karty przeglądarki. Dodaj manifest, jeśli chcesz zapewnić bogatsze możliwości instalacji na urządzeniach mobilnych i komputerach stacjonarnych.
Jakie rozmiary ikon są uwzględniane w manifeście aplikacji internetowej?+
Co najmniej: 192×192 (program uruchamiający Android) i 512×512 (ekran powitalny i podgląd instalacji). Dodaj maskowalne warianty obu rozmiarów, aby uzyskać adaptacyjną obsługę ikon Android, i 384 × 384, jeśli chcesz uzyskać dodatkowe pokrycie gęstości.
Jaka jest różnica między kolorem motywu a kolorem tła w manifeście?+
motyw_koloru ustawia kolor paska adresu przeglądarki i paska narzędzi. kolor_tła ustawia kolor tła ekranu powitalnego pokazywany przed pierwszym malowaniem aplikacji. Ustaw oba tak, aby pasowały do Twojej marki, aby zapewnić bezproblemową instalację i uruchomienie.
Dlaczego Chrome nie wyświetla monitu o instalację mojego PWA?+
Najczęstsze przyczyny to: brakujący lub nieprawidłowy manifest, brakująca ikona 192×192, ikony zwracające 404, manifest niepodawany z poprawnym typem MIME lub witryna nie jest obsługiwana przez HTTPS. Użyj Chrome DevTools > Aplikacja > Manifest, aby zobaczyć dokładną przyczynę niepowodzenia instalacji.
Co to jest ikona maskowalna i czy jest mi potrzebna?+
Ikona z możliwością maskowania zawiera wyściółkę w bezpiecznej strefie, dzięki czemu Android może nakładać maski okrągłe lub wijące się bez przycinania logo. Potrzebujesz jej, aby ikona na ekranie głównym wyglądała poprawnie na urządzeniach Android, które korzystają z adaptacyjnych kształtów ikon innych niż kwadratowe. Zadeklaruj to za pomocą `'purpose': 'maskable'` w tablicy ikon manifestu.
Czy mogę używać ikon SVG w manifeście aplikacji internetowej?+
Chromium obsługuje SVG w niektórych kontekstach ikon manifestu, ale PNG jest uniwersalnie bezpiecznym ustawieniem domyślnym dla interfejsów użytkownika instalacji w różnych przeglądarkach. Zawsze dołączaj wpisy PNG 192 i 512. Możesz dodać obok nich wpis SVG bez szkody.
Jak sprawdzić, czy mój manifest internetowy jest ważny?+
Otwórz Chrome DevTools (F12) > Aplikacja > Manifest. Chrome pokazuje błędy analizy, błędy pobierania ikon i pełną listę kontrolną możliwości instalacji. Napraw wszelkie zgłoszone problemy, a następnie ponownie przetestuj monit instalacyjny, korzystając z opcji „Dodaj do ekranu głównego” na pasku adresu Chrome.