# 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…

- Page: <https://www.datafirefly.com/documentation/pwa-storefront-pack/>
- Langue: fr
- Mis à jour le: 2026-08-31
- Autres langues: [en](https://www.datafirefly.com/en/documentation/pwa-storefront-pack/index.md), [es](https://www.datafirefly.com/es/documentation/pwa-storefront-pack/index.md), [de](https://www.datafirefly.com/de/documentation/pwa-storefront-pack/index.md), [it](https://www.datafirefly.com/it/documentation/pwa-storefront-pack/index.md), [pl](https://www.datafirefly.com/pl/documentation/pwa-storefront-pack/index.md), [nl](https://www.datafirefly.com/nl/documentation/pwa-storefront-pack/index.md), [pt](https://www.datafirefly.com/pt/documentation/pwa-storefront-pack/index.md)
- Index: <https://www.datafirefly.com/documentation/llms.txt>

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.

**Aucun service tiers.** Contrairement à la plupart des solutions push pour WordPress, aucune donnée client ne transite par un intermédiaire. Vos clés VAPID sont générées et stockées sur votre serveur. Vous parlez directement à FCM (Google), Mozilla autopush, WNS (Microsoft), etc.

## Prérequis

- WordPress 6.2 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)

Si votre site n'est pas encore en HTTPS, activez-le avant d'installer le plugin. Toutes les fonctionnalités PWA seront désactivées silencieusement en HTTP.

## 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

**Important pour les plugins de cache :** ces deux URLs doivent toujours être servies fraîches. Ajoutez-les aux exclusions de WP Rocket, W3 Total Cache, LiteSpeed Cache, ou de votre CDN. Sinon les mises à jour de configuration n'atteindront jamais les navigateurs.

## 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).

**Astuce icônes maskable :** utilisez un outil comme `maskable.app` pour générer vos variantes maskable avec la bonne safe zone. Un logo sans marge de sécurité sera tronqué sur certains téléphones Android.

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

**Toujours exclus du cache** (quelle que soit la configuration) : `/wp-admin/`, `/wp-login.php`, `/cart`, `/checkout`, `/my-account`, tous les endpoints AJAX WooCommerce. Ces zones exigent un état frais et authentifié en permanence.

### 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** :

Régénérer les clés invalide instantanément **tous les abonnements existants**. Le plugin vide automatiquement la table des abonnements après confirmation. Les navigateurs des abonnés continueront de recevoir les notifications déjà signées, mais toute nouvelle notification échouera silencieusement jusqu'à ce que l'utilisateur se réabonne.

Ne régénérez les clés qu'en cas de compromission avérée ou lors d'une migration entre environnements.

### 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.

**Bonnes pratiques :** expliquez la valeur ajoutée pour l'utilisateur (« Suivez vos commandes en temps réel »), pas pour vous (« Restez à l'écoute de nos offres »). Le taux d'acceptation est 3 à 4 fois supérieur.

## 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.

**Timing :** évitez les broadcasts en pleine nuit — sur Android, les notifications sonnent par défaut. Un envoi à 21h le vendredi soir a un taux de clic 2× supérieur à un envoi à 3h du matin.

## 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.

### Multilingue : WPML et Polylang

Le plugin est compatible avec **WPML** (y compris WooCommerce Multilingual) et **Polylang / Polylang Pro**, en mode sous-répertoires (`/en/`, `/it/`), sous-domaines ou paramètre de langue :

- **Service Worker** : toujours enregistré depuis la racine du site (`/pwasp-service-worker.js`) avec un scope `/`, donc un seul SW couvre toutes les langues.
- **Manifest** : servi dans chaque langue (`/en/pwasp-manifest.json`) avec nom, description et `start_url` de cette langue. Le champ `id` est identique partout : l'app installée depuis `/it/` et depuis `/fr/` est la même app.
- **Textes admin** (bannière d'installation, pré-invite push, message hors ligne, nom et nom court de l'app) : enregistrés automatiquement dans **WPML → String Translation** (domaine « PWA Storefront Pack ») et dans **Langues → Traductions de chaînes** pour Polylang. Saisissez-les dans la langue par défaut, traduisez-les là.
- **Notifications push** : envoyées dans la langue de chaque abonné (locale mémorisée à l'inscription). L'alerte retour en stock utilise le nom et l'URL du produit traduit.
- **Écran hors ligne** : pré-caché pour chaque langue et servi dans la langue de la page demandée.
- **Panier / Commande / Mon compte** : exclus du cache quelle que soit leur traduction de slug (résolus par langue côté serveur).

**WooCommerce Multilingual multi-devises :** la devise étant sélectionnée par cookie, deux visiteurs voient des prix différents sur la même URL. Le plugin force donc la stratégie HTML en _network-first_ et ne met jamais en cache les URLs de changement de devise (`?currency=`). Le montant des notifications « nouvelle commande » est toujours celui de la commande, dans sa devise.

### 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](https://www.datafirefly.com/my-account/). Réponse sous 24 h ouvrées.