Manifest aplikacji internetowej

Plik manifestu aplikacji internetowej to plik, który informuje przeglądarkę, jak mają wyglądać treści internetowe 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. Jego oficjalne rozszerzenie to .webmanifest, więc możesz nazwać plik manifestu na przykład 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.

Łączenie z plikiem manifestu

Aby poinformować przeglądarkę o manifeście aplikacji internetowej, musisz połączyć go z PWA za pomocą elementu HTML <link> i ustawić atrybut rel na manifest na wszystkich stronach HTML w PWA. 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 po jego przeanalizowaniu przez przeglądarkę.

Projektowanie aplikacji 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ę wraz z ikoną na ekranie głównym, w menu, na pasku aplikacji lub w menu uruchamiania systemu operacyjnego.
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. Nie przekraczaj 12 znaków, aby zminimalizować możliwość ucię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 ścieżkę bezwzględną, 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 została zainstalowana PWA. Może to być link do szczegółów produktu zamiast ekranu głównego.
display
Jedna z wartości fullscreen, standalone, minimal-ui lub browser, która określa, jak system operacyjny powinien wyświetlać okno aplikacji 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 jest skonfigurowany, jako wartość zastępcza będzie używany parametr start_url. Pamiętaj, że jeśli w przyszłości zmienisz start_url (np. zmieniając wartość ciągu zapytania), możesz uniemożliwić przeglądarce wykrycie, że PWA jest już zainstalowana.

Ikony

Ikona PWA to wizualna tożsamość aplikacji na urządzeniach użytkowników po jej zainstalowaniu, dlatego ważne jest zdefiniowanie co najmniej 1 ikony. 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 ikony lub ikony nie mają zalecanych rozmiarów, na niektórych platformach nie przejdziesz 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, np. 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 kół na kwadraty lub kwadraty z zaokrąglonymi rogami. 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 maskowanie ikon będą je maskować w razie potrzeby.

Bezpieczny obszar oznaczony jako okrąg o promieniu 40% w środku kwadratowej ikony

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

Jeśli na poniższym obrazie użyjesz ikony po lewej jako ikony z możliwością maskowania, uzyskasz słabe wyniki na urządzeniach, gdy zastosujesz maskę kształtu.

Ikona, która nie nadaje się do maskowania.

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

Ikona z większym wypełnieniem jest odpowiednia do 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.

Jeśli ikona służy do celów ogólnych i można ją zamaskować, w polu purpose możesz ustawić wartość "any maskable". Więcej informacji znajdziesz w dokumentacji manifestu aplikacji internetowej MND.

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, który czasami wpływa na sposób wyświetlania witryny przez system operacyjny (np. kolor okna i paska tytułu na komputerze lub 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, który ma być 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 aplikacji internetowej. 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.

Podczas definiowania kolorów w pliku manifestu (np. w elementach theme_color i background_color) należy używać nazw kolorów w CSS, takich jak salmon lub orange, kolorów RGB, takich jak #FF5500, lub funkcji kolorów bez przezroczystości, takich jak rgb() lub hsl(). Więcej informacji znajdziesz w rozdziale poświęconym projektowaniu aplikacji.

Wypróbuj

Ekrany powitalne

Na niektórych urządzeniach podczas wczytywania PWA renderowany jest obraz statyczny, aby użytkownik otrzymał natychmiastową informację zwrotną.

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

Gdy zainstalujesz na urządzeniu z Androidem PWA, wyświetli się ekran powitalny z informacjami z pliku manifestu, jak pokazano na diagramie poniżej.

PWA na ekranie powitalnym w Androidzie 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 ulepszeniom.

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, które obsługują kierunek (takich jak name, short_name i description). Dopuszczalne wartości to auto, ltr (od lewej do prawej) i rtl (od prawej do lewej).
orientation
Orientacja, w której aplikacja ma być wyświetlana po zainstalowaniu. Gra może ustawić tę opcję tak, aby wymagała orientacji poziomej. Akceptowane są różne wartości, ale jeśli są one uwzględnione, to zwykle jest to wartość 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, do czego służy aplikacja 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 certyfikatu PWA z International Age Rating Coalition (ARC), jeśli go masz. Służy do określania, 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 podasz wartości co najmniej w polach description i screenshots, w oknie instalacyjnym zamiast prostego paska informacji „Dodaj na ekran główny” pojawi się bardziej rozbudowane okno instalacji podobne do tego ze sklepu z aplikacjami.

Na Androidzie możesz uzyskać ładniejsze UI instalacji, jeśli podasz wartości w polach promocyjnych, jak widać w następnym filmie

Zobacz, jak działają te pola promocyjne:

Pola dotyczące możliwości

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. Istnieją też pola, takie jak related_apps i prefer_related_apps (więcej informacji znajdziesz w rozdziale poświęconym 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ć więcej funkcji do progresywnych aplikacji internetowych.

Zasoby