Fichier manifeste d'application Web

Le fichier manifeste de l'application Web est un fichier que vous créez et qui indique au navigateur comment vous souhaitez que votre contenu Web s'affiche en tant qu'application dans le système d'exploitation. Le fichier manifeste peut inclure des informations de base telles que le nom de l'application, l'icône et la couleur du thème, les préférences avancées telles que l'orientation et les raccourcis d'application souhaités, ainsi que des métadonnées de catalogue, telles que des captures d'écran.

Chaque PWA doit inclure un seul fichier manifeste par application, généralement hébergé dans le dossier racine, et accessible via un lien sur toutes les pages HTML à partir desquelles votre PWA peut être installée. Son extension officielle est .webmanifest. Vous pouvez donc nommer votre fichier manifeste comme suit : app.webmanifest.

Ajouter un fichier manifeste d'application Web à votre PWA

Pour créer un fichier manifeste d'application Web, commencez par créer un fichier texte avec un objet JSON contenant au moins un champ name avec une valeur de chaîne:

app.webmanifest:

{
   "name": "My First Application"
}

Toutefois, créer le fichier ne suffit pas : le navigateur doit également savoir qu'il existe.

Créer un lien vers votre fichier manifeste

Pour que le navigateur prenne en compte le fichier manifeste de votre application Web, vous devez l'associer à votre PWA à l'aide d'un élément HTML <link> et de l'attribut rel défini sur manifest sur toutes les pages HTML de votre PWA. Le processus est le même que pour associer une feuille de style CSS à un document.

index.html:

<html lang="en">
  <title>This is my first PWA</title>
  <link rel="manifest" href="/app.webmanifest">

Déboguer le fichier manifeste

Pour vous assurer que le fichier manifeste est correctement configuré, vous pouvez utiliser l'outil d'inspection dans Firefox et les outils de développement dans tous les navigateurs basés sur Chromium.

Pour les navigateurs Chromium

Dans les outils de développement

  1. Dans le volet de gauche, sous Application, sélectionnez Manifest (Fichier manifeste).
  2. Vérifiez les champs du fichier manifeste analysés par le navigateur.

Pour Firefox

  1. Ouvrez l'inspecteur.
  2. Accédez à l'onglet "Application".
  3. Sélectionnez l'option "Manifeste" dans le panneau de gauche.
  4. Vérifiez les champs du fichier manifeste analysés par le navigateur.

Concevoir votre expérience PWA

Maintenant que votre PWA est connectée à son fichier manifeste, il est temps de remplir les autres champs pour définir l'expérience de vos utilisateurs.

Champs de base

Le premier ensemble de champs représente les informations principales concernant votre PWA. Ils permettent de créer l'icône et la fenêtre de la PWA installée, et de déterminer le mode de démarrage. Les voici :

name
Nom complet de votre PWA. Elle s'affiche avec l'icône sur l'écran d'accueil, le lanceur d'applications, la station d'accueil ou le menu du système d'exploitation.
short_name
Facultatif. Nom plus court de votre PWA, utilisé lorsque l'espace disponible est insuffisant pour afficher la valeur complète du champ name. Limitez-vous à 12 caractères pour réduire le risque de troncation.
icons
Tableau d'objets d'icône avec src, type, sizes et des champs purpose facultatifs décrivant les images qui doivent représenter la PWA.
start_url
URL que la PWA doit charger lorsque l'utilisateur la lance à partir de l'icône installée. Nous vous recommandons d'utiliser un chemin d'accès absolu. Par conséquent, si la page d'accueil de votre PWA est la racine de votre site, vous pouvez la définir sur "/" pour l'ouvrir au démarrage de votre application. Si vous ne fournissez pas d'URL de démarrage, le navigateur peut utiliser l'URL à partir de laquelle la PWA a été installée pour démarrer. Il peut s'agir d'un lien profond, tel que les détails d'un produit, plutôt que de l'écran d'accueil.
display
L'un des éléments fullscreen, standalone, minimal-ui ou browser décrivant comment l'OS doit dessiner la fenêtre de la PWA. Pour en savoir plus sur les différents modes d'affichage, consultez la section relative à la conception des applications. La plupart des cas d'utilisation implémentent standalone.
id
Chaîne qui identifie de manière unique cette PWA par rapport aux autres qui peuvent être hébergées sur la même origine. S'il n'est pas défini, start_url est utilisé comme valeur de remplacement. N'oubliez pas que si vous modifiez start_url ultérieurement (par exemple, lorsque vous modifiez la valeur d'une chaîne de requête), le navigateur risque de ne plus pouvoir détecter qu'une PWA est déjà installée.

Icônes

L'icône de votre PWA constitue son identité visuelle sur tous les appareils de vos utilisateurs lorsqu'elle est installée. Il est donc important d'en définir au moins une. Étant donné que la propriété icons est un ensemble d'objets d'icône, vous pouvez définir plusieurs icônes dans différents formats afin d'offrir la meilleure expérience possible à vos utilisateurs. Chaque navigateur choisit une ou plusieurs icônes en fonction de ses besoins et du système d'exploitation sur lequel il est installé. Ces icônes sont les plus proches des caractéristiques requises.

Si vous ne choisissez qu'une seule taille d'icône, celle-ci doit être de 512 x 512 pixels. Toutefois, nous vous recommandons d'ajouter d'autres tailles, y compris des images au format 192 x 192, 384 x 384 et 1 024 x 1 024 pixels.

"icons": [
   {
      "src": "icons/512.png",
      "type": "image/png",
      "sizes": "512x512"
   },
   {
      "src": "icons/1024.png",
      "type": "image/png",
      "sizes": "1024x1024"
   }
]

Si vous ne fournissez pas d'icône ou si les icônes ne respectent pas la taille recommandée, vous ne remplirez pas les critères d'installation sur certaines plates-formes. Sur d'autres plates-formes, l'icône sera générée automatiquement, par exemple à partir d'une capture d'écran de la PWA ou d'une icône générique.

Icônes masquables

Certains systèmes d'exploitation, tels qu'Android, adaptent les icônes à différentes tailles et formes. Par exemple, sur Android 12, différents fabricants ou paramètres peuvent modifier la forme des icônes, des cercles aux carrés, en passant par les carrés aux coins arrondis. Pour accepter ces types d'icônes adaptatives, vous pouvez fournir une icône masquable à l'aide du champ purpose.

Pour ce faire, fournissez un fichier image carré dont l'icône principale se trouve dans une "zone de sécurité", c'est-à-dire un cercle centré sur l'icône dont le rayon correspond à 40 % de sa largeur. (voir l'image ci-dessous). Les appareils compatibles avec les icônes masquables la masqueront si nécessaire.

Zone de sûreté représentée par un cercle centré de 40 % autour de l&#39;icône carrée

Voici un exemple d'icône masquable affichée dans plusieurs formes couramment utilisées:

Dans l'image suivante, si vous utilisez l'icône située à gauche comme icône masquable, les résultats obtenus sur les appareils seront médiocres lorsqu'un masque de forme est appliqué.

Une icône qui n&#39;est pas adaptée aux icônes masquables

Cette image pourrait être utilisable avec plus de marge intérieure.

L&#39;icône avec plus de marge intérieure convient aux masques.

Les icônes masquantes doivent être au moins de 512 x 512. Une fois que vous en avez créé une, vous pouvez l'ajouter à votre collection icons pour améliorer l'expérience sur les appareils compatibles:

"icons": [
   {
      "src": "/icons/512.png",
      "type": "image/png",
      "sizes": "512x512"
   },
   {
      "src": "/icons/1024.png",
      "type": "image/png",
      "sizes": "1024x1024"
   },
   {
      "src": "/icons/512-maskable.png",
      "type": "image/png",
      "sizes": "512x512",
      "purpose": "maskable"
   },
]

Dans la plupart des cas, si l'icône masquable ne s'affiche pas correctement, vous pouvez l'améliorer en ajoutant une marge intérieure. Maskable.app est un outil en ligne sans frais qui permet de tester et de créer une version masquable de votre icône.

Les champs que vous allez inclure sont destinés à améliorer l'expérience utilisateur, même s'ils ne sont pas nécessaires à l'installation.

theme_color
La couleur par défaut de l'application, qui affecte parfois la façon dont le système d'exploitation affiche le site (par exemple, la couleur de la fenêtre et de la barre de titre sur les ordinateurs ou celle de la barre d'état sur les appareils mobiles). Cette couleur peut être remplacée par l'élément HTML theme-color <meta>.
background_color
Couleur d'espace réservé à afficher en arrière-plan de l'application avant le chargement de la feuille de style. Actuellement, Safari sur iOS et iPadOS, et la plupart des navigateurs pour ordinateur ignorent ce champ.
scope
Modifie le champ d'application de la navigation de la PWA, ce qui vous permet de définir ce qui s'affiche ou non dans la fenêtre de l'application installée. Par exemple, si vous ajoutez un lien vers une page en dehors du champ d'application, elle s'affichera dans un navigateur intégré à l'application et non dans la fenêtre de votre PWA. Toutefois, cela ne modifiera pas le champ d'application de votre service worker.

L'image suivante montre comment le champ theme_color est utilisé pour la barre de titre sur un ordinateur lorsque vous installez une PWA.

La même PWA installée sur l&#39;ordinateur de bureau avec une couleur de thème différente

Lorsque vous définissez des couleurs dans le fichier manifeste, par exemple dans theme_color et background_color, vous devez utiliser des couleurs nommées CSS, telles que salmon ou orange, des couleurs RVB comme #FF5500, ou des fonctions de couleur sans transparence telles que rgb() ou hsl(). Pour en savoir plus, consultez le chapitre relatif à la conception des applications.

Essayer

Écrans de démarrage

Sur certains appareils, une image statique s'affiche pendant le chargement de votre PWA afin de fournir immédiatement des commentaires à l'utilisateur.

Android utilise les valeurs theme_color, background_color et icon pour générer l'écran de démarrage.

Lorsque vous installez une PWA sur Android, l'appareil génère un écran de démarrage contenant les informations provenant de votre fichier manifeste, comme illustré dans le schéma suivant.

Écran de démarrage de PWA sur Android utilisant des valeurs différentes du fichier manifeste.

En revanche, sur iOS et iPadOS, Safari n'utilise pas le fichier manifeste de l'application Web pour générer des écrans de démarrage. À la place, ils utilisent une image liée à un élément <link> propriétaire, de la même manière qu'ils gèrent les icônes. Pour en savoir plus, consultez la section Améliorations.

Champs étendus

L'ensemble de champs suivant fournit des informations supplémentaires sur votre PWA. Ils sont tous facultatifs.

lang
Balise de langue spécifiant la langue principale des valeurs du fichier manifeste, par exemple en pour l'anglais, pt-BR pour le portugais du Brésil ou in pour l'hindi.
dir
Sens d'affichage des champs du fichier manifeste compatibles avec l'orientation (tels que name, short_name et description). Les valeurs valides sont auto, ltr (de gauche à droite) et rtl (de droite à gauche).
orientation
Orientation souhaitée pour l'application une fois installée. Un jeu peut configurer cette option pour demander une orientation en mode paysage uniquement. Plusieurs valeurs sont acceptées, mais si elles sont incluses, il s'agit généralement de portrait ou landscape de manière explicite.

Champs promotionnels

Le quatrième ensemble de champs vous permet de fournir des informations promotionnelles sur votre PWA (par exemple, dans les flux d'installation, les fiches et les résultats de recherche).

description
Explication du fonctionnement des PWA.
screenshots
Tableau d'objets de capture d'écran avec src, type et sizes (semblable à l'objet icons) destiné à présenter la PWA. Il n'existe aucune restriction de taille.
categories
Tableau des catégories auxquelles la PWA doit appartenir à utiliser comme suggestions pour les fiches, éventuellement à partir de la liste des catégories connues. Ces valeurs sont généralement en minuscules.
iarc_rating_id
Le code de certification de la PWA (International Age Rating Coalition), le cas échéant Elle sert à déterminer les âges auxquels votre PWA est adaptée.

Vous pouvez voir ces champs promotionnels en action aujourd'hui. Sur Android, par exemple, si votre PWA peut être installée et que vous fournissez des valeurs pour au moins les champs description et screenshots, la boîte de dialogue d'installation passe d'une simple barre d'informations "Ajouter à l'écran d'accueil" à une boîte de dialogue d'installation plus riche semblable à celle d'une plate-forme de téléchargement d'applications.

Sur Android, vous pouvez obtenir une interface d'installation plus agréable si vous fournissez des valeurs pour les champs promotionnels, comme vous pouvez le voir dans la vidéo suivante.

Découvrez ces champs promotionnels en action:

Champs des fonctionnalités

Enfin, il existe un certain nombre de champs liés à différentes fonctionnalités que votre PWA peut utiliser dans les navigateurs compatibles, tels que les champs shortcuts, share_target et display_overrides, que nous aborderons dans le chapitre Fonctionnalités. Des champs, comme related_apps et prefer_related_apps (voir le chapitre Détection pour en savoir plus), permettent également de connecter votre PWA aux applications installées, souvent à partir d'une plate-forme de téléchargement d'applications.

De nombreux nouveaux champs pourront être ajoutés à l'avenir, tandis que les navigateurs ajouteront des fonctionnalités aux progressive web apps.

Ressources