R4A.10 - Compléments Web (vuejs)

1°/ Création d'un projet PWA avec @vue/cli

1.1°/ Initialisation d'un nouveau projet

• Le plus simple est de partir d'un projet d'exemple créé avec vue/cli, en mode paramètres manuels :

vue create mon_projet

• Choisir le 3ème item du menu : Manually select Features
• Utiliser la barre d'espace pour cocher la "case" : Progressive Web App (PWA) Support
• Idem pour les autres plugins (vue-router, vuex, ...) que vous souhaiter intégrer.

1.2°/ Initialisation d'un projet existant

• Si le projet existe déjà, il suffit de taper :

vue add pwa

• Normalement, cela ne "casse" pas la structure du projet existant, à part le fichier main.js qui est modifié.

1.3°/ Création du service worker.

• Après la création du projet, un fichier src/registerServiceWorker.js a été ajouté, par rapport à un projet non PWA.
• Ce fichier permet de faciliter l'enregistrement du service worker auprès du navigateur.
• Dans ce fichier, on remarque que l'enregistrement utilise comme fichier par défaut : service-worker.js.
• C'est ce fichier qu'il faut créer dans src et cela s'avère relativement compliqué quand on ne connait rien aux services worker.
• En effet, il existe un nombre conséquent d'exemples sur le net, qui ne fonctionnent pas du tout, notamment tous ceux qui expliquent comment créer automatiquement une première ébauche de ce fichier, pour ensuite le modifier.
• Il semble que les plugins qui aident à la génération et/ou à l'écriture du fichier, aient changés puisqu'en suivant ces mauvais tutoriaux, on se retrouve à présent avec un fichier JS compacté et donc inexploitable.
• En revanche, il est tout de même possible d'utiliser ces plugins pour automatiser certaines parties, notamment la mise en cache initiale des fichiers de l'application.
• Pour cela, on utilise le plugin workbox-webpack-plugin, qui est installé lorsque l'on intègre le support PWA à l'application (cf. sections précédentes)
• Pour que cette mise en cache soit gérée automatiquement, il faut déjà indiquer au plugin le chemin d'accès au fichier du service worker et ce qu'il doit faire.
• Ceci se fait en modifiant le fichier vue.config.js, à la racine du projet, avec par exemple :

const { defineConfig } = require('@vue/cli-service')
module.exports = defineConfig({
    transpileDependencies: true,
    pwa: {
    name: 'My PWA App',
    appleMobileWebAppCapable: 'yes',
    appleMobileWebAppStatusBarStyle: 'black',
    workboxPluginMode: "InjectManifest",
    workboxOptions: {
      swSrc: "./src/service-worker.js",
        exclude: [/_redirect/, /\.map$/, /_headers/],
    },  
  }
})

• La première option importante est  workboxPluginMode, qui précise que le plugin doit "injecter" automatiquement le contenu du "manifest" dans le fichier service worker. Un peu comme un include en PHP, ou un import en JS.
• Le manifest est un fichier JSON qui est créé automatiquement par webpack lorsque l'on construit l'application en mode production. Il ne faut donc pas le créer soi-même.
• NB 1 : le contenu du manifeste est une suite de propriétés de l'application, avec son nom, ses icônes, des couleurs, etc.
• NB 2 : Il existe une autre valeur pour cette option : GenerateSW, qui permet de générer automatiquement un fichier service-worker.js, mais qui est compacté mais inexploitable.
• La deuxième option importante est  workboxOptions.swSRC, qui précise le chemin d'accès au fichier service worker que l'on va écrire. Normalement, on le met toujours dans ./src/service-worker.js.

• L'étape suivante est de créer src/service-worker.js. ATTENTION ! Ce fichier n'est qu'un "canevas" qui sera modifié/complété par webpack lors du build de production.
• Pour faire uniquement la mise en cache automatique, on écrit :

import {setCacheNameDetails} from 'workbox-core';
import {precacheAndRoute} from 'workbox-precaching';

setCacheNameDetails({prefix: "testpwa"});

// put all important files in cache, as soon as the worker is ready
precacheAndRoute(self.__WB_MANIFEST);

• Grâce à la 3ème ligne, le nom du cache commencera par testpwa, ce qui se constate dans l'inspecteur.
• Le mot-clé self.___WB_MANIFEST sera effectivement remplacé par la liste des fichiers importants à mettre en cache automatiquement (cf. démonstration).

• Après ces instructions, on peut ajouter celles qui mettent en place une stratégie de mise en cache.
• Il est possible d'écrire du JS utilisant les fonctions natives des services workers, ou bien d'utiliser des fonctions de plus haut niveau fournies par les paquets workbox.
• NB : là encore, la plupart des exemples disponibles sur le net basés sur workbox ne fonctionnent pas correctement , voire du tout !
• Si on utilise du JS natif, cela consiste principalement à mettre en place des écouteur d'événements avec un callback pour traiter l'événement.

Exemple 1 : créer un cache nommé mycache, après l'installation du service worker dans le navigateur.

self.addEventListener('install', evt =>
    evt.waitUntil(
        caches.open("mycache").then(() => {
            console.log("cache created");
        })
    )
);

 Exemple 2 : intercepter les requêtes HTTP vers myapi.org afin de faire un traitement spécial (par exemple mettre en cache la réponse)

self.addEventListener('fetch', evt => {
    if (evt.request.url.startsWith(('https://myapi.org/'))) {
        return evt.respondWith(...)
    }
});

•  Dans l'exemple ci-dessus les ... doivent être remplacés par l'appel à une fonction qui crée une réponse à la requête. Cette réponse peut très bien être créée de toute pièce, ou simplement en relançant la requête mais en plaçant le résultat en cache (cf. démonstration).

 1.4°/ Permettre l'installation

• Il y a certaines conditions pour qu'une application puisse être installable, notamment le fait qu'elle a un manifest et un service worker qui gère les requêtes fetch.
• Toute la mécanique d'installation est fournie par le navigateur.
• Elle consiste globalement à mettre en place un écouteur de l'événement beforeinstallprompt qui doit sauvegarder cet événement puis fournir à l'utilisateur un moyen de lancer l'installation.
• Cela peut être par exemple un bouton sur lequel l'utilisateur clique.
• Ce clic permet d'appeler une fonction qui appelle la fonction prompt() de  l'événement sauvegardé. Le navigateur demande donc de confirmer ou infirmer l'installation.
• En cas d'acceptation, la navigateur demande à l'OS de créer un icone de lancement sur le bureau.
• Il est également possible de récupérer ce qu'a répondu l'utilisateur pour faire des traitements supplémentaires (cf. démonstration).

1.5°/ Accéder au matériel

• Selon le navigateur et la plateforme d'exécution, il est possible d'accéder à plus ou moins de périphériques.
• Des exemples de code sont disponibles sur https://whatwebcando.today/. Il sont écrits en pur JS. Il faut donc les adapter un peu pour les intégrer dans une application vue.
• Le code de démonstration fourni un exemple d'accès au GPS et à la caméra.

2°/ Code de démonstration

• L'archive du projet complet (excepté les modules node) est téléchargeable [ ici ]
• L'application est en gros un clone de celle utilisée dans le TD 1 : elle permet de récupérer des villes, personnages et items auprès de l'API apidemo.iut-bm.univ-fcomte.fr.
• Après extraction, aller dans le répertoire testpwa et lancer :

npm install
npm install -g http-server

• La première instruction installe tous les paquets node du projet. La seconde installe de quoi servir l'application web localement.

Remarques sur le code :

• Dans le code de src/service-worker.js, on remarque que l'on intercepte les requêtes fetch, afin de les relancer immédiatement si l'URL demandée est bien celle de l'API. Si ce n'est pas le cas, l'appel initial à fecth se poursuit.
• La relance de la requête se fait dans la méthode networkFirst() qui utilise 2 fonctions successivement :
  • la première pour relancer la requête sur le réseau avec fetch. Si cela réussit, le résultat est mis en cache avant d'être renvoyé à l'application.
  • la deuxième, qui est utilisée en cas d'échec de la première, pour aller chercher dans le cache le résultat de la requête.
• Ces deux fonctions utilisent la console pour déboguer facilement leur fonctionnement.
• Dans un but pédagogique, il y a 2 principes différents d'accès à l'API :
  • un service axios, comme celui du TD 1,
  • un service basé sur l'API native fetch. NB : on remarque que la gestion de l'envoi du corps de la requête, du résultat ou bien des erreurs est moins "pratique" qu'avec axios. L'avantage est que fetch est intégré au navigateur.
• Le services qui s'occupe des villes utilise axios, alors que les deux autres utilisent fetch.
• Dans le suite, on remarquera que cela n'a aucune influence sur la capacité du service worker à intercepter des requêtes.

• L'application peut être testée dans un mode développement avec npm run serve, MAIS dans ce cas, le service worker n'est pas utilisé. On ne peut donc pas tester la mise en cache.
• Pour construire et tester la version de production, en étant à la racine du projet :

npm run build
http-server dist