Manifest aplikacji internetowej

Manifest aplikacji internetowej to tworzony przez Ciebie plik, który informuje przeglądarkę, w jaki sposób Twoje treści internetowe mają być wyświetlane jako aplikacja w systemie operacyjnym. Plik manifestu może zawierać podstawowe informacje, takie jak nazwa aplikacji, ikona i kolor motywu. zaawansowane ustawienia, takie jak wybrana orientacja czy skróty do aplikacji; i metadane katalogu, np. zrzuty ekranu.

Każda aplikacja PWA powinna zawierać 1 plik manifestu na aplikację, zwykle hostowany w folderze głównym i zawierający link na wszystkich stronach HTML, z których można zainstalować tę aplikację. Oficjalne rozszerzenie to .webmanifest, dlatego plik manifestu może mieć nazwę podobną do app.webmanifest.

Dodawanie pliku manifestu aplikacji internetowej do PWA

Aby utworzyć plik manifestu aplikacji internetowej, najpierw utwórz plik tekstowy z obiektem JSON, który zawiera co najmniej pole name z wartością w postaci ciągu znaków:

app.webmanifest:

{
   "name": "My First Application"
}

Jednak samo jego utworzenie nie wystarczy – przeglądarka musi o tym wiedzieć.

Łączę z Twoim plikiem manifestu

Aby poinformować przeglądarkę o manifeście aplikacji internetowej, musisz połączyć ją z PWA za pomocą elementu HTML <link> i atrybutu rel ustawionego na manifest na wszystkich stronach HTML tej aplikacji. Przypomina to łączenie 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 analizowanego przez przeglądarkę.

Firefox

  1. Otwórz inspektora.
  2. Przejdź na kartę Aplikacja.
  3. W panelu po lewej stronie wybierz opcję Plik manifestu.
  4. Sprawdź pola pliku manifestu analizowanego przez przeglądarkę.
.

Projektowanie aplikacji PWA

Po połączeniu aplikacji PWA z plikiem manifestu możesz wypełnić pozostałe pola, aby określić, jak będą korzystać z niej użytkownicy.

Pola podstawowe

Pierwszy zestaw pól zawiera podstawowe informacje o Twojej aplikacji PWA. Służą do utworzenia ikony i okna zainstalowanej aplikacji PWA oraz określają sposób jej uruchamiania. Są to:

name
Pełna nazwa Twojej aplikacji PWA. Pojawi się ona wraz z ikoną na ekranie głównym systemu operacyjnego, w Menu z aplikacjami, w Docku i menu.
short_name
Opcjonalnie: krótsza nazwa aplikacji PWA używana, gdy nie ma wystarczająco dużo miejsca na wyświetlenie pełnej wartości pola name. Wpisz poniżej 12 znaków, aby zminimalizować ryzyko obcięcia.
icons
Tablica obiektów ikon z polami src, type, sizes i opcjonalnymi purpose opisującymi obrazy, które mają reprezentować PWA.
start_url
Adres URL, który powinien wczytać PWA, gdy użytkownik uruchomi go po kliknięciu ikony instalacji. Zalecana jest ścieżka bezwzględna, jeśli więc strona główna aplikacji PWA znajduje się w katalogu głównym witryny, możesz wpisać „/” aby otwierać ją po uruchomieniu aplikacji. Jeśli nie podasz URL-a początkowego, przeglądarka może użyć adresu URL, z którego została zainstalowana aplikacja PWA. Może to być precyzyjny link, np. do szczegółowych informacji o produkcie, a nie do ekranu głównego.
display
Jedna z zasad fullscreen, standalone, minimal-ui lub browser opisująca, jak system operacyjny powinien narysować 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 z mechanizmu standalone.
id
Ciąg znaków jednoznacznie identyfikujący tę aplikację PWA względem innych aplikacji, które mogą być hostowane w tym samym źródle. Jeśli jej nie skonfigurujesz, jako wartość zastępczą będzie używana start_url. Pamiętaj, że zmiana identyfikatora start_url w przyszłości (np. przy zmianie wartości ciągu zapytania) może uniemożliwić przeglądarce wykrycie, że aplikacja PWA jest już zainstalowana.
.
. .

Ikony

Ikona aplikacji PWA reprezentuje jej wizualną tożsamość zainstalowanych urządzeń, dlatego ważne jest, aby zdefiniować co najmniej jedno. Właściwość icons jest zbiorem obiektów ikon, więc możesz zdefiniować kilka ikon w różnych formatach, aby zapewnić użytkownikom najlepsze wrażenia. Każda przeglądarka wybiera co najmniej jedną ikonę w zależności od swoich potrzeb oraz systemu operacyjnego, w którym jest zainstalowana, a ikona jest bliższa wymaganej specyfikacji.

Jeśli chcesz wybrać tylko jeden rozmiar ikony, powinien on mieć 512 na 512 pikseli. Zalecamy jednak przesłanie większej liczby rozmiarów, w tym 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 podasz żadnej ikony lub nie mają one zalecanych rozmiarów, na niektórych platformach nie spełnisz kryteriów instalacji. W przypadku innych platform ikona zostanie wygenerowana automatycznie, np. ze zrzutu ekranu aplikacji PWA lub za pomocą ogólnej ikony.

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 na Androidzie 12 różni producenci i ustawienia mogą zmienić kształt ikon z okręgów na kwadraty na kwadraty o zaokrąglonych rogach. Aby obsługiwać tego typu ikony adaptacyjne, możesz udostępnić ikonę z możliwością maskowania za pomocą pola purpose.

Aby to zrobić, prześlij kwadratowy plik graficzny, którego główna ikona znajduje się w „bezpiecznej strefie”, czyli okręgu wyśrodkowanym na ikonie w promieniu 40 procent szerokości ikony. (zobacz ilustrację poniżej). Urządzenia obsługujące ikony z możliwością maskowania w razie potrzeby będą maskowane.

Bezpieczny obszar oznaczony jako wyśrodkowany okrąg o promieniu 40 procent w kwadratowej ikonie

Oto przykład ikony z możliwością maskowania renderowanej w wielu często używanych kształtach:

Jeśli na poniższej ilustracji użyjesz ikony po lewej stronie jako ikony z możliwością maskowania, po zastosowaniu maski kształtu na urządzeniach otrzymasz słabe wyniki.

Ikona nieodpowiednia dla ikony z możliwością maskowania.

Tego obrazu można użyć, dodając dodatkowe dopełnienie.

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

Ikony z możliwością maskowania powinny mieć co najmniej 512 x 512 pikseli. Utworzone treści możesz dodać do kolekcji icons, aby zwiększyć komfort korzystania z obsługiwanych urządzeń:

"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"
   },
]

Jeśli ikona z maskowaniem nie wyświetla się prawidłowo, w większości przypadków możesz poprawić jej wygląd, dodając dopełnienie. 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 należy uwzględnić, to pola, które zwiększą wygodę użytkowników, mimo że nie są wymagane do zainstalowania.

theme_color
Domyślny kolor aplikacji, czasami wpływa na sposób wyświetlania witryny w systemie operacyjnym (na przykład kolor okna i paska tytułu na komputerach czy kolor paska 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 załadowaniem jej arkusza stylów. Safari w systemach iOS i iPadOS oraz w większości przeglądarek na komputerach obecnie ignoruje to pole.
scope
Zmienia zakres nawigacji PWA, pozwalając określić, co ma być wyświetlane w oknie zainstalowanej aplikacji. Jeśli na przykład utworzysz link do strony spoza zakresu, zostanie ona wyrenderowana w przeglądarce w aplikacji, a nie w oknie aplikacji PWA. Nie zmieni to jednak zakresu skryptu service worker.

Następny obraz pokazuje, jak podczas instalowania PWA pole theme_color jest używane jako pasek tytułu na komputerze.

Ta sama aplikacja PWA zainstalowana na komputerze z innym kolorem motywu.

Definiując kolory w pliku manifestu, np. w elementach theme_color i background_color, używaj nazwanych kolorów CSS, np. salmon lub orange, kolorów RGB, np. #FF5500, lub funkcji kolorów bez przezroczystości, np. rgb() lub hsl(). Więcej informacji znajdziesz w rozdziale na temat projektowania aplikacji.

Wypróbuj

Ekrany powitalne

Na niektórych urządzeniach podczas wczytywania aplikacji PWA obraz statyczny jest renderowany, dzięki czemu użytkownik ma natychmiastowy dostęp do informacji zwrotnych.

Android używa wartości theme_color, background_color i icon do generowania ekranu powitalnego.

Po zainstalowaniu PWA na urządzeniu z Androidem urządzenie wygeneruje ekran powitalny z informacjami pochodzącymi z pliku manifestu, tak jak na tym schemacie.

PWA na ekranie powitalnym Androida z różnymi wartościami z pliku manifestu.

Safari na iOS i iPadOS nie używa natomiast pliku manifestu aplikacji internetowej do generowania ekranów powitalnych. Zamiast tego wykorzystują obraz, do którego prowadzi zastrzeżony element <link>, podobny do sposobu obsługi ikon. Więcej informacji znajdziesz w rozdziale Ulepszenia.

Pola rozszerzone

Następny zestaw pól zawiera dodatkowe informacje o Twojej aplikacji PWA. Wszystkie są opcjonalne.

lang
Tag języka określający główny język wartości w pliku manifestu, np. en dla języka angielskiego, pt-BR dla brazylijskiego portugalskiego i in dla hindi.
dir
Kierunek wyświetlania pól manifestu z możliwością określenia kierunku (np. name, short_name i description). Prawidłowe wartości to auto, ltr (od lewej do prawej) i rtl (od prawej do lewej).
orientation
Wybrana orientacja aplikacji po zainstalowaniu. Gra może ustawić tę opcję tak, aby prosiła o orientację poziomą. Można użyć kilku wartości, ale jeśli są one podane, jest to zwykle jawna wartość portrait lub landscape.
.
.

Pola promocyjne

Czwarty zestaw pól umożliwia podanie informacji promocyjnych o PWA, na przykład w procesach instalacji, informacjach o produktach i wynikach wyszukiwania.

description
Wyjaśnienie działania PWA.
screenshots
Tablica obiektów zrzutów ekranu z obiektami src, type i sizes (podobnymi do obiektu icons), których celem jest prezentacja PWA. Nie ma żadnych ograniczeń dotyczących rozmiaru.
categories
Tablica kategorii, która powinna należeć do aplikacji PWA, powinna być używana jako wskazówki dotyczące wizytówek, opcjonalnie z listy znanych kategorii. Wartości te są zwykle zapisane małymi literami.
iarc_rating_id
Kod certyfikacji PWA International Age Rating Coalition (jeśli go masz). Służy do określania, dla jakich grup wiekowych aplikacja PWA jest odpowiednia.
.
.

Już dziś możesz zobaczyć, jak działają te pola promocyjne. Jeśli na przykład na Androidzie można zainstalować aplikację PWA, a w polach description i screenshots podasz wartości, okno instalacji zmieni się z prostego „Dodaj do ekranu głównego”. do bardziej rozbudowanego okna instalacji, podobnego do tego ze sklepu.

Na Androidzie interfejs instalacji będzie bardziej ładny, jeśli podasz wartości w polach promocyjnych, tak jak w następnym filmie.

Zobacz, jak działają te pola promocyjne:

Pola funkcji

Jest też wiele pól związanych z różnymi funkcjami, których może używać aplikacja PWA w obsługiwanych przeglądarkach. Są to np. pola shortcuts, share_target i display_overrides, które opisujemy w rozdziale dotyczącym funkcji. Dostępne są też pola, takie jak related_apps i prefer_related_apps (więcej informacji znajdziesz w rozdziale o wykrywaniu), które umożliwiają połączenie PWA z zainstalowanymi aplikacjami, często ze sklepu z aplikacjami.

W przyszłości może pojawić się wiele nowych pól, w czasie gdy przeglądarki dodadzą więcej możliwości do progresywnych aplikacji internetowych.

Zasoby