Manifest aplikacji internetowej

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

  1. W panelu po lewej stronie w sekcji Aplikacja wybierz Plik manifestu.
  2. Sprawdź pola pliku manifestu w sposób przeanalizowany przez przeglądarkę.

W przeglądarce Firefox

  1. Otwórz inspektora.
  2. Otwórz kartę Application.
  3. W panelu po lewej stronie wybierz opcję „Plik manifestu”.
  4. 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 polami purpose, 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 lub browser 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ę z standalone.
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 zmiana start_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.

bezpieczny obszar oznaczony jako 40-procentowe koło o promieniu wyśrodkowanym w kwadratowej ikonie;

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.

Ikona, która nie jest odpowiednia dla ikony z możliwością maskowania.

Ten obraz można wykorzystać z większym dopełnieniem.

Ikona z większym dopełnieniem jest odpowiednia dla masek.

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.

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.

Ta sama aplikacja PWA zainstalowana na komputerze ma inny kolor motywu.

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.

PWA na ekranie powitalnym Androida przy użyciu innych wartości z pliku manifestu.

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 i in w języku hindi.
dir
Kierunek wyświetlania pól manifestu z ustawionym kierunkiem (np. name, short_name i description). Prawidłowe wartości to auto, ltr (od lewej do prawej) i rtl (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 lub landscape.

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 i sizes (podobna do obiektu icons), 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.

Zasoby