Come offrire un'esperienza di installazione in-app personalizzata

Molti browser ti consentono di attivare e promuovere l'installazione della tua app web progressiva (PWA) direttamente nell'interfaccia utente della PWA. L'installazione (talvolta nota anche come Aggiungi alla schermata Home) consente agli utenti di installare facilmente la PWA sui propri dispositivi mobili o desktop. Se installi una PWA, questa viene aggiunta all'Avvio app di un utente, consentendone l'esecuzione come qualsiasi altra app installata.

Oltre all'esperienza di installazione fornita dal browser, è possibile fornire un flusso di installazione personalizzato direttamente all'interno dell'app.

Pulsante Installa app fornito nella PWA Spotify
Pulsante "Installa app" fornito nella PWA di Spotify

Per decidere se promuovere l'installazione, è meglio pensare a come gli utenti utilizzano in genere la tua PWA. Ad esempio, se diversi utenti utilizzano la PWA più volte in una settimana, potrebbero trarre vantaggio dalla comodità di avviare l'app dalla schermata Home di un telefono o dal menu Start in un sistema operativo desktop. Anche alcune applicazioni di produttività e intrattenimento traggono vantaggio dallo spazio aggiuntivo sullo schermo creato rimuovendo le barre degli strumenti del browser dalla finestra nelle modalità standalone o minimal-ui installate.

Prerequisiti

Prima di iniziare, assicurati che la PWA soddisfi i requisiti di installabilità, che in genere includono la presenza di un manifest dell'app web.

Promuovi l'installazione

Per indicare che la tua app web progressiva è installabile e per fornire un flusso di installazione in-app personalizzato:

  1. Ascolta l'evento beforeinstallprompt.
  2. Salva l'evento beforeinstallprompt per utilizzarlo per attivare il flusso di installazione in un secondo momento.
  3. Avvisa l'utente che la tua PWA è installabile e fornisci un pulsante o un altro elemento per avviare il flusso di installazione in-app.

Ascolta l'evento beforeinstallprompt

Se la tua app web progressiva soddisfa i criteri di installazione richiesti, il browser attiva un evento beforeinstallprompt. Salva un riferimento all'evento e aggiorna l'interfaccia utente per indicare che l'utente può installare la PWA.

// 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.`);
});

Flusso di installazione in-app

Per fornire l'installazione in-app, fornisci un pulsante o un altro elemento di interfaccia su cui l'utente possa fare clic per installare la tua app. Dopo aver fatto clic sull'elemento, chiama prompt() per l'evento beforeinstallprompt salvato (memorizzato nella variabile deferredPrompt). Mostra all'utente una finestra di dialogo di installazione modale in cui viene chiesto di confermare l'installazione della 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;
});

La proprietà userChoice è una promessa che si risolve con la scelta dell'utente. Puoi chiamare prompt() solo una volta nell'evento differito. Se l'utente lo ignora, devi attendere fino a quando l'evento beforeinstallprompt viene attivato di nuovo, in genere subito dopo la risoluzione della proprietà userChoice.

Rileva l'installazione della PWA

Puoi utilizzare la proprietà userChoice per determinare se l'utente ha installato la tua app dall'interfaccia utente. Tuttavia, se l'utente installa la tua PWA dalla barra degli indirizzi o da un altro componente del browser, userChoice non ti aiuterà. Devi invece ascoltare l'evento appinstalled. Viene attivata ogni volta che viene installata la PWA, indipendentemente dal meccanismo utilizzato per installarla.

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');
});

Rilevare come è stata lanciata la PWA

La query multimediale display-mode CSS indica come è stata avviata la PWA, in una scheda del browser o come PWA installata. Ciò consente di applicare stili diversi a seconda di come è stata lanciata l'app. Ad esempio, nascondi sempre il pulsante di installazione e fornisci un pulsante Indietro quando viene avviato come PWA installata.

Monitorare il lancio della PWA

Per monitorare in che modo gli utenti avviano la tua PWA, utilizza matchMedia() per testare la query multimediale display-mode. Safari su iOS non supporta ancora questa funzionalità, quindi devi selezionare navigator.standalone, restituisce un valore booleano che indica se il browser è in esecuzione in modalità autonoma.

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';
}

Monitoraggio del cambio di modalità di visualizzazione

Per monitorare se l'utente cambia tra standalone e browser tab, ascolta le modifiche apportate alla query multimediale 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);
});

Aggiorna la UI in base alla modalità di visualizzazione corrente

Per applicare un colore di sfondo diverso a una PWA avviata come PWA installata, utilizza il CSS condizionale:

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

Aggiornare l'icona e il nome dell'app

E se devi aggiornare il nome dell'app o fornire nuove icone? Consulta l'articolo In che modo Chrome gestisce gli aggiornamenti del file manifest dell'app web per sapere quando e come queste modifiche vengono applicate in Chrome.