Jak zapewnić własny proces instalacji aplikacji

Wiele przeglądarek umożliwia włączanie i promowanie instalacji progresywnej aplikacji internetowej (PWA) bezpośrednio w interfejsie tej aplikacji. Instalacja (czasami nazywana dodawaniem do ekranu głównego) ułatwia użytkownikom instalowanie aplikacji PWA na urządzeniu mobilnym lub komputerze. Zainstalowanie aplikacji PWA powoduje dodanie jej do programu uruchamiającego, dzięki czemu może być uruchamiana tak samo jak każdą inną zainstalowaną aplikację.

Oprócz opcji korzystania z przeglądarki możesz też udostępnić własny, niestandardowy proces instalacji bezpośrednio z poziomu aplikacji.

W aplikacji Spotify PWA dostępny jest przycisk Zainstaluj aplikację
Przycisk „Zainstaluj aplikację” dostępny w aplikacji PWA Spotify

Podejmując decyzję o promowaniu instalacji, warto zastanowić się, jak użytkownicy zwykle korzystają z Twojej aplikacji PWA. Jeśli na przykład niektórzy użytkownicy używają Twojej aplikacji PWA wiele razy w tygodniu, mogą oni wygodniej uruchamiać ją z ekranu głównego telefonu lub z menu Start w systemie operacyjnym. Niektóre aplikacje zwiększające produktywność i rozrywkę mogą też wykorzystać dodatkowe miejsce na ekranie, które jest spowodowane usunięciem pasków narzędzi przeglądarki z okna w zainstalowanych trybach standalone lub minimal-ui.

Wymagania wstępne

Na początek upewnij się, że Twoja aplikacja PWA spełnia wymagania dotyczące możliwości zainstalowania, które zazwyczaj obejmują plik manifestu aplikacji internetowej.

Promuj instalację

Aby wskazać, że progresywna aplikacja internetowa jest możliwa do zainstalowania, i zapewnić niestandardowy proces instalacji w aplikacji:

  1. Posłuchaj zdarzenia beforeinstallprompt.
  2. Zapisz zdarzenie beforeinstallprompt, aby można było go użyć do późniejszego uruchomienia procesu instalacji.
  3. Poinformuj użytkownika, że Twoją aplikację PWA można zainstalować, i podaj przycisk lub inny element rozpoczynający instalację w aplikacji.

Posłuchaj zdarzenia beforeinstallprompt

Jeśli progresywna aplikacja internetowa spełnia wymagane kryteria instalacji, przeglądarka uruchamia zdarzenie beforeinstallprompt. Zapisz odniesienie do zdarzenia i zaktualizuj interfejs użytkownika tak, aby wskazać, że użytkownik może zainstalować Twoją progresywną aplikację internetową.

// Initialize deferredPrompt for use later to show browser install prompt.
let deferredPrompt;

window.addEventListener('beforeinstallprompt', (e) => {
  // Prevent the mini-infobar from appearing on mobile
  e.preventDefault();
  // Stash the event so it can be triggered later.
  deferredPrompt = e;
  // Update UI notify the user they can install the PWA
  showInstallPromotion();
  // Optionally, send analytics event that PWA install promo was shown.
  console.log(`'beforeinstallprompt' event was fired.`);
});

Proces instalacji w aplikacji

Aby zapewnić instalację w aplikacji, podaj przycisk lub inny element interfejsu, który użytkownik może kliknąć, by zainstalować aplikację. Po kliknięciu elementu wywołaj prompt() w zapisanym zdarzeniu beforeinstallprompt (przechowywanym w zmiennej deferredPrompt). Wyświetla użytkownikowi modalne okno instalacji z prośbą o potwierdzenie, że chce zainstalować Twoją aplikację PWA.

buttonInstall.addEventListener('click', async () => {
  // Hide the app provided install promotion
  hideInstallPromotion();
  // Show the install prompt
  deferredPrompt.prompt();
  // Wait for the user to respond to the prompt
  const { outcome } = await deferredPrompt.userChoice;
  // Optionally, send analytics event with outcome of user choice
  console.log(`User response to the install prompt: ${outcome}`);
  // We've used the prompt, and can't use it again, throw it away
  deferredPrompt = null;
});

Właściwość userChoice jest obietnicą satysfakcji z wyboru użytkownika. W odroczonym zdarzeniu możesz tylko raz wywołać metodę prompt(). Jeśli użytkownik ją odrzuci, musisz poczekać, aż zdarzenie beforeinstallprompt uruchomi się ponownie, zwykle bezpośrednio po rozwiązaniu właściwości userChoice.

Wykrywanie pomyślnej instalacji PWA

Możesz użyć właściwości userChoice, aby określić, czy użytkownik zainstalował aplikację z poziomu interfejsu. Jeśli jednak użytkownik zainstaluje Twoją aplikację PWA z paska adresu lub innego komponentu przeglądarki, userChoice nie pomoże. Zamiast tego zacznij nasłuchiwać zdarzenia appinstalled. Jest uruchamiana po każdym zainstalowaniu PWA niezależnie od mechanizmu używanego do jej zainstalowania.

window.addEventListener('appinstalled', () => {
  // Hide the app-provided install promotion
  hideInstallPromotion();
  // Clear the deferredPrompt so it can be garbage collected
  deferredPrompt = null;
  // Optionally, send analytics event to indicate successful install
  console.log('PWA was installed');
});

Wykrywanie sposobu uruchomienia PWA

Zapytanie o media display-mode w CSS wskazuje sposób uruchomienia PWA – na karcie przeglądarki lub jako zainstalowana aplikacja PWA. Dzięki temu można stosować różne style w zależności od tego, jak aplikacja została uruchomiona. Na przykład zawsze ukryj przycisk instalacji i udostępnij przycisk Wstecz w przypadku uruchomienia jako zainstalowanej aplikacji PWA.

Śledzenie uruchomienia PWA

Aby śledzić, jak użytkownicy uruchamiają Twoją progresywną aplikację internetową, użyj matchMedia() do przetestowania zapytania o media display-mode. Safari na iOS jeszcze nie obsługuje tej funkcji, więc musisz zaznaczyć pole navigator.standalone. Zwraca ona wartość logiczną wskazującą, czy przeglądarka działa w trybie samodzielnym.

function getPWADisplayMode() {
  const isStandalone = window.matchMedia('(display-mode: standalone)').matches;
  if (document.referrer.startsWith('android-app://')) {
    return 'twa';
  } else if (navigator.standalone || isStandalone) {
    return 'standalone';
  }
  return 'browser';
}

Śledzenie zmian trybu wyświetlania

Aby śledzić, czy użytkownik zmienia się między standalone a browser tab, nasłuchuj zmian w zapytaniu o media display-mode.

window.matchMedia('(display-mode: standalone)').addEventListener('change', (evt) => {
  let displayMode = 'browser';
  if (evt.matches) {
    displayMode = 'standalone';
  }
  // Log display mode change to analytics
  console.log('DISPLAY_MODE_CHANGED', displayMode);
});

Zaktualizuj interfejs zgodnie z bieżącym trybem wyświetlania

Aby zastosować inny kolor tła aplikacji PWA uruchomionej jako zainstalowana PWA, użyj warunkowego CSS:

@media all and (display-mode: standalone) {
  body {
    background-color: yellow;
  }
}

Zaktualizuj ikonę i nazwę aplikacji

Co zrobić, jeśli chcesz zmienić nazwę aplikacji lub dodać nowe ikony? Sprawdź, jak Chrome obsługuje aktualizacje pliku manifestu aplikacji internetowej, aby zobaczyć, kiedy i w jaki sposób są one odzwierciedlane w Chrome.