Le fichier manifeste d'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, son icône et la couleur du thème. les préférences avancées, telles que l'orientation souhaitée et les raccourcis d'application ; et les métadonnées du catalogue, comme des captures d'écran.
Chaque PWA doit inclure un seul fichier manifeste par application, généralement hébergé dans le dossier racine et lié à 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 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, la création du fichier n'est pas suffisante. Le navigateur doit également savoir qu'il existe.
Créer un lien vers votre fichier manifeste
Pour que le navigateur reconnaisse 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. Cette opération s'apparente à l'association d'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
- Dans le volet de gauche, sous Application, sélectionnez Manifest.
- Vérifiez les champs du fichier manifeste analysés par le navigateur.
Pour Firefox
- Ouvrez l'outil d'inspection.
- Accédez à l'onglet Application.
- Sélectionnez l'option "Fichier manifeste" dans le panneau de gauche.
- 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 de base concernant votre PWA. Ils permettent de créer l'icône et la fenêtre de la PWA installée et de déterminer son mode de démarrage. Les voici :
name- Nom complet de votre PWA. Elle s'affichera avec l'icône sur l'écran d'accueil, le lanceur d'applications, le dock ou le menu du système d'exploitation.
short_name- Facultatif. Nom plus court de votre PWA, utilisé lorsque l'espace est insuffisant pour afficher la valeur complète du champ
name. Il ne doit pas dépasser 12 caractères pour réduire le risque de troncation. icons- Tableau d'objets "Icône" avec
src,type,sizeset les champs facultatifspurposedé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 d'installation. Un chemin d'accès absolu est recommandé. Par conséquent, si la page d'accueil de votre PWA correspond à la racine de votre site, vous pouvez le 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, comme les détails d'un produit, plutôt que vers votre écran d'accueil.
displayfullscreen,standalone,minimal-uioubrowser, décrivant comment le système d'exploitation doit afficher la fenêtre de la PWA. Pour en savoir plus sur les différents modes d'affichage, consultez le chapitre Conception de l'application. La plupart des cas d'utilisation mettent en œuvrestandalone.id- Chaîne identifiant de manière unique cette PWA par rapport à d'autres PWA pouvant être hébergées sur la même origine. Si elle n'est pas définie,
start_urlest utilisé comme valeur de remplacement. Gardez à l'esprit qu'en modifiantstart_urlultérieurement (par exemple, en modifiant 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 est son identité visuelle pour l'ensemble des utilisateurs appareils lorsqu'ils sont installés. Il est donc important d'en définir au moins un. La propriété icons étant un ensemble d'objets "icon" (icône), vous pouvez définir plusieurs icônes dans différents formats afin d'offrir la meilleure expérience utilisateur possible. Chaque navigateur choisit une ou plusieurs icônes en fonction de ses besoins et du système d'exploitation sur lequel il est installé (les icônes les plus proches des spécifications requises).
Si vous devez choisir une seule taille d'icône, elle doit être de 512 x 512 pixels. Toutefois, nous vous recommandons d'ajouter d'autres tailles, y compris des images de 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 sont pas aux tailles recommandées, sur certaines plates-formes, vous ne respecterez pas les critères d'installation. Sur d'autres plates-formes, l'icône est générée automatiquement, par exemple à partir d'une capture d'écran de la PWA ou à l'aide d'une icône générique.
Icônes masquables
Certains systèmes d'exploitation, comme Android, adaptent les icônes à différentes tailles et formes. Par exemple, sous Android 12, différents fabricants ou paramètres peuvent modifier la forme des icônes, en passant par des cercles, des carrés ou des 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 est contenue dans une "zone de sécurité". Il s'agit d'un cercle centré dans l'icône dont le rayon est égal à 40 % de la largeur de l'icône. (voir l'image ci-dessous). Les appareils qui acceptent les icônes masquables le masquent si nécessaire.
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 de gauche comme icône masquable, les résultats obtenus sur les appareils seront médiocres lors de l'application d'un masque de forme.
Cette image pourrait être utilisée avec plus de marge intérieure.
Les icônes machables doivent avoir une taille minimale de 512 x 512. Une fois que vous avez créé une liste, vous pouvez l'ajouter à votre collection icons afin d'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 permettant de tester et de créer une version masquable de votre icône.
Champs recommandés
Le prochain ensemble de champs à inclure permettra d'améliorer l'expérience utilisateur, même s'ils ne sont pas obligatoires pour l'installation.
theme_color- 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 ordinateur 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. Ce champ est actuellement ignoré par Safari sur iOS, iPadOS et la plupart des navigateurs pour ordinateur.
scope- Modifie le champ d'application de navigation de la PWA, ce qui vous permet de définir ce qui est affiché ou non dans la fenêtre de l'application installée. Par exemple, si vous créez un lien vers une page en dehors du champ d'application, elle s'affichera dans un navigateur intégré à l'application plutôt que 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 de bureau lorsque vous installez une PWA.
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, comme salmon ou orange, des couleurs RVB telles que #FF5500, ou des fonctions de couleur sans transparence telles que rgb() ou hsl(). Pour en savoir plus, consultez le chapitre 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 un retour immédiat à 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.
En revanche, Safari sur iOS et iPadOS n'utilise pas le fichier manifeste d'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 semblable à la façon dont ils gèrent les icônes. Pour en savoir plus, consultez le chapitre "Améliorations".
Champs étendus
Les champs suivants fournissent 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
enpour l'anglais,pt-BRpour le portugais du Brésil ouinpour l'hindi. dir- Direction de l'affichage des champs de fichier manifeste compatibles avec la direction (par exemple,
name,short_nameetdescription). Les valeurs valides sontauto,ltr(de gauche à droite) etrtl(de droite à gauche). orientation- Orientation souhaitée pour l'application une fois installée. Un jeu peut définir cette option pour demander une orientation en mode paysage uniquement. Plusieurs valeurs sont acceptées, mais si vous les renseignez, il s'agit généralement de
portraitoulandscapeexplicitement.
Champs promotionnels
Le quatrième ensemble de champs vous permet de fournir des informations promotionnelles concernant votre PWA, par exemple dans les parcours d'installation, les fiches et les résultats de recherche.
description- Explication du fonctionnement de la PWA.
screenshots- Tableau d'objets de capture d'écran avec
src,typeetsizes(semblable à l'objeticons) destiné à présenter la PWA. Il n'y a aucune restriction de taille. categories- Tableau des catégories auxquelles la PWA doit appartenir pour servir d'indices aux fiches, éventuellement à partir de la liste des catégories connues. Ces valeurs sont généralement en minuscules.
iarc_rating_id- Code de certification de l'International Age Rating Coalition pour la PWA, le cas échéant. Elle sert à déterminer les tranches d'âge auxquelles votre PWA est appropriée.
Vous pouvez voir ces champs promotionnels en action dès aujourd'hui. Sur Android, par exemple, si votre PWA est installable et que vous fournissez des valeurs pour au moins les champs description et screenshots, la boîte de dialogue d'installation passe d'un simple "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 conviviale si vous fournissez des valeurs pour les champs promotionnels, comme vous pouvez le voir dans la vidéo suivante.
Découvrez comment fonctionnent ces champs promotionnels:
Champs des fonctionnalités
Enfin, il existe un certain nombre de champs associés aux différentes fonctionnalités que votre PWA peut utiliser dans les navigateurs compatibles, tels que les champs shortcuts, share_target et display_overrides, comme nous l'avons vu dans le chapitre Fonctionnalités. Il existe également des champs, comme related_apps et prefer_related_apps (voir le chapitre Détection pour en savoir plus) pour connecter votre PWA aux applications installées, souvent à partir d'une plate-forme de téléchargement d'applications.
De nombreux nouveaux champs pourraient apparaître à l'avenir pendant que les navigateurs ajoutent des fonctionnalités aux progressive web apps.