Rejestracja modułu obsługi protokołu URL na potrzeby PWA

Umożliwiaj zainstalowanym progresywnym aplikacjom internetowym obsługę linków korzystających z określonego protokołu, aby zapewnić bardziej zintegrowane działanie.

Thomas Steiner

Informacje o schematach (czyli protokołach)

Identyfikator URI (Uniform Resource Identifier) to kompaktowy ciąg znaków, który identyfikuje zasób abstrakcyjny lub fizyczny. Każdy identyfikator URI zaczyna się od nazwy schematu, która odnosi się do specyfikacji przypisywania identyfikatorów w ramach tego schematu. Składnia URI to zdecentralizowany i rozszerzalny system nazewnictwa, w którym specyfikacja każdego schematu może dodatkowo ograniczać składnię i semantykę identyfikatorów używających tego schematu. Schematy są też nazywane protokołami. Oto kilka przykładów schematów.

tel:+1-816-555-1212
mailto:Jane.Doe@example.com
news:comp.infosystems.www.servers.unix
https://web.dev/

Termin URL (Uniform Resource Locator) odnosi się do podzbioru identyfikatorów URI, które oprócz identyfikowania zasobu umożliwiają jego lokalizowanie przez opisanie podstawowego mechanizmu dostępu (np. lokalizacji w sieci).

Informacje o metodzie registerProtocolHandler()

Metoda Navigator w bezpiecznym kontekście registerProtocolHandler() umożliwia witrynom rejestrowanie możliwości otwierania lub obsługi określonych schematów adresów URL. Dlatego witryny muszą wywoływać tę metodę w ten sposób: navigator.registerProtocolHandler(scheme, url). Te 2 parametry są zdefiniowane w ten sposób:

  • scheme: ciąg znaków zawierający protokół, który witryna chce obsługiwać.
  • url: ciąg znaków zawierający adres URL modułu obsługi. Ten adres URL musi zawierać zmienną %s jako symbol zastępczy, który zostanie zastąpiony przez adres URL z zastosowanym kodowaniem zmiany znaczenia.

Schemat musi być jednym ze schematów z listy dozwolonych (np. mailto, bitcoin lub magnet) albo zaczynać się od web+, po którym następuje co najmniej 1 mała litera ASCII po prefiksie web+, np. web+coffee.

Aby to wyjaśnić, podajemy konkretny przykład:

  1. Użytkownik odwiedza witrynę https://coffeeshop.example.com/, która wywołuje następujące polecenie: navigator.registerProtocolHandler('web+coffee', 'coffee?type=%s').
  2. Później, podczas odwiedzania witryny https://randomsite.example.com/, użytkownik klika link taki jak <a href="web+coffee:latte-macchiato">All about latte macchiato</a>.
  3. Powoduje to, że przeglądarka przechodzi do adresu URL https://coffeeshop.example.com/coffee?type=web%2Bcoffee%3A%2F%2Flatte-macchiato. Ciąg wyszukiwania zdekodowany z adresu URL ma postać ?type=web+coffee://latte-macchiato.

Na czym polega obsługa protokołów

Obecny mechanizm rejestracji modułu obsługi protokołu URL na potrzeby PWA polega na oferowaniu rejestracji modułu obsługi protokołu jako części instalacji PWA za pomocą jej pliku manifestu. Gdy użytkownik kliknie hiperlink z określonym schematem, np. mailto, bitcoin lub web+music, w przeglądarce lub aplikacji na konkretną platformę, zarejestrowana PWA otworzy się i otrzyma adres URL. Warto zauważyć, że zarówno proponowana rejestracja oparta na pliku manifestu, jak i tradycyjna metoda registerProtocolHandler() odgrywają w praktyce bardzo podobne role, a jednocześnie umożliwiają uzupełniające się wrażenia użytkownika:

  • Podobieństwa obejmują wymagania dotyczące listy schematów, które można zarejestrować, oraz nazwy i formatu parametrów itp.
  • Różnice w rejestracji opartej na pliku manifestu są subtelne, ale mogą być przydatne do poprawy komfortu użytkowników PWA. Na przykład rejestracja PWA oparta na pliku manifestu może nie wymagać dodatkowego działania użytkownika poza zainicjowaną przez niego instalacją PWA.

Przypadki użycia

  • W PWA do edycji tekstu użytkownik w dokumencie napotyka link do prezentacji, np. web+presentations://deck2378465. Gdy użytkownik kliknie link, PWA do prezentacji automatycznie otworzy się w odpowiednim zakresie i wyświetli prezentację.
  • W aplikacji do czatu na konkretną platformę użytkownik otrzymuje w wiadomości na czacie link do adresu URL magnet. Po kliknięciu linku uruchamia się zainstalowana PWA do torrentów i rozpoczyna się pobieranie.
  • Użytkownik ma zainstalowaną PWA do strumieniowego przesyłania muzyki. Gdy znajomy udostępni link do utworu, np. web+music://songid=1234&time=0:13 a użytkownik go kliknie, PWA do strumieniowego przesyłania muzyki automatycznie uruchomi się w osobnym oknie.

Jak korzystać z rejestracji modułu obsługi protokołu URL na potrzeby PWA

Interfejs API do rejestracji modułu obsługi protokołu URL jest wzorowany na metodzie navigator.registerProtocolHandler(). Tym razem informacje są przekazywane deklaratywnie za pomocą pliku manifestu aplikacji internetowej w nowej właściwości o nazwie "protocol_handlers", która przyjmuje tablicę obiektów z 2 wymaganymi kluczami "protocol" i "url". Poniższy fragment kodu pokazuje, jak zarejestrować protokoły web+tea i web+coffee. Wartości to ciągi znaków zawierające adres URL modułu obsługi z wymaganym symbolem zastępczym %s dla adresu URL z zastosowanym kodowaniem zmiany znaczenia.

{
  "protocol_handlers": [
    {
      "protocol": "web+tea",
      "url": "/tea?type=%s"
    },
    {
      "protocol": "web+coffee",
      "url": "/coffee?type=%s"
    }
  ]
}

Rejestrowanie się wielu aplikacji w tym samym protokole

Jeśli kilka aplikacji zarejestruje się jako moduły obsługi tego samego schematu, np. protokołu mailto, system operacyjny wyświetli użytkownikowi selektor i pozwoli mu wybrać, którego z zarejestrowanych modułów obsługi chce użyć.

Rejestrowanie się tej samej aplikacji w wielu protokołach

Ta sama aplikacja może zarejestrować się w wielu protokołach, jak widać w przykładowym kodzie.

Aktualizacje aplikacji i rejestracja modułu obsługi

Rejestracje modułów obsługi są synchronizowane z najnowszą wersją pliku manifestu dostarczoną przez aplikację. Istnieją 2 przypadki:

  • Aktualizacja, która dodaje nowe moduły obsługi, powoduje rejestrację modułu obsługi (niezależnie od instalacji aplikacji).
  • Aktualizacja, która usuwa moduły obsługi, powoduje wyrejestrowanie modułu obsługi (niezależnie od odinstalowania aplikacji).

Debugowanie modułu obsługi protokołu w Narzędziach deweloperskich

W panelu Aplikacja > Manifest otwórz sekcję Moduły obsługi protokołów. Tutaj możesz wyświetlić i przetestować wszystkie dostępne protokoły.

Moduły obsługi protokołów w okienku Manifest

Bezpieczeństwo

Ponieważ instalacja PWA wymaga bezpiecznego kontekstu, obsługa protokołów dziedziczy to ograniczenie. Lista zarejestrowanych modułów obsługi protokołów nie jest w żaden sposób udostępniana w internecie, więc nie można jej używać jako wektora fingerprintingu.

Próby nawigacji nieinicjowane przez użytkownika

Próby nawigacji, które nie są inicjowane przez użytkownika, ale są programowe, mogą nie otwierać aplikacji. Niestandardowy adres URL protokołu może być używany tylko w kontekstach przeglądania najwyższego poziomu, ale nie np. jako adres URL elementu iframe.

Lista dozwolonych protokołów

Podobnie jak w przypadku metody registerProtocolHandler() istnieje lista dozwolonych protokołów, które aplikacje mogą zarejestrować do obsługi.

Przy pierwszym uruchomieniu PWA z powodu wywołanego protokołu użytkownik zobaczy okno z prośbą o zgodę. W tym oknie wyświetli się nazwa aplikacji i jej źródło oraz pytanie, czy aplikacja może obsługiwać linki z protokołu. Jeśli użytkownik odrzuci okno z prośbą o zgodę, system operacyjny zignoruje zarejestrowany moduł obsługi protokołu. Aby wyrejestrować moduł obsługi protokołu, użytkownik musi odinstalować PWA, która go zarejestrowała. Przeglądarka wyrejestruje też moduł obsługi protokołu, jeśli użytkownik wybierze opcję „Zapamiętaj mój wybór” i kliknie „Zablokuj”.

Prześlij opinię

Zespół Chromium chce poznać Twoje wrażenia związane z rejestracją modułu obsługi protokołu URL na potrzeby PWA.

Przekaż nam opinię o projekcie interfejsu API

Czy coś w interfejsie API nie działa tak, jak oczekujesz? A może brakuje metod lub właściwości, których potrzebujesz do zrealizowania swojego pomysłu? Masz pytanie lub komentarz dotyczący modelu bezpieczeństwa? Zgłoś problem ze specyfikacją w odpowiednim repozytorium GitHub lub dodaj swoje uwagi do istniejącego problemu.

Zgłoś problem z implementacją

Czy udało Ci się znaleźć błąd w implementacji Chromium? A może implementacja różni się od specyfikacji? Zgłoś błąd na stronie new.crbug.com. Podaj jak najwięcej szczegółów, instrukcje odtworzenia i wpisz UI>Browser>WebAppInstalls w polu Komponenty.

Wyraź poparcie dla interfejsu API

Czy planujesz korzystać z rejestracji modułu obsługi protokołu URL na potrzeby PWA? Twoje publiczne poparcie pomaga zespołowi Chromium ustalać priorytety funkcji i pokazuje innym dostawcom przeglądarek, jak ważne jest ich wsparcie.

Podziel się swoimi planami na wątku WICG Discourse. Wyślij tweeta do @ChromiumDev z hasztagiem #ProtocolHandler i daj nam znać, gdzie i jak go używasz.

Podziękowania

Rejestracja modułu obsługi protokołu URL na potrzeby PWA została zaimplementowana i określona przez Fabio Rochę, Diego Gonzáleza, Connora Moody'ego i Samuela Tanga z zespołu Microsoft Edge. Ten dokument został sprawdzony przez Joe Medleya i Fabio Rochę.