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, ikona i kolor motywu aplikacji, zaawansowane ustawienia, takie jak orientacja i skróty aplikacji, oraz metadane katalogu, np. zrzuty ekranu.

Każda PWA powinna zawierać jeden plik manifestu na aplikację, który jest zwykle hostowany w folderze głównym i połączony ze wszystkimi stronami HTML, z których można instalować PWA. 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ą ciągu znaków:

app.webmanifest:

{
   "name": "My First Application"
}

Utworzenie pliku nie wystarczy, ponieważ przeglądarka musi też wiedzieć, że istnieje.

Łą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. Jest to podobne 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 sprawdzić, czy manifest jest prawidłowo skonfigurowany, możesz użyć narzędzia Inspektor w Firefoxie i Narzędzi deweloperskich w każdej przeglądarce opartej na Chromium.

W przypadku przeglądarek Chromium

W Narzędziach deweloperskich

  1. W panelu po lewej stronie w sekcji Aplikacja kliknij Plik manifestu.
  2. Sprawdź pola pliku manifestu po jego przeanalizowaniu przez przeglądarkę.

Firefox

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

Projektowanie interfejsu PWA

Po połączeniu PWA z manifesczami możesz wypełnić pozostałe pola, aby zdefiniować sposób wyświetlania aplikacji użytkownikom.

Pola podstawowe

Pierwszy zestaw pól zawiera podstawowe informacje o Twojej aplikacji PWA. Są one używane do tworzenia ikony i okna zainstalowanej aplikacji PWA oraz określania sposobu jej uruchamiania. Są to:

name
Pełna nazwa 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 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 ikony z polami src, type, sizes i opcjonalnie purpose, które opisują, które obrazy powinny reprezentować PWA.
start_url
Adres URL, który powinien być ładowany w aplikacji internetowej, gdy użytkownik uruchomi ją z zainstalowanej ikony. Zalecamy użycie ścieżki bezwzględnej, więc jeśli strona główna PWA jest katalogiem głównym witryny, możesz ustawić wartość „/”, aby otwierała się ona po uruchomieniu aplikacji. Jeśli nie podasz adresu URL strony startowej, przeglądarka może użyć adresu URL, z którego zainstalowano PWA. Może to być link do szczegółów produktu zamiast 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 poświęconym projektowaniu aplikacji. Większość przypadków użycia implementuje standalone.
id
Ciąg znaków, który jednoznacznie identyfikuje tę PWA w stosunku do innych aplikacji, które mogą być hostowane w tym samym źródle. Jeśli nie zostanie skonfigurowany, zastępczo zostanie użyta wartość start_url. Pamiętaj, że jeśli w przyszłości zmienisz start_url (np. zmieniając wartość ciągu zapytania), możesz pozbawić przeglądarkę możliwości wykrycia, że PWA jest już zainstalowana.

Ikony

Ikona aplikacji PWA reprezentuje jej wizualną tożsamość na urządzeniach użytkowników po zainstalowaniu, dlatego ważne jest, aby zdefiniować co najmniej jedną. Właściwość icons to zbiór obiektów ikony, więc możesz zdefiniować kilka ikon w różnych formatach, aby zapewnić użytkownikom jak najlepszą jakość. Każda przeglądarka wybierze jedną lub więcej ikon na podstawie swoich potrzeb i systemu operacyjnego, na którym jest zainstalowana. Ikony te będą odpowiadać wymaganiom.

Jeśli musisz wybrać tylko jeden rozmiar ikony, powinien on wynosić 512 x 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. Na innych platformach ikona zostanie wygenerowana automatycznie, np. na podstawie zrzutu ekranu z aplikacji PWA lub za pomocą 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 na Androidzie 12 różni producenci i ustawienia mogą zmienić kształt ikon z okręgów na kwadraty lub na kwadraty o zaokrąglonych rogach. Aby obsługiwać takie adaptacyjne ikony, możesz podać ikonę z możliwością maskowania, korzystając z pola purpose.

W tym celu prześlij kwadratowy plik obrazu, którego główna ikona znajduje się w „bezpiecznym obszarze” – kółku wyśrodkowanym w ikonie o promieniu równym 40% szerokości ikony. (patrz obraz 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ą zamaskowania, renderowanej w kilku 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.

Ten obraz można użyć, dodając więcej marginesu.

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

Ikony z maskowaniem powinny mieć wymiary co najmniej 512 x 512. Po utworzeniu profilu możesz dodać go do kolekcji icons, aby ulepszyć działanie 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, którą można zamaskować, nie wyświetla się dobrze, możesz poprawić jej wygląd, dodając więcej marginesu. Maskable.app to bezpłatne narzędzie online do testowania i tworzenia wersji ikony z możliwością zamaskowania.

Kolejny zestaw pól, które należy uwzględnić, to pola, które poprawią wrażenia użytkownika, mimo że nie są wymagane do zainstalowania aplikacji.

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że zostać zastąpiony przez element HTML theme-color <meta>.
background_color
Kolor zastępczy wyświetlany na tle aplikacji przed załadowaniem jej arkusza stylów. Safari na iOS i iPadOS oraz większość przeglądarek komputerowych obecnie ignoruje to pole.
scope
Zmienia zakres nawigacji w PWA, umożliwiając określenie, co ma się wyświetlać w oknie zainstalowanej aplikacji, a co nie. Jeśli np. utworzysz link do strony spoza zakresu, zostanie ona wyświetlona w przeglądarce w aplikacji, a nie w oknie PWA. Nie zmieni to jednak zakresu działania Twojego serwisu.

Następny obraz pokazuje, jak pole theme_color jest używane do paska tytułu na komputerze po zainstalowaniu PWA.

Ta sama 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 PWA jest renderowany obraz statyczny, aby użytkownik otrzymał natychmiastową informację zwrotną.

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 pliku manifestu aplikacji internetowej do generowania ekranów powitalnych. Zamiast tego używają obrazu powiązanego z elementem <link>, który jest zastrzeżony, podobnie jak w przypadku ikon. Więcej informacji znajdziesz w rozdziale poświęconym ulepszaniu.

Pola rozszerzone

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

lang
Tag języka określający język główny wartości pliku manifestu, np. en dla języka angielskiego, pt-BR dla języka portugalskiego (Brazylia) lub in dla języka 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ą. Akceptowane są różne wartości, ale jeśli są one uwzględnione, to zwykle są to wartości portrait lub landscape.

Pola promocyjne

Czwarty zestaw pól umożliwia podanie informacji promocyjnych o PWA, np. w procesach instalacji, w informacjach i w wynikach wyszukiwania.

description
Wyjaśnienie działania PWA.
screenshots
Tablica obiektów zrzutu ekranu z elementami src, type i sizes (podobnymi do obiektu icons), które mają na celu zaprezentowanie PWA. Nie ma ograniczeń rozmiaru.
categories
Tablica kategorii, do których należy PWA, aby służyć jako wskazówki dla list, opcjonalnie z listy znanych kategorii. Te wartości są zwykle pisane małymi literami.
iarc_rating_id
Kod certyfikacji PWA International Age Rating Coalition (jeśli go masz). Ma ona określać, dla których grup wiekowych jest odpowiednia Twoja PWA.

Te pola promocyjne możesz już dziś zobaczyć w działaniu. Na przykład na Androidzie, jeśli PWA jest instalowalna i uwzględnisz wartości w co najmniej polach description i screenshots, w oknie instalacji zamiast prostego paska informacji „Dodaj na ekran główny” pojawi się bardziej rozbudowane okno instalacji podobne do tego ze sklepu z aplikacjami.

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ż kilka pól związanych z różnymi funkcjami, których Twoja aplikacja PWA może używać w obsługiwanych przeglądarkach, np. pól shortcuts, share_target i display_override, o których piszemy w rozdziale o funkcjach. 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, ponieważ przeglądarki będą dodawać nowe funkcje do progresywnych aplikacji internetowych.

Zasoby