Jak zapewnić własny proces instalacji aplikacji

Wiele przeglądarek umożliwia włączanie i promowanie instalacji progresywnej aplikacji internetowej (PWA) bezpośrednio w ich interfejsie. Instalacja (czasami nazywana dodawaniem do ekranu głównego) pozwala użytkownikom zainstalować PWA na urządzeniu mobilnym lub komputerze. Zainstalowanie PWA powoduje dodanie jej do programu uruchamiającego, dzięki czemu może ona działać tak samo jak każda inna zainstalowana aplikacja.

Oprócz przeprowadzania instalacji przez przeglądarkę możesz też udostępnić własny, niestandardowy proces instalacji bezpośrednio w aplikacji.

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

Rozważając promowanie instalacji, zastanów się, jak użytkownicy zwykle korzystają z Twojej aplikacji PWA. Jeśli na przykład niektórzy użytkownicy korzystają z 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 aplikacje rozrywkowe mogą też korzystać z dodatkowego miejsca na ekranie, które usuwa pasek narzędzi przeglądarki 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 pokazać, że progresywną aplikację internetową można zainstalować, i zapewnić niestandardowy proces jej instalacji:

  1. Posłuchaj zdarzenia beforeinstallprompt.
  2. Zapisz zdarzenie beforeinstallprompt, aby mogło ono aktywować później proces 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 funkcję prompt() w zapisanym zdarzeniu beforeinstallprompt (zapisanego 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 należy nasłuchiwać zdarzenia appinstalled, które jest uruchamiane przy każdym zainstalowaniu aplikacji PWA, niezależnie od mechanizmu użytego 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 progresywna aplikacja internetowa. Dzięki temu można stosować różne style w zależności od tego, jak aplikacja została uruchomiona. Możesz na przykład skonfigurować go w taki sposób, aby przycisk instalacji był zawsze ukryty i udostępniał przycisk Wstecz przy uruchamianiu jako zainstalowaną aplikację 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 w iOS jeszcze nie obsługuje tej funkcji, więc zamiast niej zaznacz navigator.standalone, która zwraca 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.