W tym poście zajmiemy się pisaniem specjalnego pliku: manifest.json. Jeśli tworzycie swoje PWA, to jest to punkt obowiązkowy na drodze do stworzenia pełnej, możliwej do zainstalowania aplikacji. Zapraszam do czytania!
Definicja Web App Manifest i wsparcie
Web App Manifest to prosty plik JSON, który zawiera wszystkie najważniejsze informacje o Progressive Web App (jeśli nie wiecie, co to jest PWA, w tym artykule przybliżam to pojęcie: PWA – Wprowadzenie). Istnienie tego pliku i powiązanie go z naszą aplikacją jest jednym z wymagań, aby przeglądarka potraktowała ją jako możliwą do zainstalowania.
JSON (JavaScript Object Notation) to prosty format wymiany danych. Choć oparty o Javascript, jest używany powszechnie niezależnie od języka programowania. Ten format świetnie nadaje się m.in. do przekazywania informacji pomiędzy stronami/aplikacjami. Jeśli chcecie dowiedzieć się więcej o tym, zapraszam do odwiedzenia tej strony ze szczegółowym wyjaśnieniem i schematami struktury samego zapisu: Introducing JSON (na stronie można zmienić język na polski).
Na czas pisania tego posta (21.07.2019) strona caniuse.com informuje, że ten element jest obsługiwany globalnie w przeglądarkach 82% użytkowników, natomiast w Polsce: 90%. Wsparcie dla Web App Manifest z początku było głównie sprawą przeglądarek mobilnych, jednak Google już dawno zadbał o to, aby w Chrome na PC także dało się z tego skorzystać. Przez wzrastającą popularność PWA, inne przeglądarki także idą w kierunku lepszego wsparcia, dlatego możemy się spodziewać, że niedługo wskaźniki będą wyższe.
Praktyczny przykład
Aby stworzyć Web App Manifest, powinniśmy utworzyć nowy plik tekstowy. Choć specyfikacja W3C podpowiada, że rozszerzenie tego pliku powinno być *.webmanifest, tak przeglądarki wspierają także *.json, dlatego możemy wybrać którykolwiek z tych dwóch. Tym samym, w tej samej specyfikacji możemy także znaleźć zapis na temat tego, że typ MIME przeznaczony dla tego pliku to "application/manifest+json".
Przejdźmy jednak do praktyki i spójrzmy na przykładową treść pliku manifest.json/manifest.webmanifest:
{
"name": "Donate App",
"description": "This app helps you donate to worthy causes.",
"icons": [{
"src": "images/icon.png",
"sizes": "192x192"
}]
}Źródło: Specyfikacja W3C
Powyższy przykład zawiera jedynie najważniejsze informacje o naszej aplikacji: jej nazwę, opis oraz wskazanie na ikonę. Nazwa może być wprowadzona w dwóch wariantach, "name" oraz "short_name". Najlepiej jest umieścić oba, ponieważ mogą być różnie wyświetlone, w zależności od miejsca (np. na ekranie głównym pod ikoną lepiej jest, gdy wyświetla krótką nazwę aplikacji). Jeśli brakuje nazw, przeglądarka może wyciągnąć nazwę z jakiegoś innego elementu lub wyświetlić domyślny tekst.
Następnie mamy "description", który zawiera krótki opis działania aplikacji. Z reguły opis ten nie jest nigdzie wyświetlany, ale zaczynają pojawiać się coraz większe możliwości, np. sklepy z PWA, które używają tych opisów na podstronach aplikacji.
W przypadku "icons" mamy sprawę bardziej skomplikowaną. Ta właściwość zawiera tablicę obiektów, gdzie każdy z nich reprezentuje ikonę konkretnego rozmiaru czy formatu. Dzięki temu przeglądarka może wybrać taką ikonę, która najbardziej odpowiada danemu urządzeniu czy systemowi, lub po prostu miejscu, w którym ikona ma się wyświetlać.
Pozostałe właściwości
Właściwość "start_url" wskazuje adres strony, która wyświetli się użytkownikowi po otworzeniu aplikacji. Należy pamiętać, że URL w tym miejscu jest relatywny dla pliku manifest. Specyfikacja też zwraca uwagę na to, że użytkownik lub przeglądarka mogą być w stanie zignorować lub zmienić tę wartość po zainstalowaniu aplikacji.
A teraz trochę o kolorach, mamy tutaj dostępne dwa elementy: "background_color" i "theme_color". Ten pierwszy nadaje kolor tła przy "splash screenie", który wyświetla się przy starcie aplikacji na telefonie (na cały splash screen składa się tło, ikona aplikacji oraz jej nazwa). Druga opcja pozwala nam na spersonalizowanie głównego koloru naszej aplikacji. Kolor ten, w przypadku urządzeń mobilnych, będzie otaczał kartę naszej aplikacji w menedżerze zadań. Na komputerze z kolei będzie się wyświetlać w tle paska tytułu.
Dodatkiem, o którym dobrze wiedzieć, jest tag meta o nazwie "theme-color". Dzięki niemu nadamy kolor naszej stronie, jeszcze zanim użytkownik ją zainstaluje na swoim ekranie głównym. Wraz z tym elementem, pasek przeglądarki mobilnej zmieni swój kolor na ten, który mu nadaliśmy. Wystarczy w tagu <head> naszej strony dodać to:
<meta name="theme-color" content="#011627">
Właściwość "display" pozwala nam zadecydować, w jakim trybie nasza aplikacja się wyświetli. Tutaj mamy do wyboru cztery wartości: "fullscreen", "standalone", "minimal-ui" oraz "browser". Dzięki "fullscreen" wyświetlimy aplikację na pełnym ekranie, bez jakichkolwiek elementów, czy paska powiadomień. Przy "standalone" pojawi nam się ten pasek tak jak przy zwykłej aplikacji natywnej. "Minimal-ui" pokaże nam podstawowe elementy przeglądarki, co może być przydatne, jeśli nie uwzględniliśmy odpowiedniej nawigacji w naszej aplikacji. "Browser" z kolei jest zwyczajnym wyświetleniem strony w przeglądarce – działa więc podobnie jak zwyczajny skrót do strony internetowej. Wygląd każdej z tych wartości możecie zobaczyć na obrazku poniżej.
Dzięki "orientation" wskażemy, w jakiej pozycji chcemy naszą aplikację wyświetlić. Czasem, np. w przypadku gier, moglibyśmy chcieć, aby aplikacja od razu pojawiała się na ekranie poziomo, w tym celu przypiszemy temu elementowi wartość "landscape". Jeśli jednak chcemy wymusić widok pionowy, użyjemy "portrait".
Element "scope" wyznacza zasięg nawigacji wewnątrz aplikacji. Jeśli użytkownik za pomocą linku opuści wyznaczony zakres adresu, strona otworzy mu się poza aplikacją, w przeglądarce internetowej. Według tego, co pisze społeczność na Githubie, element ten wyznacza także adresy, z których mogą być pobrane zasoby. Generalnie ten fragment dokumentacji jest na obecnym etapie niejasny i nie ma podanych przykładów użycia. Developerzy z Google pokazali jednak w swoim przykładzie wartość "/" dla "scope".
Właściwości dodatkowe dla marketów
Wcześniej, przy nazwach i opisie aplikacji, wspomniałem o czymś takim jak "sklepy z PWA". Są to odpowiedniki Google Play czy Apple AppStore (na których swoją drogą też można zamieścić PWA), tyle że tylko dla aplikacji internetowych. Jednym z przykładów takiego sklepu jest Appscope. Co prawda umieszczanie aplikacji w tego typu miejscach to temat na osobny post, ale i tutaj możemy zwrócić uwagę na kilka elementów w naszym manifest.json, które mają zastosowanie właśnie tam.
Poza wspomnianymi tytułami i opisem aplikacji, mamy też opcjonalne "categories" oraz "screenshots", które pozwoli nam na lepszą prezentację naszego PWA na rynku. Z kategoriami to jest tak, że nie ma ścisłej listy wartości, której powinniśmy się trzymać. W3C zachęca nas jednak, abyśmy skorzystali z przygotowanej przez społeczność listy, która zawiera najczęściej używane kategorie. A można ją znaleźć tutaj: https://github.com/w3c/manifest/wiki/Categories
Kategorie są podpowiedzią dla sklepów, aby wiedziały, w którym miejscu umieścić naszą aplikację. Z tego też powodu dobrze jest zapoznać się z kategoriami, które są dostępne właśnie tam.
"Screenshots", jak nazwa wskazuje, są tablicą linków do obrazów, które pokazują wygląd i działanie PWA. I wygląda to tak samo, jak w przypadku zwykłych aplikacji w Google Play czy AppStore.
Opcje językowe
Możemy przypisać naszemu plikowi dwie właściwości językowe:
W "lang" zapisujemy język (w formie zgodnej z IANA Language Subtag Registry) manifestu. Tak, manifestu. Dokładniej jego konkretnych właściwości, czyli tytułu, krótkiego tytułu i opisu. Zwracam na to szczególną uwagę, ponieważ w wielu miejscach pojawia się stwierdzenie, że to dotyczy języka aplikacji – a jest to nieprawda.
W "dir" natomiast wybieramy kierunek tekstu, ponownie, tylko dla wymienionych wyżej wartości manifestu. Do wyboru w tym przypadku mamy "ltr" (left-to-right), "rtl" (right-to-left) oraz "auto". W większości przypadków jednak nie musicie się tym absolutnie przejmować.
Plik manifest.json gotowy. Co dalej?
Pomimo zrobienia i uzupełnienia informacjami pliku, przeglądarka wciąż nie wie, gdzie ten plik może znaleźć. Dlatego musimy zrobić jeszcze jedną rzecz: powiadomić ją o tym! Jedyne, co musimy zrobić, to dodać jeden prosty tag HTML do <head> w naszym dokumencie:
<link rel="manifest" href="manifest.json" />Jak sprawdzić poprawność manifest.json?
Jeśli nie jesteśmy pewni, czy nasze ikony zostały odpowiednio zinterpretowane przez przeglądarkę, lub czy nie wprowadziliśmy źle którejś z wartości, możemy sprawdzić poprawność tego dokumentu. W tym celu, w przeglądarce Google Chrome, uruchamiamy narzędzia developerskie (F12) i przechodzimy do zakładki "Application". Po wybraniu z lewej strony na liście "Manifest" zobaczymy w głównym panelu informacje, które przeglądarka znalazła (o ile w ogóle) w naszym manifest.json. Tak będzie to wyglądać w dev toolsach:
Bonus: mój plik manifest.json
Pod koniec postanowiłem, że zostawię Wam skończony plik manifestu, jako przykład użycia różnych elementów. Jest on bardziej rozbudowany niż to, co mamy zaprezentowane w specyfikacji. Sam plik pochodzi z mojego portalu dla polskich rysowników komiksów (w wolnej chwili możecie tam zajrzeć): Inku
{
"name": "Inku – komiksy, manga",
"short_name": "Inku",
"description": "Aplikacja portalu Inku – dla polskich rysowników komiksów",
"lang": "pl",
"theme_color": "#011627",
"background_color": "#011627",
"display": "standalone",
"orientation": "portrait",
"scope": "/",
"start_url": "index.php",
"icons": [
{
"src": "/icon/android-chrome-36x36.png",
"sizes": "36x36",
"type": "image/png"
},
{
"src": "/icon/android-chrome-48x48.png",
"sizes": "48x48",
"type": "image/png"
},
{
"src": "/icon/android-chrome-72x72.png",
"sizes": "72x72",
"type": "image/png"
},
{
"src": "/icon/android-chrome-96x96.png",
"sizes": "96x96",
"type": "image/png"
},
{
"src": "/icon/android-chrome-144x144.png",
"sizes": "144x144",
"type": "image/png"
},
{
"src": "/icon/android-chrome-192x192.png",
"sizes": "192x192",
"type": "image/png"
},
{
"src": "/icon/android-chrome-256x256.png",
"sizes": "256x256",
"type": "image/png"
},
{
"src": "/icon/android-chrome-384x384.png",
"sizes": "384x384",
"type": "image/png"
},
{
"src": "/icon/android-chrome-512x512.png",
"sizes": "512x512",
"type": "image/png"
}
]
}Bonus: narzędzia pomagające przy tworzeniu manifest.json
Ha, to jeszcze nie koniec! Od czasu, gdy tylko pojawiła się taka forma "definiowania" swojej aplikacji, zaraz powstały narzędzia, które pozwalają uprościć proces tworzenia takiego pliku, tak samo, jak i ikon. Choć osobiście uważam, że nie są one aż tak niezbędne, ponieważ napisanie tego ręcznie nie jest żadnym problemem, to mogą być małą pomocą dla tych, co dopiero zaczynają. Oto dwa przykłady znalezionych "generatorów":
https://app-manifest.firebaseapp.com/
– mamy tutaj prosty formularz, a także generator ikon: dzięki niemu możemy z jednej ikony o dużej rozdzielczości od razu przygotować cały zestaw ikon w różnych rozmiarach.
https://tomitm.github.io/appmanifest/
– tu z kolei brakuje takiego generatora, ale sam formularz jest bardziej rozbudowany, wraz z podpowiedziami poszczególnych właściwości.
Nowość! PWA Shortcuts
Od pewnego czasu możliwości PWA, w tym samego pliku manifest, zostały rozszerzone. Używając dodatkowych parametrów w naszym pliku możemy skorzystać ze skrótów z systemu operacyjnego dla swojej aplikacji. O tym, jak je zdefiniować i jak najlepiej je wykorzystać, przeczytacie w tym poście na moim blogu: PWA Shortcuts – jak utworzyć skróty w swojej web aplikacji
Podsumowanie
Gratulacje! W tym poście dowiedzieliście się wszystkiego, co powinniście, na temat Web App Manifest. Dzięki temu plikowi spełnicie jedno z trzech wymagań do stworzenia PWA możliwego do zainstalowania.
Darmowy ebook o PWAJeśli interesuje Cię temat PWA i chciałbyś dowiedzieć się o tym więcej, zapraszam do zapoznania się z moim ebookiem zawierającym najważniejsze informacje:
"Basics of PWA" eBook
2020-02-13 15:07:09
Fajny wpis