Cómo brindar tu propia experiencia de instalación en la app

Pete LePage

Muchos navegadores te permiten habilitar y promover la instalación de tu app web progresiva (AWP) directamente desde su interfaz de usuario. La instalación (en ocasiones, antes conocida como Agregar a la pantalla principal) permite a los usuarios instalar tu AWP en su dispositivo móvil o de escritorio. Cuando se instala una AWP, se agrega al selector del usuario para que se ejecute 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 en la app.

El botón "Install App" que se proporciona en la AWP de Spotify.

Cuando consideres si promocionar la instalación, ten en cuenta cómo suelen usar tu AWP los usuarios. Por ejemplo, si hay un conjunto de usuarios que usan tu AWP varias veces a la semana, es posible que se beneficien de la comodidad adicional de iniciar tu app desde la pantalla principal de un teléfono o desde el menú Inicio en un sistema operativo de escritorio. Algunas aplicaciones de productividad y entretenimiento también se benefician del espacio de pantalla adicional que se crea cuando se quitan las barras de herramientas del navegador de la ventana en los modos standalone, minimal-ui o window-control-overlay instalados.

Requisitos previos

Antes de comenzar, asegúrate de que tu AWP cumpla con los requisitos de instalabilidad, que suelen incluir tener un manifiesto de app web.

Cómo promover la instalación

Para mostrar que tu app web progresiva se puede instalar y proporcionar un flujo de instalación personalizado en la app, haz lo siguiente:

1. Escucha el evento beforeinstallprompt.
2. Guarda el evento beforeinstallprompt para que pueda activar el flujo de instalación más adelante.
3. Avísale al usuario que se puede instalar tu AWP y proporciona un botón o algún otro elemento para iniciar el flujo de instalación en la app.

Nota: El evento beforeinstallprompt y el evento appinstalled se movieron de la especificación del manifiesto de la app web a su propio incubador. El equipo de Chrome sigue comprometido a brindarles asistencia y no tiene planes de quitarla ni darla de baja. El equipo de DevRel de la Web de Google sigue recomendando su uso para proporcionar una experiencia de instalación personalizada.

Detecta el evento beforeinstallprompt

Si tu aplicación web progresiva cumple con los criterios de instalación necesarios, 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.`);
});

Nota: Existen muchos patrones diferentes que puedes usar para notificarle al usuario que se puede instalar tu app y proporcionar un flujo de instalación en la app. Estos pueden incluir un botón en el encabezado, un elemento en el menú de navegación o un elemento en tu feed de contenido.

Flujo de instalación en la app

Para proporcionar una instalación en la app, proporciona un botón o algún otro elemento de interfaz en el que el usuario pueda hacer clic o presionar para instalar tu app. Cuando se haga clic en el elemento o se lo presione, 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 solicita 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 la 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.

Pruébalo: Haz que un sitio se pueda instalar con el evento beforeinstallprompt.

Detecta cuándo se instaló correctamente la AWP

Puedes usar la propiedad userChoice para determinar si el usuario instaló tu app desde tu interfaz de usuario. Sin embargo, si el usuario instala tu 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 tu PWA, sin importar qué mecanismo se use para instalarlo.

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 cómo 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 haya iniciado 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.

Hacer un seguimiento de cómo se lanzó la AWP

Para hacer un seguimiento de cómo los usuarios inician tu AWP, usa matchMedia() para probar la consulta multimedia 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';
}

Realiza un seguimiento de los cambios en el modo de visualización

Para hacer un seguimiento de si el usuario cambia entre browser y otros modos de visualización, escucha los cambios en la consulta de contenido multimedia 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());
});

Actualiza la IU según el 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;
  }
}

Actualiza el ícono y el nombre de tu app

¿Qué sucede si necesitas actualizar el nombre de tu app o proporcionar íconos nuevos? Consulta Cómo Chrome controla las actualizaciones del manifiesto de la app web para ver cuándo y cómo se reflejan esos cambios en Chrome.