Web App Manifest et installation PWA : A2HS sans App Store

Tous les champs du manifest sont déclarés dans vite.config.ts. Le plugin vite-plugin-pwa génère le fichier manifest.webmanifest et injecte la balise <link rel="manifest"> dans le HTML au build.

VitePWA({
  registerType: 'autoUpdate',

  // Fichiers copiés dans dist/ et précachés par Workbox (logo SVG non inclus par défaut)
  includeAssets: ['icons/smartbooster-logo.svg'],

  manifest: {
    name:             'Démo PWA Terrain SmartBooster',
    short_name:       'Démo PWA Terrain',     // ≤ 12 caractères recommandé
    description:      'Application terrain pour techniciens, démo offline',
    theme_color:      '#2563eb',         // barre de statut Android + switcher d'apps
    background_color: '#f8fafc',         // couleur du splash screen au chargement
    display:          'standalone',      // pas de barre d'adresse, look natif
    orientation:      'portrait',
    start_url:        '/',

    icons: [
      {
        src:   '/icons/pwa-192x192.png',
        sizes: '192x192',
        type:  'image/png',
      },
      {
        src:   '/icons/pwa-512x512.png',
        sizes: '512x512',
        type:  'image/png',
      },
      {
        src:     '/icons/pwa-512x512.png',
        sizes:   '512x512',
        type:    'image/png',
        purpose: 'any maskable',   // permet à Android de découper l'icône
      },
    ],
  },
})

Icône maskable : Android adapte la forme de l'icône selon le launcher (rond, carré arrondi, goutte...). L'icône maskable doit avoir une zone de sécurité de 10% sur chaque bord pour éviter que le contenu soit découpé. L'outil maskable.app permet de tester le rendu avant déploiement.

Le composable intercepte l'événement beforeinstallprompt au niveau module (avant tout montage de composant) pour ne pas le rater s'il se déclenche tôt au chargement de la page. Il expose aussi showIosHint pour afficher une instruction manuelle sur iOS où cet événement n'existe pas.

import { isIOS, isAndroid } from '@/utils/deviceDetect.js'

// Singleton module-level : les listeners sont enregistrés dès le premier import,
// avant le montage du premier composant. Si beforeinstallprompt se déclenche
// pendant le chargement (fréquent), on ne le rate pas.
const deferredPrompt = ref<BeforeInstallPromptEvent | null>(null)

// Détection via display-mode : si l'app est déjà installée, ne pas afficher
// la bannière d'installation.
const isInstalled = ref(window.matchMedia('(display-mode: standalone)').matches)

const isMobile = isIOS || isAndroid

// Android Chrome : l'événement peut se déclencher avant le montage des composants
window.addEventListener('beforeinstallprompt', (e) => {
  e.preventDefault()   // empêche le mini infobar automatique de Chrome
  if (isMobile) deferredPrompt.value = e as BeforeInstallPromptEvent
})

// Mise à jour de isInstalled quand l'utilisateur accepte l'installation
window.addEventListener('appinstalled', () => {
  deferredPrompt.value = null
  isInstalled.value = true
})

// iOS : pas de beforeinstallprompt. On affiche un hint textuel
// ("Appuyez sur Partager → Ajouter à l'écran d'accueil") si l'app n'est pas installée.
const showIosHint = ref(isMobile && isIOS && !isInstalled.value)

export function useInstallPrompt() {
  async function promptInstall(): Promise<void> {
    if (!deferredPrompt.value) return
    await deferredPrompt.value.prompt()
    const { outcome } = await deferredPrompt.value.userChoice
    // outcome : 'accepted' | 'dismissed'
    deferredPrompt.value = null
  }

  return { deferredPrompt, isInstalled, showIosHint, promptInstall }
}

Pourquoi au niveau module : beforeinstallprompt peut se déclencher très tôt, avant que le composant qui gère la bannière ne soit monté. Si le listener est dans onMounted, l'événement est perdu et la bannière ne s'affiche jamais, même si l'app est installable.