Molti browser ti consentono di attivare e promuovere l'installazione della tua app web progressiva (PWA) direttamente nella sua interfaccia utente. L'installazione (a volte in precedenza indicata come Aggiungi alla schermata Home) consente agli utenti di installare la tua PWA sul proprio dispositivo mobile o computer. L'installazione di una PWA viene aggiunta ad Avvio app di un utente in modo che possa essere eseguita come qualsiasi altra app installata.
Oltre all'esperienza di installazione fornita dal browser, puoi fornire il tuo flusso di installazione personalizzato direttamente all'interno dell'app.
Quando decidi se promuovere l'installazione, tieni presente in che modo gli utenti solitamente utilizzano la tua PWA. Ad esempio, se esiste un insieme di utenti che utilizzano la tua PWA più volte alla settimana, questi utenti potrebbero trarre vantaggio dalla comodità aggiuntiva di avviare la tua app dalla schermata Home di uno smartphone o dal menu Start di un sistema operativo per computer. Alcune applicazioni per la produttività e l'intrattenimento traggono vantaggio anche dallo spazio aggiuntivo sullo schermo creato rimuovendo le barre degli strumenti del browser dalla finestra nelle modalità standalone
, minimal-ui
o window-control-overlay
installate.
Prerequisiti
Prima di iniziare, assicurati che la tua PWA soddisfi i requisiti di installabilità, che in genere includono la presenza di un manifest della web app.
Promuovi l'installazione
Per dimostrare che la tua app web progressiva è installabile e per fornire un flusso di installazione in-app personalizzato:
- Ascolta l'evento
beforeinstallprompt
. - Salva l'evento
beforeinstallprompt
in modo che possa attivare il flusso di installazione più tardi. - 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 l'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 tua 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 consentire l'installazione in-app, fornisci un pulsante o un altro elemento dell'interfaccia
su cui un utente può fare clic o toccare per installare l'app. Quando l'utente fa clic o
tocca l'elemento, richiama prompt()
sull'evento beforeinstallprompt
salvato (archiviato nella
variabile deferredPrompt
). Viene mostrata all'utente una finestra di dialogo di installazione modale che gli chiede di confermare di voler installare la tua 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()
nell'evento differito una sola volta. Se l'utente lo ignora, dovrai attendere che l'evento beforeinstallprompt
venga attivato di nuovo, in genere subito dopo la risoluzione della proprietà userChoice
.
Rileva quando la PWA è stata installata correttamente
Puoi utilizzare la proprietà userChoice
per determinare se l'utente ha installato
la tua app dalla tua interfaccia utente. Tuttavia, se l'utente installa la PWA
dalla barra degli indirizzi o da un altro componente del browser, userChoice
non ti aiuterà.
Dovresti invece ascoltare l'evento appinstalled
, che viene attivato ogni volta che la tua PWA viene installata, indipendentemente dal meccanismo utilizzato per l'installazione.
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');
});
Rileva come è stata avviata la PWA
La query sui media CSS display-mode
indica in che modo è stata avviata la PWA, in una scheda del browser o come PWA installata. In questo modo è possibile applicare stili diversi a seconda di come è stata lanciata l'app. Ad esempio, puoi configurarla in modo che nasconda sempre il pulsante Installa e fornisca un pulsante Indietro quando viene avviata come PWA installata.
Monitora come è stata lanciata la PWA
Per monitorare il modo in cui gli utenti avviano la tua PWA, utilizza matchMedia()
per testare la query media display-mode
.
function getPWADisplayMode() {
if (document.referrer.startsWith('android-app://'))
return 'twa';
if (window.matchMedia('(display-mode: browser)').matches)
return 'browser';
if (window.matchMedia('(display-mode: standalone)').matches || navigator.standalone)
return 'standalone';
if (window.matchMedia('(display-mode: minimal-ui)').matches)
return 'minimal-ui';
if (window.matchMedia('(display-mode: fullscreen)').matches)
return 'fullscreen';
if (window.matchMedia('(display-mode: window-controls-overlay)').matches)
return 'window-controls-overlay';
return 'unknown';
}
Monitoraggio dei cambiamenti della modalità di visualizzazione
Per monitorare se l'utente passa da browser
ad altre modalità di visualizzazione,
ascolta le modifiche apportate alla query multimediale display-mode
.
// Replace "standalone" with the display mode used in your manifest
window.matchMedia('(display-mode: standalone)').addEventListener('change', () => {
// Log display mode change to analytics
console.log('DISPLAY_MODE_CHANGED', getPWADisplayMode());
});
Aggiornare l'interfaccia utente in base alla modalità di visualizzazione corrente
Per applicare un colore di sfondo diverso per una PWA quando viene avviata come PWA installata, utilizza CSS condizionale:
@media all and (display-mode: standalone) {
body {
background-color: yellow;
}
}
Aggiornare l'icona e il nome dell'app
Cosa succede se devi aggiornare il nome dell'app o fornire nuove icone? Consulta In che modo Chrome gestisce gli aggiornamenti del manifest dell'app web per scoprire quando e come queste modifiche vengono applicate in Chrome.