# Manifeste d'application web

## Ce que c'est

Un manifeste d'application web est un document JSON qui décrit un site web comme une application : son nom, l'adresse à laquelle elle s'ouvre, les adresses qui lui appartiennent, l'apparence de sa fenêtre et les images qui la représentent. Une page désigne le fichier par un élément `link` dont le `rel` vaut `manifest`. Un navigateur proposant l'installation le lit pour déterminer ce que sera la copie installée. La spécification du W3C qui le définit l'appelle simplement manifeste, comme la plupart des échanges courants sur le sujet.

Le fichier est du JSON ordinaire. Son type de média enregistré est `application/manifest+json` et son extension enregistrée `.webmanifest`, même si la spécification accepte tout type de média JSON et si de nombreux sites servent un `manifest.json`. Chaque champ est facultatif. Voici un petit exemple pour un site imaginaire de tables des marées :

```json
{
    "name": "Harbour Tide Tables",
    "short_name": "Tides",
    "start_url": "/tides/",
    "display": "standalone",
    "background_color": "#ffffff",
    "icons": [
        {
            "src": "/icons/tides-512.png",
            "sizes": "512x512",
            "type": "image/png"
        }
    ]
}
```

Trois champs déterminent ce qu'est l'application, par opposition à son apparence. `start_url` suggère la page sur laquelle s'ouvre l'application installée ; un navigateur peut l'ignorer ou permettre à l'utilisateur de la modifier. `scope` est l'ensemble des adresses considérées comme internes à l'application. S'il manque, la spécification prend l'URL de départ sans son nom de fichier, sa chaîne de requête ni son fragment. L'exemple ci-dessus couvre donc tout ce qui se trouve sous `/tides/`. `id` est l'identité de l'application et, s'il manque, reprend l'URL de départ. Les adresses relatives des icônes et l'URL de départ sont résolues par rapport à l'URL du manifeste lui-même, et non à la page qui y renvoie. Un `id` relatif est, lui, résolu par rapport à l'origine de l'URL de départ.

Le reste relève de la présentation. `display` demande `fullscreen`, `standalone`, `minimal-ui` ou `browser`. Un navigateur qui ne peut satisfaire la demande descend dans cette liste dans l'ordre. Chaque icône peut porter un `purpose` : `any` par défaut, `maskable` pour une image conçue pour supporter le recadrage, ou `monochrome` pour une image dont la couleur est supprimée afin de n'utiliser que son canal alpha. `theme_color` colore la fenêtre autour de l'application. Une note complémentaire du W3C ajoute `description`, `categories` et `screenshots`, que les dialogues d'installation et les boutiques peuvent afficher.

## Pourquoi c'est important

Le manifeste fournit des métadonnées d'installation que le site maîtrise. La spécification laisse la décision d'installer au navigateur : il peut proposer un moyen de le faire, et chaque navigateur fixe ses propres conditions, dont certaines exigent des champs particuliers. Une équipe fournit les données d'entrée, et le navigateur décide de leur usage. La question utile porte donc moins sur la présence d'un manifeste que sur ce qu'il promet.

L'identité est la promesse qui survit au fichier. Lorsqu'un navigateur récupère à nouveau le manifeste, la spécification indique qu'il devrait utiliser un `id` identique comme signal que le nouveau fichier remplace le manifeste d'une application déjà installée. Puisqu'en l'absence d'`id`, l'identité est l'URL de départ, déplacer la page de départ la modifie silencieusement. Le navigateur devrait donc traiter le nouveau fichier comme une application différente de celle présente sur l'appareil du lecteur. Fixer `id` dès la première version coûte une ligne et supprime ce risque.

La portée détermine où s'arrête la fenêtre de l'application. La navigation à l'intérieur de cette portée reste dans la fenêtre installée. Un lien qui en sort s'ouvre tout de même, mais la spécification attend du navigateur qu'il indique au lecteur qu'il se trouve hors de l'application. Une portée plus étroite que le site fait donc apparaître des liens ordinaires entre ses sections comme des sorties.

Les icônes concentrent la plupart des dégâts visibles. Les lanceurs les recadrent en cercles, carrés arrondis et autres formes ; un logo qui remplit tout son carré perd ses bords. La spécification définit la zone sûre d'une icône masquable comme un cercle central dont le rayon vaut deux cinquièmes du côté le plus court de l'icône. Tout ce qui dépasse peut être coupé. Une icône monochrome ne conserve que son canal alpha : dessinée sur un fond opaque, elle devient un carré plein.

Les champs de couleur ont un rôle plus étroit qu'il n'y paraît. `background_color` n'est prévu que pour le moment précédant l'arrivée de la feuille de style. La spécification interdit au navigateur de l'utiliser une fois cette feuille disponible. C'est la couleur de la première image affichée, et de rien ensuite.

## À quoi cela ressemble en pratique

Ce site construit son manifeste à partir d'un modèle plutôt que de tenir un fichier à jour manuellement. Sa configuration Hugo enregistre `application/manifest+json` avec le suffixe `webmanifest` et fait du manifeste une sortie de la page d'accueil de chaque langue. Chacune reçoit donc son propre fichier, et l'en-tête HTML de chaque page renvoie au fichier de sa langue. La configuration en consigne la raison : une copie globale ne peut désigner qu'une URL de départ, et un visiteur ayant installé la version danoise du site obtenait une application ouvrant la page d'accueil anglaise.

Le modèle assemble le manifeste sous forme de table associative et le confie à l'encodeur JSON de Hugo. L'échappement et les virgules relèvent donc de l'encodeur, et une virgule manquante ne peut être publiée. Chaque adresse d'icône part de la racine de l'hôte. Le commentaire explique pourquoi : une adresse relative dans `/da/manifest.webmanifest` serait résolue sous `/da/`, et chaque icône danoise donnerait une 404. Les icônes elles-mêmes sont lues sur disque dans trois dossiers, un par usage, avec dix tailles chacun allant de 36 à 512 pixels. La taille est tirée du nom du fichier ; une taille ajoutée par le générateur apparaît donc dans le manifeste sans modification manuelle.

`id` est fixé à l'adresse d'accueil de la langue, et `scope` couvre toute l'origine : un lien vers une autre langue reste ainsi dans la fenêtre installée. Les captures d'écran sont nommées `<lang>-<form_factor>-<WxH>.webp`, et le modèle déduit les trois informations du nom du fichier. L'anglais et le danois comportent chacun une capture large de 1 280 par 800 et une capture étroite de 780 par 1 688. Une langue sans capture ne reçoit aucun champ `screenshots`, plutôt qu'une liste vide.

La [page des crédits](/fr/credits/) cite la spécification du W3C parmi les standards suivis par le site et PWABuilder parmi les contrôles externes accessibles à tous : un service qui lit le manifeste et les autres éléments rendant le site installable, depuis les machines de Microsoft.

La [page d'installation](/fr/install/) présente ce même fichier du point de vue du lecteur. Elle explique où chaque navigateur place la commande d'installation et précise que les navigateurs d'Apple ne la proposent jamais spontanément. Firefox dispose d'une fonction distincte de fenêtre d'application web, activée par défaut sous Windows à partir de la version 143, ou de la version 150 pour les installations depuis le Microsoft Store. La documentation d'implémentation de Mozilla indique une prise en charge de Linux désactivée par défaut et une absence de prise en charge de macOS. La page précise aussi ce qu'il faut attendre de ce site : l'application installée dispose d'une icône et de sa propre fenêtre. Le site ne publie ni service worker ni copie hors ligne gérée ; il a donc besoin d'une connexion pour un usage normal.

## Où les problèmes surviennent

**Chaque icône donne une 404 sous un chemin traduit.** Un `src` relatif est résolu par rapport à l'URL du manifeste. Un manifeste servi sous un préfixe de langue demande donc ses icônes sous ce préfixe. Écrivez les adresses d'icône depuis la racine de l'hôte, ou sous forme d'URL complètes.

**L'application installée s'ouvre dans la mauvaise langue.** Un manifeste ne peut désigner qu'une URL de départ ; tous les lecteurs installent donc la même page d'accueil. Servez un manifeste par langue, chacun avec ses propres `start_url` et `id`, et reliez chaque page au manifeste correspondant.

**Les copies installées ignorent le nouveau manifeste.** Sans `id`, l'identité est l'URL de départ. Déplacer cette page donne donc au fichier une nouvelle identité, et le navigateur devrait le traiter comme une application différente de celle déjà installée par les lecteurs. Définissez `id` avant la première version et n'y touchez plus ensuite.

**Le lanceur recadre le logo.** Une icône ayant l'usage `any` est placée ou coupée selon le choix de la plateforme. Ajoutez une icône `maskable` dont tout le contenu important tient dans le cercle central de rayon égal à 40 % du côté le plus court de l'icône.

**Modifier le manifeste ne change rien.** Le standard HTML n'utilise que le premier élément `link` dont le `rel` contient `manifest`. Si un thème ou une extension a inséré son propre lien plus tôt dans la page, le fichier modifié n'est donc jamais celui qui est lu. Gardez exactement un lien de manifeste par page.

## Pour aller plus loin

- [Web Application Manifest](https://www.w3.org/TR/appmanifest/) — chaque champ, le traitement du fichier par le navigateur et les règles d'`id`, de `scope` et des usages des icônes.
- [Manifeste d'application web : informations sur l'application](https://www.w3.org/TR/manifest-app-info/) — `description`, `categories` et `screenshots`, avec les formats d'écran et les libellés.
- [IANA : application/manifest+json](https://www.iana.org/assignments/media-types/application/manifest+json) — l'enregistrement du type de média et de son extension `.webmanifest`.
- [Standard HTML : type de lien manifest](https://html.spec.whatwg.org/multipage/links.html#link-type-manifest) — comment le lien de manifeste est récupéré et pourquoi seul le premier compte.
- [Utiliser les applications web dans Firefox pour Windows](https://support.mozilla.org/en-US/kb/web-apps-firefox-windows) — la fonction Windows et sa disponibilité à partir de la version 143, ou de la version 150 pour les installations depuis le Microsoft Store.
- [Documentation source de Firefox : applications web dans Firefox](https://firefox-source-docs.mozilla.org/browser/components/taskbartabs/docs/index.html) — l'implémentation actuelle : Windows activé par défaut, Linux désactivé par défaut et macOS non pris en charge.

<https://engineer.company/fr/glossary/webmanifest/>
