Bruno Charest f22a2abae8 feat: add Progressive Web App (PWA) support with service worker registration, manifest, update notifications, and install prompts

2026-03-24 23:55:15 -04:00

9.3 KiB

Raw Blame History

Guide PWA - ObsiGate

ObsiGate est maintenant une Progressive Web App (PWA) complète, offrant une expérience d'application native sur tous les appareils.

🎯 Qu'est-ce qu'une PWA ?

Une Progressive Web App combine le meilleur du web et des applications natives :

Installation : Installez ObsiGate sur votre appareil comme une application native
Mode hors ligne : Accédez à vos notes même sans connexion internet
Notifications : Recevez des alertes de mise à jour
Performance : Chargement rapide grâce au cache intelligent
Multi-plateforme : Fonctionne sur desktop, mobile et tablette

📱 Installation

Sur Desktop (Chrome, Edge, Brave)

Ouvrez ObsiGate dans votre navigateur
Cliquez sur l'icône d'installation dans la barre d'adresse (➕ ou ⬇️)
Cliquez sur "Installer" dans la popup
ObsiGate apparaît maintenant dans vos applications

Alternative : Menu ⋮ → "Installer ObsiGate..."

Sur Android

Ouvrez ObsiGate dans Chrome
Appuyez sur le menu ⋮ (trois points)
Sélectionnez "Ajouter à l'écran d'accueil"
Confirmez l'installation
L'icône ObsiGate apparaît sur votre écran d'accueil

Sur iOS/iPadOS (Safari)

Ouvrez ObsiGate dans Safari
Appuyez sur le bouton Partager 📤
Faites défiler et sélectionnez "Sur l'écran d'accueil"
Nommez l'application et appuyez sur "Ajouter"
ObsiGate apparaît sur votre écran d'accueil

⚡ Fonctionnalités PWA

Mode Hors Ligne

Le service worker met en cache :

Interface utilisateur : HTML, CSS, JavaScript
Ressources statiques : Icônes, polices
Contenu API : Dernières données consultées

Stratégies de cache :

Cache First : Assets statiques (interface)
Network First : API et données dynamiques
Fallback : Affichage gracieux en cas d'erreur

Mises à Jour Automatiques

Vérification des mises à jour toutes les minutes
Notification élégante quand une nouvelle version est disponible
Mise à jour en un clic sans perte de données

Raccourcis d'Application

Accès rapide aux fonctionnalités depuis l'icône :

Recherche : Ouvre directement la recherche

🛠️ Configuration Technique

Fichiers PWA

ObsiGate/
├── frontend/
│   ├── manifest.json          # Manifeste PWA
│   ├── sw.js                  # Service Worker
│   ├── icons/                 # Icônes PWA
│   │   ├── icon-72x72.svg
│   │   ├── icon-192x192.svg
│   │   ├── icon-512x512.svg
│   │   └── ...
│   ├── index.html             # Meta tags PWA
│   ├── app.js                 # Enregistrement SW
│   └── style.css              # Styles PWA
└── generate_pwa_icons.py      # Générateur d'icônes

Manifeste (manifest.json)

Définit les métadonnées de l'application :

Nom et description
Icônes (multiples tailles)
Couleurs de thème
Mode d'affichage (standalone)
Raccourcis d'application

Service Worker (sw.js)

Gère le cache et le mode hors ligne :

Cache statique : Interface et assets
Cache dynamique : Données API (max 50 entrées)
Stratégies : Cache-first et Network-first
Nettoyage : Suppression automatique des anciens caches

Icônes PWA

Tailles supportées :

72x72 : Favicon, petites icônes
96x96 : Raccourcis
128x128, 144x144, 152x152 : Appareils mobiles
192x192 : Android home screen (standard)
384x384 : Haute résolution
512x512 : Splash screens, maskable icons

Maskable icons : Icônes adaptatives avec safe zone pour Android

🔧 Génération des Icônes

Utilisation du Script

# Générer les icônes SVG
python generate_pwa_icons.py

Le script crée :

Icônes régulières (toutes tailles)
Icônes maskables (192x192, 512x512)
Icône de recherche (96x96)
README avec instructions de conversion

Conversion SVG → PNG (Production)

Option 1 : ImageMagick

cd frontend/icons
for file in *.svg; do
  size=$(echo $file | grep -oP '\d+x\d+' | head -1 | cut -d'x' -f1)
  convert -background none -resize ${size}x${size} "$file" "${file%.svg}.png"
done

Option 2 : Inkscape

cd frontend/icons
for file in *.svg; do
  size=$(echo $file | grep -oP '\d+x\d+' | head -1 | cut -d'x' -f1)
  inkscape "$file" --export-filename="${file%.svg}.png" --export-width=$size
done

Option 3 : Outils en ligne

Note : Les navigateurs modernes supportent les SVG directement, la conversion PNG est optionnelle.

🎨 Personnalisation

Modifier les Couleurs

Éditez frontend/manifest.json :

{
  "theme_color": "#2563eb",        // Couleur de la barre d'état
  "background_color": "#1a1a1a"    // Couleur de fond au lancement
}

Modifier les Icônes

Éditez generate_pwa_icons.py
Modifiez les fonctions create_svg_icon() et create_maskable_svg_icon()
Régénérez : python generate_pwa_icons.py

Ajouter des Raccourcis

Éditez frontend/manifest.json :

{
  "shortcuts": [
    {
      "name": "Nouvelle Note",
      "url": "/?action=new",
      "icons": [{"src": "/static/icons/new-96x96.png", "sizes": "96x96"}]
    }
  ]
}

🔍 Débogage

Vérifier l'Installation PWA

Chrome DevTools :

Ouvrez DevTools (F12)
Onglet "Application"
Section "Manifest" : Vérifiez les métadonnées
Section "Service Workers" : Vérifiez l'enregistrement
Section "Cache Storage" : Inspectez le cache

Tester le Mode Hors Ligne

DevTools → Onglet "Network"
Cochez "Offline"
Rechargez la page
L'application doit fonctionner avec les données en cache

Logs du Service Worker

// Dans la console du navigateur
navigator.serviceWorker.getRegistration().then(reg => {
  console.log('Service Worker:', reg);
  console.log('Active:', reg.active);
  console.log('Waiting:', reg.waiting);
});

Forcer la Mise à Jour

// Dans la console
navigator.serviceWorker.getRegistration().then(reg => {
  reg.update();
});

Désinstaller le Service Worker

// Dans la console
navigator.serviceWorker.getRegistrations().then(registrations => {
  registrations.forEach(reg => reg.unregister());
});

📊 Métriques PWA

Lighthouse Audit

Chrome DevTools → Onglet "Lighthouse"
Sélectionnez "Progressive Web App"
Cliquez sur "Generate report"

Critères évalués :

✅ Manifeste valide
✅ Service Worker enregistré
✅ HTTPS (ou localhost)
✅ Icônes appropriées
✅ Responsive design
✅ Mode hors ligne

Score Attendu

ObsiGate devrait obtenir 90-100/100 sur l'audit PWA.

🚀 Déploiement

Prérequis

HTTPS obligatoire en production (sauf localhost)
Service Worker nécessite une connexion sécurisée

Configuration Reverse Proxy

Nginx :

location /sw.js {
    add_header Cache-Control "no-cache, no-store, must-revalidate";
    add_header Service-Worker-Allowed "/";
    proxy_pass http://obsigate:8080;
}

location /manifest.json {
    add_header Cache-Control "public, max-age=3600";
    proxy_pass http://obsigate:8080;
}

Traefik :

http:
  middlewares:
    sw-headers:
      headers:
        customResponseHeaders:
          Cache-Control: "no-cache, no-store, must-revalidate"
          Service-Worker-Allowed: "/"

🔒 Sécurité

Content Security Policy

Le service worker respecte la CSP définie dans le backend :

Scripts : 'self' + CDN autorisés
Styles : 'self' + CDN autorisés
Images : 'self' + data URIs

Permissions

PWA installée demande les mêmes permissions que le site web :

Aucune permission supplémentaire requise
Notifications : optionnelles (désactivées par défaut)

📱 Compatibilité

Plateforme	Support	Notes
Chrome Desktop	✅ Complet	Installation native
Edge Desktop	✅ Complet	Installation native
Firefox Desktop	⚠️ Partiel	Pas d'installation, SW fonctionne
Safari Desktop	⚠️ Partiel	Support limité
Chrome Android	✅ Complet	Installation + notifications
Safari iOS	✅ Complet	"Add to Home Screen"
Samsung Internet	✅ Complet	Installation native

🎓 Ressources

❓ FAQ

Q : Puis-je utiliser ObsiGate sans l'installer ?
R : Oui, l'installation est optionnelle. Le site web fonctionne normalement.

Q : Les données sont-elles synchronisées hors ligne ?
R : Non, le mode hors ligne utilise le cache local. Les modifications nécessitent une connexion.

Q : Comment désinstaller l'application ?
R : Desktop : Clic droit sur l'icône → "Désinstaller". Mobile : Maintenez l'icône → "Supprimer".

Q : Le cache prend-il beaucoup d'espace ?
R : Non, le cache est limité à ~50 entrées dynamiques + assets statiques (~5-10 MB).

Q : Puis-je désactiver le service worker ?
R : Oui, supprimez l'enregistrement dans DevTools ou commentez registerServiceWorker() dans app.js.

ObsiGate PWA - Vos notes Obsidian, partout, tout le temps. 📖✨

9.3 KiB Raw Blame History Unescape Escape