Plik manifestu aplikacji internetowej to utworzony przez Ciebie plik informujący przeglądarkę o sposobie wyświetlania treści internetowych jako aplikacji w systemie operacyjnym. Plik manifestu może zawierać podstawowe informacje, takie jak nazwa, ikona i kolor motywu, a także ustawienia zaawansowane (np. żądana orientacja i skróty aplikacji) oraz metadane katalogu, np. zrzuty ekranu.
Każda aplikacja PWA powinna zawierać 1 plik manifestu (zazwyczaj przechowywany w folderze głównym) i połączony ze wszystkimi stronami HTML, na których można ją zainstalować. Jej oficjalne rozszerzenie to .webmanifest
, więc możesz nadać manifestowi nazwę podobną do app.webmanifest
.
Dodawanie pliku manifestu aplikacji internetowej do PWA
Aby utworzyć manifest aplikacji internetowej, najpierw utwórz plik tekstowy z obiektem JSON zawierającym co najmniej pole name
z wartością będącą ciągiem znaków:
app.webmanifest:
{
"name": "My First Application"
}
Samo utworzenie pliku nie wystarczy, bo przeglądarka też musi wiedzieć, że on istnieje.
Łączenie z plikiem manifestu
Aby poinformować przeglądarkę o pliku manifestu aplikacji internetowej, połącz ją z PWA za pomocą elementu HTML <link>
i atrybutu rel
ustawionego na manifest
na wszystkich stronach HTML aplikacji PWA. Działa to podobnie do łączenia arkusza stylów CSS z dokumentem.
index.html:
<html lang="en">
<title>This is my first PWA</title>
<link rel="manifest" href="/app.webmanifest">
Debugowanie pliku manifestu
Aby upewnić się, że plik manifestu jest prawidłowo skonfigurowany, możesz użyć inspektora w Firefoksie i Narzędzi deweloperskich w każdej przeglądarce opartej na Chromium.
Przeglądarki Chromium
W Narzędziach deweloperskich
- W panelu po lewej stronie w sekcji Aplikacja wybierz Plik manifestu.
- Sprawdź pola pliku manifestu w sposób przeanalizowany przez przeglądarkę.
W przeglądarce Firefox
- Otwórz inspektora.
- Otwórz kartę Application.
- W panelu po lewej stronie wybierz opcję „Plik manifestu”.
- Sprawdź pola pliku manifestu w sposób przeanalizowany przez przeglądarkę.
Projektowanie aplikacji PWA
Po połączeniu aplikacji PWA z plikiem manifestu musisz wypełnić pozostałe pola, aby określić interfejs dla użytkowników.
Pola podstawowe
Pierwszy zestaw pól zawiera podstawowe informacje o Twojej aplikacji PWA. Służą do utworzenia ikony i okna zainstalowanej aplikacji PWA oraz do określania sposobu uruchamiania. Są to:
name
- Pełna nazwa Twojej PWA. Ikona pojawi się wraz z ikoną na ekranie głównym, w programie uruchamiającym, doku lub w menu systemu operacyjnego.
short_name
- Opcjonalnie, krótsza nazwa aplikacji PWA, która jest używana, gdy nie ma wystarczająco dużo miejsca, aby wyświetlić pełną wartość pola
name
. Nie przekraczaj 12 znaków, aby zminimalizować ryzyko obcięcia. icons
- Tablica obiektów ikon z polami
src
,type
,sizes
i opcjonalnymi polamipurpose
, opisujących obrazy, które powinny przedstawiać PWA. start_url
- Adres URL, który ma załadować PWA, gdy użytkownik uruchamia ją po kliknięciu ikony instalacji. Zalecana jest ścieżka bezwzględna, więc jeśli strona główna Twojej aplikacji PWA znajduje się w katalogu głównym witryny, możesz ustawić w tym atrybucie znak „/”, aby otwierać ją przy uruchamianiu aplikacji. Jeśli nie podasz początkowego adresu URL, przeglądarka może jako punktu wyjścia użyć adresu URL, z którego została zainstalowana PWA. Zamiast ekranu głównego może to być precyzyjny link, np. szczegóły produktu.
display
- Jedna z wartości
fullscreen
,standalone
,minimal-ui
lubbrowser
opisująca, jak system operacyjny powinien wyświetlać okno PWA. Więcej informacji o różnych trybach wyświetlania znajdziesz w rozdziale na temat projektowania aplikacji. W większości przypadków użycia korzysta się zstandalone
. id
- Ciąg znaków jednoznacznie identyfikujący tę aplikację PWA względem innych, które mogą być hostowane w tym samym źródle. Jeśli nie jest skonfigurowany,
start_url
będzie używany jako wartość zastępcza. Pamiętaj, że zmianastart_url
w przyszłości (np. podczas zmiany wartości ciągu zapytania) może uniemożliwić przeglądarce wykrycie, że aplikacja PWA jest już zainstalowana.
Ikony
Ikona aplikacji PWA to jej wizualna tożsamość na wszystkich urządzeniach użytkowników po zainstalowaniu, dlatego ważne jest, by zdefiniować przynajmniej jedną z nich. Właściwość icons
jest zbiorem obiektów ikon, dlatego możesz zdefiniować kilka ikon w różnych formatach, aby zapewnić użytkownikom najlepsze wrażenia. Każda przeglądarka wybierze co najmniej jedną ikonę w zależności od swoich potrzeb i systemu operacyjnego, w którym jest zainstalowana. Ikony są zgodne z potrzebnymi specyfikacjami.
Jeśli chcesz wybrać tylko jeden rozmiar ikony, powinien on mieć 512 x 512 pikseli. Zalecamy jednak podanie większej liczby rozmiarów, w tym również obrazów o rozdzielczości 192 x 192, 384 x 384 i 1024 x 1024 piksele.
"icons": [
{
"src": "icons/512.png",
"type": "image/png",
"sizes": "512x512"
},
{
"src": "icons/1024.png",
"type": "image/png",
"sizes": "1024x1024"
}
]
Jeśli nie dodasz ikony lub ikony nie mają zalecanych rozmiarów, niektóre platformy nie spełnią kryteriów instalacji. Na innych platformach ikona zostanie wygenerowana automatycznie, np. na podstawie zrzutu ekranu z progresywną aplikacją internetową lub ikony ogólnej.
Ikony z możliwością maskowania
Niektóre systemy operacyjne, takie jak Android, dostosowują ikony do różnych rozmiarów i kształtów. Na przykład w Androidzie 12 różni producenci lub ustawienia mogą zmieniać kształt ikon z okręgów na kwadraty na kwadraty z zaokrąglonymi narożnikami. Aby obsługiwać tego rodzaju ikony adaptacyjne, możesz udostępnić ikonę z możliwością maskowania w polu purpose
.
W tym celu prześlij kwadratowy obraz, którego główna ikona znajduje się w „bezpiecznej strefie”, czyli okręgu pośrodku ikony i promień 40% jej szerokości. (zobacz ilustrację poniżej). Urządzenia, które obsługują ikony z możliwością maskowania, będą maskować ikonę w razie potrzeby.
Oto przykład ikony z możliwością maskowania wyrenderowanej w wielu często używanych kształtach:
Jeśli na ilustracji poniżej użyjesz ikony po lewej stronie jako ikony z możliwością maskowania, po zastosowaniu maski kształtu na urządzeniach uzyskasz słabe wyniki.
Ten obraz można wykorzystać z większym dopełnieniem.
Ikony z możliwością maskowania powinny mieć rozmiar co najmniej 512 x 512 pikseli. Po utworzeniu takiego elementu możesz dodać go do kolekcji w usłudze icons
, aby lepiej wykorzystać jego możliwości na obsługiwanych urządzeniach:
"icons": [
{
"src": "/icons/512.png",
"type": "image/png",
"sizes": "512x512"
},
{
"src": "/icons/1024.png",
"type": "image/png",
"sizes": "1024x1024"
},
{
"src": "/icons/512-maskable.png",
"type": "image/png",
"sizes": "512x512",
"purpose": "maskable"
},
]
W większości przypadków, jeśli ikona z możliwością maskowania nie wyświetla się prawidłowo, można ją ulepszyć, dodając więcej dopełnienia. Maskable.app to bezpłatne narzędzie online do testowania i tworzenia wersji ikony z możliwością maskowania.
Pola zalecane
Następny zestaw pól, które musisz uwzględnić, to pola, które poprawią wrażenia użytkowników, nawet jeśli nie są wymagane do zainstalowania.
theme_color
- Domyślny kolor aplikacji, który może wpływać na sposób wyświetlania witryny w systemie operacyjnym (np. kolor okna i paska tytułu na komputerze lub pasek stanu na urządzeniach mobilnych). Ten kolor można zastąpić elementem HTML
theme-color
<meta>
. background_color
- Kolor zastępczy wyświetlany w tle aplikacji przed wczytaniem arkusza stylów. Safari na iOS i iPadOS oraz w większości przeglądarek na komputerach obecnie ignorują to pole.
scope
- Zmienia zakres nawigacji aplikacji PWA, co pozwala określić, co jest, a co nie jest wyświetlane w oknie zainstalowanej aplikacji. Jeśli na przykład umieścisz link do strony spoza zakresu, zostanie ona wyrenderowana w przeglądarce w aplikacji, a nie w oknie PWA. Nie zmieni to jednak zakresu Twojego skryptu service worker.
Na następnym obrazie widać wykorzystanie pola theme_color
na pasku tytułu na komputerze podczas instalowania aplikacji PWA.
Do definiowania kolorów w pliku manifestu, na przykład w theme_color
i background_color
, należy używać nazwanych kolorów CSS, takich jak salmon
lub orange
, kolorów RGB (#FF5500
) lub funkcji kolorów bez przezroczystości, takich jak rgb()
lub hsl()
. Więcej informacji znajdziesz w sekcji na temat projektowania aplikacji.
Wypróbuj
Ekrany powitalne
Na niektórych urządzeniach podczas ładowania aplikacji PWA renderowany jest statyczny obraz, dzięki czemu użytkownik natychmiast otrzymuje opinię.
Android generuje ekran powitalny na podstawie wartości theme_color
, background_color
i icon
.
Gdy zainstalujesz aplikację PWA na Androidzie, urządzenie wygeneruje ekran powitalny z informacjami pochodzącymi z pliku manifestu, tak jak na tym schemacie.
Safari na iOS i iPadOS nie używa natomiast pliku manifestu aplikacji internetowej do generowania ekranów powitalnych. Zamiast tego używają obrazu, który pochodzi z zastrzeżonego elementu <link>
, podobnie jak w przypadku ich obsługi. Więcej informacji znajdziesz w rozdziałie o ulepszeniach.
Pola rozszerzone
Następny zestaw pól zawiera dodatkowe informacje o Twojej aplikacji PWA. Wszystkie są opcjonalne.
lang
- Tag języka określający podstawowy język wartości w pliku manifestu, na przykład
en
dla języka angielskiego,pt-BR
dla języka brazylijskiego iin
w języku hindi. dir
- Kierunek wyświetlania pól manifestu z ustawionym kierunkiem (np.
name
,short_name
idescription
). Prawidłowe wartości toauto
,ltr
(od lewej do prawej) irtl
(od prawej do lewej). orientation
- Oczekiwana orientacja aplikacji po zainstalowaniu. Gra może skonfigurować to ustawienie tak, aby żądała tylko orientacji poziomej. Akceptowanych jest kilka wartości, ale ich podanie jest zwykle jawne, czyli
portrait
lublandscape
.
Pola promocyjne
Czwarty zestaw pól umożliwia podanie informacji promocyjnych dotyczących Twojej aplikacji PWA, na przykład w procesie instalacji, informacjach o aplikacji i wynikach wyszukiwania.
description
- Wyjaśnienie, do czego służy PWA.
screenshots
- Tablica obiektów zrzutów ekranu z
src
,type
isizes
(podobna do obiektuicons
), która służy do prezentowania aplikacji PWA. Nie ma żadnych ograniczeń rozmiaru. categories
- Tablica kategorii, w których PWA powinna być używana jako wskazówki, opcjonalnie może znajdować się na liście znanych kategorii. Wartości te są zwykle pisane małymi literami.
iarc_rating_id
- Kod certyfikatu PWA (International Age Rating Coalition) dla PWA, jeśli go masz. Te dane powinny być używane do określenia, dla jakich grup wiekowych jest odpowiednia aplikacja PWA.
Już dziś możesz zobaczyć, jak działają te pola promocyjne. Jeśli na przykład na Androidzie można zainstalować PWA i podasz wartości w co najmniej polach description
i screenshots
, okno dialogowe instalacji zmieni się z prostego paska informacyjnego „Dodaj do ekranu głównego” na bogatsze okno instalacji podobne do tego ze sklepu z aplikacjami.
W przypadku Androida możesz uzyskać lepszy interfejs instalacji, jeśli podasz wartości w polach promocyjnych, jak widać w następnym filmie.
Zobacz, jak działają te pola promocyjne:
Pola możliwości
Jest też sporo pól związanych z różnymi możliwościami, z których Twoja aplikacja PWA może być używana w obsługiwanych przeglądarkach, takich jak pola shortcuts
, share_target
i display_overrides
, które opisujemy w rozdziale o możliwościach. Istnieją też pola, takie jak related_apps
i prefer_related_apps
(więcej informacji znajdziesz w rozdziale o wykrywaniu), które umożliwiają łączenie Twojej aplikacji PWA z zainstalowanymi aplikacjami, często ze sklepu z aplikacjami.
W przyszłości może pojawić się wiele nowych pól, gdy przeglądarki wzbogacają możliwości progresywnych aplikacji internetowych.