Proposer votre propre expérience d'installation dans l'application

Pete LePage

De nombreux navigateurs vous permettent d'activer et de promouvoir l'installation de votre progressive web app (PWA) directement dans son interface utilisateur. L'installation (anciennement appelée "Ajouter à l'écran d'accueil") permet aux utilisateurs d'installer votre PWA sur leur appareil mobile ou leur ordinateur. L'installation d'une PWA l'ajoute au lanceur d'applications d'un utilisateur afin qu'elle puisse s'exécuter comme n'importe quelle autre application installée.

En plus de l'expérience d'installation fournie par le navigateur, vous pouvez fournir votre propre flux d'installation personnalisé directement dans votre application.

Bouton "Installer l'application" fourni dans la PWA Spotify.

Pour promouvoir ou non l'installation, tenez compte de la façon dont les utilisateurs utiliser votre PWA. Par exemple, si un ensemble d'utilisateurs utilise votre PWA plusieurs fois par semaine, ils peuvent bénéficier de la commodité supplémentaire de lancer votre application depuis l'écran d'accueil d'un téléphone ou depuis le menu Démarrer d'un système d'exploitation pour ordinateur. Certaines applications de productivité et de divertissement bénéficient également de l'espace d'écran supplémentaire créé en supprimant les barres d'outils du navigateur de la fenêtre dans les modes standalone, minimal-ui ou window-control-overlay installés.

Prérequis

Avant de commencer, assurez-vous que votre PWA respecte les exigences d'installabilité, qui incluent généralement un fichier manifeste d'application Web.

Promouvoir l'installation

Pour montrer que votre progressive web app est installable et pour fournir un parcours d'installation personnalisé dans l'application :

1. Écoutez l'événement beforeinstallprompt.
2. Enregistrez l'événement beforeinstallprompt afin qu'il puisse déclencher le flux d'installation plus tard.
3. Informez l'utilisateur que votre PWA est installable et fournissez un bouton ou un autre élément pour lancer le flux d'installation dans l'application.

Remarque: Les événements beforeinstallprompt et appinstalled ont été transférés de la spécification du fichier manifeste d'application Web vers leur propre incubateur. L'équipe Chrome s'engage à les soutenir, et n'a pas l'intention de les supprimer ni de les abandonner de l'assistance. L'équipe Web DevRel de Google recommande toujours de les utiliser pour fournir expérience d'installation personnalisée.

Écouter l'événement beforeinstallprompt

Si votre progressive web app répond aux critères d'installation requis, le navigateur déclenche un événement beforeinstallprompt. Enregistrez une référence à l'événement et mettez à jour votre interface utilisateur pour indiquer que l'utilisateur peut installer votre 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.`);
});

Remarque : Vous pouvez utiliser de nombreux modèles différents pour avertir l'utilisateur que votre application peut être installée et fournir un flux d'installation dans l'application. Il peut s'agir d'un bouton dans l'en-tête, d'un élément dans un menu de navigation ou un élément de votre flux de contenu.

Flux d'installation dans l'application

Pour permettre l'installation dans l'application, fournissez un bouton ou un autre élément d'interface sur lequel l'utilisateur peut cliquer ou appuyer pour installer votre application. Lorsque l'utilisateur clique ou appuie sur l'élément, appelez prompt() sur l'événement beforeinstallprompt enregistré (stocké dans la variable deferredPrompt). Elle affiche une boîte de dialogue d'installation modale demandant à l'utilisateur de confirmer qu'il souhaite installer votre 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 propriété userChoice est une promesse qui répond au choix de l'utilisateur. Vous ne pouvez appeler prompt() qu'une seule fois sur l'événement différé. Si l'utilisateur le ferme, vous devez attendre que l'événement beforeinstallprompt se déclenche à nouveau, généralement juste après que la propriété userChoice est résolu.

Essayez : rendre un site installable à l'aide de l'événement beforeinstallprompt

Détecter quand la PWA a été correctement installée

Vous pouvez utiliser la propriété userChoice pour déterminer si l'utilisateur a installé depuis votre interface utilisateur. En revanche, si l'utilisateur installe votre PWA à partir de la barre d'adresse ou d'un autre composant du navigateur, userChoice ne vous aidera pas. À la place, vous devez écouter l'événement appinstalled, qui se déclenche chaque fois que votre PWA est installé, quel que soit le mécanisme utilisé pour l'installer.

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

Détecter le mode de lancement de la PWA

La requête multimédia CSS display-mode indique comment la PWA a été lancée, soit dans un onglet de navigateur, soit en tant que PWA installée. Cela permet d'appliquer différentes en fonction de la façon dont l'application a été lancée. Par exemple, vous pouvez le configurer pour toujours masquer le bouton d'installation et afficher un bouton "Retour" lorsqu'il est lancé en tant que installé la PWA.

Suivre le lancement de la PWA

Pour suivre la manière dont les utilisateurs lancent votre PWA, utilisez matchMedia() pour tester la display-mode requête média.

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

Suivre les changements de mode d'affichage

Pour savoir si l'utilisateur passe de browser à d'autres modes d'affichage, écoutez les modifications apportées à la requête multimédia 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());
});

Mettre à jour l'UI en fonction du mode d'affichage actuel

Pour appliquer une couleur d'arrière-plan différente à une PWA lorsqu'elle est lancée en tant que PWA installée, utilisez le CSS conditionnel :

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

Modifier l'icône et le nom de votre application

Que faire si vous devez mettre à jour le nom de votre application ou fournir de nouvelles icônes ? Consultez Comment Chrome gère les mises à jour du fichier manifeste de l'application Web pour savoir quand et comment ces modifications sont reflétées dans Chrome.