Muchos navegadores te permiten habilitar y promocionar la instalación de tu app web progresiva (AWP) directamente en su interfaz de usuario. La instalación (antes conocida como Agregar a la pantalla principal) permite a los usuarios instalar la AWP en su dispositivo móvil o de escritorio. Cuando instalas una AWP, se agrega al selector del usuario para que pueda ejecutarse como cualquier otra app instalada.
Además de la experiencia de instalación proporcionada por el navegador, puedes proporcionar tu propio flujo de instalación personalizado directamente dentro de tu app.
Cuando pienses en promocionar la instalación, ten en cuenta la forma en que los usuarios suelen usar tu AWP. Por ejemplo, si hay un conjunto de usuarios que usan la AWP varias veces en una semana, esos usuarios podrían beneficiarse de la comodidad adicional de iniciar la app desde la pantalla principal de un teléfono o desde el menú Inicio en el sistema operativo de una computadora de escritorio. Algunas aplicaciones de productividad y entretenimiento también se benefician del espacio adicional de pantalla que se crea cuando se quitan las barras de herramientas del navegador de la ventana en los modos standalone
o minimal-ui
instalados.
Requisitos previos
Antes de comenzar, asegúrate de que tu AWP cumpla con los requisitos de instalación, que suelen incluir un manifiesto de app web.
Promover la instalación
Para mostrar que tu app web progresiva se puede instalar y proporcionar un flujo de instalación personalizado desde la app, haz lo siguiente:
- Escucha el evento
beforeinstallprompt
. - Guarda el evento
beforeinstallprompt
para que pueda activar el flujo de instalación más adelante. - Informa al usuario que tu AWP se puede instalar y proporciona un botón o algún otro elemento para iniciar el flujo de instalación desde la app.
Escucha el evento beforeinstallprompt
Si la app web progresiva cumple con los criterios de instalación obligatorios, el navegador activa un evento beforeinstallprompt
. Guarda una referencia al evento y actualiza la interfaz de usuario para indicar que el usuario puede instalar tu AWP.
// 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.`);
});
Flujo de instalación en la app
Para proporcionar la instalación desde la app, proporciona un botón o algún otro elemento de la interfaz en el que el usuario pueda hacer clic o presionar para instalar tu app. Cuando se haga clic en el elemento o lo presiones, llama a prompt()
en el evento beforeinstallprompt
guardado (almacenado en la variable deferredPrompt
). Le muestra al usuario un diálogo de instalación modal en el que se le pide que confirme que desea instalar tu AWP.
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 propiedad userChoice
es una promesa que se resuelve con la elección del usuario.
Solo puedes llamar a prompt()
en el evento diferido una vez. Si el usuario lo descarta, deberás esperar hasta que se vuelva a activar el evento beforeinstallprompt
, por lo general, inmediatamente después de que se resuelva la propiedad userChoice
.
Detecta si la AWP se instaló correctamente
Puedes usar la propiedad userChoice
para determinar si el usuario instaló tu app desde tu interfaz de usuario. Sin embargo, si el usuario instala la AWP desde la barra de direcciones o desde otro componente del navegador, userChoice
no ayudará.
En su lugar, debes escuchar el evento appinstalled
, que se activa cada vez que se instala la AWP, independientemente del mecanismo que se use para instalarla.
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');
});
Detecta cómo se inició la AWP
La consulta de medios display-mode
de CSS indica la forma en que se inició la AWP, ya sea en una pestaña del navegador o como una AWP instalada. Esto permite aplicar diferentes estilos según cómo se inició la app. Por ejemplo, puedes configurarlo para que siempre oculte el botón de instalación y proporcione un botón Atrás cuando se inicie como una AWP instalada.
Realiza un seguimiento del lanzamiento de la AWP
Para realizar un seguimiento de cómo los usuarios inician tu AWP, usa matchMedia()
para probar la consulta de medios display-mode
. Safari en iOS aún no admite esta función, por lo que debes verificar navigator.standalone
, que muestra un valor booleano que indica si el navegador se está ejecutando en modo independiente.
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';
}
Realiza un seguimiento de los cambios en el modo de visualización
Para realizar un seguimiento si el usuario cambia entre standalone
y browser tab
, detecta los cambios en la consulta de medios 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);
});
Cómo actualizar la IU en función del modo de visualización actual
Para aplicar un color de fondo diferente a una AWP cuando se inicia como una AWP instalada, usa CSS condicional:
@media all and (display-mode: standalone) {
body {
background-color: yellow;
}
}
Cómo actualizar el ícono y el nombre de la app
¿Qué pasa si necesitas actualizar el nombre de la app o proporcionar íconos nuevos? Consulta Cómo Chrome maneja las actualizaciones del manifiesto de la app web para ver cuándo y cómo se reflejan esos cambios en Chrome.