PWA Storefront Pack

Guide complet d’installation, de configuration et d’utilisation de PWA Storefront Pack : le plugin qui transforme votre boutique WooCommerce en Progressive Web App installable, avec mode hors ligne et notifications push VAPID natives (sans Firebase, sans OneSignal, sans abonnement mensuel).

Aperçu et principe de fonctionnement

PWA Storefront Pack ajoute à votre WooCommerce trois briques indépendantes mais complémentaires :

• Web App Manifest — vos clients peuvent installer votre boutique sur leur écran d’accueil comme une vraie application (icône, splash screen, mode standalone sans barre d’adresse).
• Service Worker — cache intelligent des pages et ressources, page hors ligne personnalisable, exclusions automatiques des zones sensibles (panier, checkout, mon compte).
• Notifications push VAPID — implémentation complète du protocole Web Push en PHP pur : ECDSA P-256, JWT ES256, chiffrement aes128gcm. Votre serveur dialogue directement avec les services push des navigateurs.

Prérequis

• WordPress 6.0 ou supérieur
• WooCommerce 7.0 ou supérieur
• PHP 7.4 ou supérieur avec l’extension openssl (activée par défaut sur tous les hébergeurs)
• HTTPS obligatoire — les navigateurs refusent d’enregistrer un Service Worker ou de gérer des notifications push sur HTTP (sauf localhost pour le développement)

Installation

1. Téléchargez l’archive pwa-storefront-pack.zip depuis votre compte DataFirefly.
2. Dans WordPress, allez dans Extensions → Ajouter → Téléverser une extension.
3. Sélectionnez le ZIP et cliquez sur Installer maintenant, puis Activer.
4. À l’activation, le plugin crée trois tables SQL (wp_pwasp_subscriptions, wp_pwasp_push_log, wp_pwasp_stock_waitlist) et génère automatiquement votre paire de clés VAPID.
5. Rendez-vous dans WooCommerce → PWA Storefront pour configurer.

Configuration générale

L’onglet General centralise l’identité de votre application :

• Enable PWA — interrupteur principal. Désactivez pour retirer temporairement le manifest et le Service Worker sans désinstaller le plugin.
• App name — nom complet affiché lors de l’installation et sur le splash screen (ex. « Ma Boutique Officielle »).
• Short name — libellé court sous l’icône de l’écran d’accueil, limité à 12 caractères par convention Android.
• Theme color — couleur de la barre d’adresse et du sélecteur de tâches (recommandé : votre couleur de marque principale).
• Background color — fond du splash screen pendant le chargement de l’app (souvent blanc ou très clair).

URLs des endpoints

Le plugin sert deux endpoints critiques :

• https://votre-site.com/pwasp-manifest.json — le Web App Manifest
• https://votre-site.com/pwasp-service-worker.js — le Service Worker

Manifest

L’onglet Manifest contrôle le comportement de l’app installée :

• Display mode — standalone par défaut (recommandé, expérience type app). Autres options : fullscreen, minimal-ui, browser.
• Orientation — any, portrait ou landscape. Sur mobile, portrait est souvent le plus adapté aux boutiques.
• Start URL — chemin où l’app s’ouvre au lancement. Par défaut /. Vous pouvez pointer vers /shop pour ouvrir directement le catalogue.
• Scope — périmètre d’URLs contrôlé par l’app. Généralement /. Ne le restreignez que si vous n’utilisez la PWA que sur un sous-dossier.
• Categories — indices pour les app stores web (Chrome, Edge). Exemple : shopping,business.
• Shortcuts — activez pour générer des raccourcis Boutique / Panier / Mon compte accessibles par appui long sur l’icône de l’écran d’accueil.

Icônes de l’application

L’onglet Icons permet d’associer vos icônes depuis la médiathèque WordPress. Cinq formats sont gérés :

• Icon 192×192 (any purpose) — obligatoire. Utilisé sur Android, dans les résultats du moteur de recherche.
• Icon 512×512 (any purpose) — obligatoire. Icône du splash screen au lancement.
• Maskable 192×192 — optionnel. Avec marge de sécurité interne de 10 % pour les icônes adaptatives Android (formes rondes, carrées, larmes).
• Maskable 512×512 — optionnel. Même principe pour le splash screen.
• Apple Touch Icon 180×180 — pour iOS. Sans coins arrondis (iOS les ajoute automatiquement).

Tant qu’aucune icône n’est configurée, le plugin utilise des icônes par défaut fournies (marque DataFirefly). Remplacez-les avant de mettre en production.

Mode hors ligne et stratégie de cache

L’onglet Offline & Cache configure le comportement du Service Worker :

Stratégies

• Network first (recommandé) — le navigateur essaie le réseau, puis retombe sur le cache si offline. Fraîcheur maximale des prix et du stock.
• Cache first — le cache répond immédiatement, le réseau met à jour en arrière-plan. Plus rapide mais peut afficher des prix légèrement périmés.

Les stratégies s’appliquent uniquement aux pages HTML. Les autres types de ressources ont des stratégies fixes optimales :

• CSS / JS / polices → cache-first (elles ne changent qu’aux mises à jour de version)
• Images produit → stale-while-revalidate (affichage immédiat depuis le cache, refresh en arrière-plan)

Portée du cache

Trois cases à cocher permettent d’activer/désactiver le cache par type :

• Cache HTML pages — pages produit, catégorie, page d’accueil, articles
• Cache CSS / JS / fonts — le squelette de votre thème
• Cache images — visuels produit, images des articles de blog

Page hors ligne

Deux options :

• Utiliser l’écran par défaut — écran minimaliste intégré au plugin (icône, message, bouton Réessayer), aux couleurs de votre marque.
• Utiliser une page personnalisée — sélectionnez une page WordPress existante. Elle sera pré-cachée à l’installation du Service Worker et servie en cas d’échec réseau.

Bannière d’installation

L’onglet Install Banner contrôle la promotion de l’installation :

• Delay (page views) — nombre de pages vues avant affichage. 3 par défaut : l’utilisateur a manifesté un intérêt minimum sans être harcelé dès la première visite.
• Banner title / text / CTA / Dismiss — textes entièrement personnalisables, traduisibles via .pot.

Comportement :

• Sur Chrome, Edge, Opera, Samsung Internet : la bannière apparaît quand le navigateur signale que le site est installable (beforeinstallprompt). Un clic sur le CTA affiche la boîte native d’installation.
• Sur iOS Safari : la bannière affiche automatiquement les instructions « Touchez Partager, puis Sur l’écran d’accueil » (Apple ne propose pas d’API d’installation programmatique).
• Dismissal mémorisé 7 jours — si l’utilisateur ferme la bannière, elle ne réapparaît pas avant une semaine.
• Détection automatique — si l’app est déjà installée (mode standalone détecté), la bannière ne s’affiche plus.

Notifications push : les clés VAPID

Les notifications push utilisent le protocole VAPID (Voluntary Application Server Identification), standard W3C. À l’activation du plugin, une paire de clés ECDSA P-256 est générée automatiquement :

• Clé publique — partagée avec les navigateurs des abonnés (via JavaScript). 65 octets, encodée base64url.
• Clé privée — jamais transmise, sert à signer chaque envoi. 32 octets.

L’onglet Push Notifications affiche votre clé publique en clair et le nombre d’abonnements actifs. Vous pouvez la copier pour d’éventuels tests externes.

Régénération des clés

Le bouton Regenerate keys génère une nouvelle paire. Cette opération est destructive :

VAPID subject

Champ VAPID subject : adresse de contact au format mailto:vous@exemple.com ou https://exemple.com/contact. Certains services push (Mozilla notamment) l’utilisent pour vous joindre en cas d’abus détecté sur votre serveur. Pré-rempli avec l’email admin de WordPress.

Opt-in prompt et RGPD

La section Opt-in prompt configure la pré-invite affichée avant la boîte de dialogue native de permission :

• Show opt-in prompt — active la pré-invite personnalisée. Recommandé : la boîte native seule a un taux de refus élevé et bloque toute nouvelle demande pour 30 jours.
• GDPR consent required — n’affiche jamais la boîte native sans clic explicite de l’utilisateur sur votre CTA. Requis en Europe pour être conforme RGPD.
• Delay (seconds) — attente avant affichage. 10 secondes par défaut : laisser l’utilisateur explorer avant de solliciter la permission.
• Prompt title / text / CTA / Dismiss — textes entièrement personnalisables.

Déclencheurs automatiques

Le plugin livre trois automatisations branchées directement sur les hooks WooCommerce. Chacune est activable indépendamment.

Statut de commande

Hook : woocommerce_order_status_changed.
Le client identifié (pas les invités) reçoit une notification à chaque transition de statut de sa commande. Titre : « Commande #1042 mise à jour ». Corps : « Statut : Expédiée ». Clic → page de suivi de commande.

La notification utilise un tag unique par commande (order-1042) : les mises à jour successives remplacent la précédente au lieu de s’empiler.

Nouvelle commande (admin)

Hook : woocommerce_new_order.
Tous les utilisateurs ayant le rôle administrator ou shop_manager et abonnés aux push reçoivent une notification à chaque nouvelle commande. Titre : « Nouvelle commande reçue ». Corps : « Commande #1042 — 189,00 € ». Clic → écran d’édition de la commande.

L’URL admin est HPOS-aware : si votre WooCommerce utilise High-Performance Order Storage, le lien pointe vers le nouveau schéma (admin.php?page=wc-orders). Sinon vers l’ancien (post.php?post=X).

Retour en stock

Hook : woocommerce_product_set_stock et woocommerce_variation_set_stock.
Quand un produit passe de « rupture » à « en stock », le plugin envoie une notification à tous les visiteurs qui s’étaient ajoutés à sa liste d’attente. Titre : « De retour en stock ! ». Corps : « Sneakers cuir premium édition limitée est de nouveau disponible ». Image du produit en aperçu si disponible.

Chaque entrée est marquée notified_at après envoi réussi, pour éviter les doublons si le stock oscille.

Composeur de broadcast

Menu : WooCommerce → PWA Broadcast. Interface pour envoyer une notification manuelle à tous les abonnés actifs (campagnes marketing, annonces, etc.).

Champs :

• Title — titre de la notification (100 caractères max recommandés)
• Message — corps de la notification (200 caractères max recommandés)
• Open URL — page où l’utilisateur arrive au clic (par défaut la page d’accueil)
• Image URL — grande image affichée dans la notification (Android uniquement, iOS ne l’affiche pas)

Un aperçu en temps réel montre le rendu approximatif de la notification à droite de l’écran.

Deux boutons :

• Send broadcast — envoi à tous les abonnés actifs (confirmation requise)
• Send test to me — envoi uniquement à vos propres abonnements. Utile pour valider le rendu avant broadcast massif.

Liste d’attente retour en stock (API JavaScript)

Pour permettre aux visiteurs de s’inscrire à la liste d’attente d’un produit en rupture, appelez depuis votre thème :

window.PWASP.addToWaitlist(productId)
  .then(result => {
    if (result.success) {
      alert('Vous serez notifié dès le retour en stock !');
    }
  });

Comportement :

1. Si l’utilisateur n’est pas encore abonné aux push, la boîte de permission native s’ouvre.
2. Une fois l’abonnement enregistré côté serveur, l’entrée est ajoutée à la liste d’attente du produit.
3. Au retour en stock détecté, une push est envoyée automatiquement.

Vous pouvez appeler cette API depuis n’importe quel bouton personnalisé ou hook woocommerce_single_product_summary via un mu-plugin.

Autres API JS exposées

// Souscrire manuellement (par exemple depuis un bouton personnalisé)
window.PWASP.subscribePush();

// Désinscrire (bouton « Me désabonner »)
window.PWASP.unsubscribePush();

API REST

Le plugin expose six endpoints sous le namespace pwasp/v1 :

• POST /wp-json/pwasp/v1/subscribe — enregistre un abonnement. Corps : objet PushSubscription du navigateur.
• POST /wp-json/pwasp/v1/unsubscribe — supprime un abonnement. Corps : { endpoint: "..." }.
• POST /wp-json/pwasp/v1/test — envoi de test à l’utilisateur courant (auth requise, capability manage_woocommerce).
• POST /wp-json/pwasp/v1/broadcast — diffusion à tous les abonnés (auth requise).
• POST /wp-json/pwasp/v1/regenerate-vapid — régénère les clés VAPID (auth requise).
• POST /wp-json/pwasp/v1/waitlist — ajoute à une liste d’attente. Corps : { subscription_id, product_id }.

Authentification : nonce WordPress X-WP-Nonce pour les endpoints publics, capability manage_woocommerce pour les endpoints admin.

Compatibilité et cas particuliers

HPOS (High-Performance Order Storage)

Le plugin déclare formellement sa compatibilité HPOS à WooCommerce via FeaturesUtil::declare_compatibility. Vous verrez la case cochée dans WooCommerce → Réglages → Avancé → Fonctionnalités.

Plugins de cache

Ajoutez les exclusions suivantes dans votre plugin de cache :

• /pwasp-manifest.json
• /pwasp-service-worker.js

Certains plugins (WP Rocket, LiteSpeed) proposent également une option pour ne pas cacher les fichiers JavaScript signés Service Worker — activez-la si disponible.

iOS et Safari

Support par version :

• iOS 16.4 et supérieur — installation via « Sur l’écran d’accueil » et notifications push (pour les PWA installées uniquement)
• iOS 15 et 16.3 — installation possible, notifications push non disponibles
• iOS 14 et inférieur — installation possible, aucune notification

Sur iOS, les push ne fonctionnent que si l’utilisateur a d’abord installé la PWA sur son écran d’accueil. C’est une contrainte d’Apple, pas du plugin.

Sous-dossiers et multisite

Le plugin fonctionne sur WordPress installé à la racine (example.com) ou dans un sous-dossier (example.com/shop/). Les endpoints sont résolus dynamiquement via home_url(). En multisite, activez le plugin par site — chaque site aura sa propre paire de clés VAPID et sa propre base d’abonnés.

Dépannage

« Le Service Worker n’est pas enregistré »

1. Vérifiez que votre site est bien en HTTPS (https:// et pas http://).
2. Ouvrez la console navigateur (F12 → onglet Application → Service Workers). Y a-t-il un message d’erreur ?
3. Testez l’URL https://votre-site.com/pwasp-service-worker.js dans un onglet. Le fichier doit renvoyer du JavaScript, pas une page 404 ni la home de WordPress.
4. Si 404 : allez dans Réglages → Permaliens et cliquez sur Enregistrer les modifications pour rafraîchir les règles de réécriture.

« Les notifications n’arrivent pas »

1. Vérifiez dans WooCommerce → PWA Subscribers que votre abonnement est bien listé et en statut active.
2. Utilisez le bouton Send test to me dans le composeur de broadcast. Recevez-vous la notif ?
3. Si non : la boîte de permission a peut-être été refusée. Sur Chrome : ouvrez le cadenas dans la barre d’adresse → Notifications → Autoriser.
4. Sur Windows/macOS : vérifiez que Chrome/Firefox n’est pas en mode « Ne pas déranger ».

« Régénérer les clés VAPID a échoué »

Cause probable : l’extension PHP openssl n’est pas disponible sur votre hébergement, ou la génération de clés ECDSA est bloquée. Vérifiez via un fichier phpinfo.php que la section openssl est présente et que le curve prime256v1 est supporté. Contactez votre hébergeur si nécessaire.

Désinstallation

Suppression via Extensions → Extensions installées → Supprimer :

• Les trois tables SQL sont supprimées
• Les options plugin sont supprimées
• Les tâches cron programmées sont annulées
• Les icônes uploadées dans la médiathèque restent (elles peuvent servir ailleurs)

Support

Pour toute question ou anomalie, ouvrez un ticket depuis votre compte DataFirefly. Réponse sous 24 h ouvrées.