Un fichier manifeste d'application Web est un fichier JSON qui indique au navigateur comment votre progressive web app (PWA) doit se comporter lorsqu'elle est installée sur l'ordinateur ou l'appareil mobile de l'utilisateur. Un fichier manifeste typique inclut au minimum les éléments suivants:
- Le nom de l'application
- Icônes que l'application doit utiliser
- URL à ouvrir au lancement de l'application
Créer le fichier manifeste
Le fichier manifeste peut porter n'importe quel nom, mais il est communément nommé manifest.json
et diffusé à partir de la racine (le répertoire de premier niveau de votre site Web). La spécification suggère que l'extension doit être .webmanifest
, mais vous pouvez utiliser des fichiers JSON pour que la lecture de vos fichiers manifestes soit plus claire.
Un fichier manifeste typique ressemble à ceci:
{
"short_name": "Weather",
"name": "Weather: Do I need an umbrella?",
"icons": [
{
"src": "/images/icons-vector.svg",
"type": "image/svg+xml",
"sizes": "512x512"
},
{
"src": "/images/icons-192.png",
"type": "image/png",
"sizes": "192x192"
},
{
"src": "/images/icons-512.png",
"type": "image/png",
"sizes": "512x512"
}
],
"id": "/?source=pwa",
"start_url": "/?source=pwa",
"background_color": "#3367D6",
"display": "standalone",
"scope": "/",
"theme_color": "#3367D6",
"shortcuts": [
{
"name": "How's the weather today?",
"short_name": "Today",
"description": "View weather information for today",
"url": "/today?source=pwa",
"icons": [{ "src": "/images/today.png", "sizes": "192x192" }]
},
{
"name": "How's the weather tomorrow?",
"short_name": "Tomorrow",
"description": "View weather information for tomorrow",
"url": "/tomorrow?source=pwa",
"icons": [{ "src": "/images/tomorrow.png", "sizes": "192x192" }]
}
],
"description": "Weather forecast information",
"screenshots": [
{
"src": "/images/screenshot1.png",
"type": "image/png",
"sizes": "540x720",
"form_factor": "narrow"
},
{
"src": "/images/screenshot2.jpg",
"type": "image/jpg",
"sizes": "720x540",
"form_factor": "wide"
}
]
}
Principales propriétés du fichier manifeste
short_name
et name
Vous devez fournir au moins short_name
ou name
dans votre fichier manifeste. Si vous fournissez les deux, name
est utilisé lorsque l'application est installée, et short_name
est utilisé sur l'écran d'accueil, dans le lanceur d'applications ou à tout autre endroit où l'espace est limité.
icons
Lorsqu'un utilisateur installe votre PWA, vous pouvez définir un ensemble d'icônes que le navigateur pourra utiliser sur l'écran d'accueil, le lanceur d'applications, le sélecteur de tâches, l'écran de démarrage et à d'autres endroits.
La propriété icons
est un tableau d'objets image. Chaque objet doit inclure le src
, une propriété sizes
et le type
de l'image. Pour utiliser des icônes masquables, parfois appelées icônes adaptatives sur Android, ajoutez "purpose": "any maskable"
à la propriété icon
.
Pour Chromium, vous devez fournir une icône d'au moins 192 x 192 pixels et une icône de 512 x 512 pixels. Si seules ces deux tailles d'icône sont fournies, Chrome redimensionne automatiquement les icônes pour les adapter à l'appareil. Si vous préférez mettre à l'échelle vos propres icônes et les ajuster pour qu'elles soient parfaites, fournissez des icônes par incréments de 48 dp.
id
La propriété id
vous permet de définir explicitement l'identifiant utilisé pour votre application. L'ajout de la propriété id
au fichier manifeste supprime la dépendance à start_url
ou à l'emplacement du fichier manifeste, et permet de les mettre à jour ultérieurement. Pour en savoir plus, consultez Identifier de manière unique les PWA avec la propriété d'ID du fichier manifeste d'application Web.
start_url
La propriété start_url
est obligatoire. Il indique au navigateur où votre application doit démarrer lorsqu'elle se lance, et l'empêche de démarrer à partir de la page sur laquelle l'utilisateur se trouvait lorsqu'il a ajouté votre application à son écran d'accueil.
Votre start_url
doit rediriger l'utilisateur directement vers votre application, et non vers la page de destination d'un produit. Réfléchissez à ce que l'utilisateur voudra faire immédiatement après avoir ouvert votre application et placez-le là-bas.
background_color
La propriété background_color
est utilisée sur l'écran de démarrage lorsque l'application est lancée pour la première fois sur mobile.
display
Vous pouvez personnaliser l'interface utilisateur du navigateur à afficher au lancement de votre application. Par exemple, vous pouvez masquer la barre d'adresse et les éléments de l'interface utilisateur du navigateur. Il est même possible de lancer
des jeux en plein écran. La propriété display
utilise l'une des valeurs suivantes:
Propriété | Comportement |
---|---|
fullscreen |
Ouvre l'application Web sans aucune interface utilisateur de navigateur et occupe toute la zone d'affichage disponible. |
standalone |
Ouvre l'application Web pour qu'elle ressemble à une application autonome. L'application s'exécute dans sa propre fenêtre, distincte du navigateur, et masque les éléments standards de l'interface utilisateur du navigateur, tels que la barre d'adresse. |
minimal-ui |
Ce mode est semblable à standalone , mais fournit à l'utilisateur un ensemble minimal d'éléments d'interface utilisateur pour contrôler la navigation, tels que les boutons "Retour" et "Actualiser".
|
browser |
Une expérience de navigation standard |
display_override
Pour choisir la façon dont votre application Web s'affiche, définissez un mode display
dans son fichier manifeste, comme expliqué précédemment. Les navigateurs ne sont pas obligés de prendre en charge tous les modes d'affichage, mais ils sont obligatoires pour prendre en charge la chaîne de remplacement définie par les spécifications ("fullscreen"
→ "standalone"
→ "minimal-ui"
→ "browser"
). S'ils ne prennent pas en charge un mode donné, ils reviennent au mode d'affichage suivant dans la chaîne. Dans de rares cas, ces solutions de remplacement peuvent causer des problèmes. Par exemple, un développeur ne peut pas demander "minimal-ui"
sans être contraint de repasser en mode d'affichage "browser"
lorsque "minimal-ui"
n'est pas compatible. Le comportement actuel rend également impossible l'introduction de nouveaux modes d'affichage de manière rétrocompatible, car ils n'ont pas leur place dans la chaîne de remplacement.
Vous pouvez définir votre propre séquence de remplacement à l'aide de la propriété display_override
, que le navigateur prend en compte avant la propriété display
. Sa valeur est une suite de chaînes considérées dans l'ordre listé. Le premier mode d'affichage compatible est appliqué. Si aucune option n'est acceptée, le navigateur revient à l'évaluation du champ display
. S'il n'y a pas de champ display
, le navigateur ignore display_override
.
Voici un exemple d'utilisation de display_override
. Les détails de "window-control-overlay"
ne sont pas abordés sur cette page.
{
"display_override": ["window-control-overlay", "minimal-ui"],
"display": "standalone",
}
Lors du chargement de cette application, le navigateur tente d'abord d'utiliser "window-control-overlay"
. Si ce n'est pas le cas, la propriété "minimal-ui"
est utilisée, puis "standalone"
dans la propriété display
. Si aucune de ces options n'est disponible, le navigateur revient à la chaîne de remplacement standard.
scope
Le scope
de votre application est l'ensemble des URL que le navigateur considère comme faisant partie de votre application. scope
contrôle la structure d'URL qui inclut tous les points d'entrée et de sortie de l'application. Le navigateur l'utilise pour déterminer à quel moment l'utilisateur a quitté l'application.
Autres remarques concernant scope
:
- Si vous n'incluez pas de
scope
dans votre fichier manifeste, l'scope
implicite par défaut est l'URL de démarrage, mais son nom de fichier, sa requête et son fragment ont été supprimés. - L'attribut
scope
peut être un chemin d'accès relatif (../
) ou tout chemin de niveau supérieur (/
) permettant d'augmenter la couverture des navigations dans votre application Web. - L'élément
start_url
doit être inclus dans le champ d'application. start_url
est relatif au chemin défini dans l'attributscope
.- Un élément
start_url
commençant par/
sera toujours la racine de l'origine.
theme_color
theme_color
définit la couleur de la barre d'outils et peut être reflétée dans l'aperçu de l'application dans les sélecteurs de tâches. Le theme_color
doit correspondre à la couleur du thème meta
spécifiée dans l'en-tête de votre document.
theme_color
dans les requêtes média
Vous pouvez ajuster theme_color
dans une requête média à l'aide de l'attribut media
de l'élément de couleur du thème meta
. Vous pouvez par exemple définir une couleur pour le mode clair et une autre pour le mode sombre. Toutefois, vous ne pouvez pas définir ces préférences dans votre fichier manifeste. Pour en savoir plus, consultez le problème GitHub w3c/manifest#975.
<meta name="theme-color" media="(prefers-color-scheme: light)" content="white">
<meta name="theme-color" media="(prefers-color-scheme: dark)" content="black">
shortcuts
La propriété shortcuts
est un tableau d'objets de raccourci d'application qui permet d'accéder rapidement aux tâches clés de votre application. Chaque membre est un dictionnaire contenant au moins un name
et un url
.
description
La propriété description
décrit la finalité de votre application.
Dans Chrome, la description ne doit pas dépasser 300 caractères sur toutes les plates-formes. Si la description est plus longue, le navigateur la tronque avec des points de suspension. Sur Android, la description ne doit pas dépasser sept lignes de texte.
screenshots
La propriété screenshots
est un tableau d'objets image représentant votre application dans des scénarios d'utilisation courants. Chaque objet doit inclure la src
, une propriété sizes
et le type
de l'image. La propriété form_factor
est facultative.
Vous pouvez le définir sur "wide"
pour les captures d'écran ne s'appliquant qu'aux écrans larges ou sur "narrow"
pour les captures d'écran de petite taille.
Dans Chrome, l'image doit répondre aux critères suivants:
- La largeur et la hauteur doivent être comprises entre 320 et 3 840 pixels.
- La dimension maximale ne peut pas être plus de 2,3 fois la longueur de la dimension minimale.
- Toutes les captures d'écran correspondant au facteur de forme approprié doivent avoir le même format.
- À partir de Chrome 109, seules les captures d'écran dont le
form_factor
est défini sur"wide"
s'affichent sur le bureau.
- À partir de Chrome 109, seules les captures d'écran dont le
- À partir de Chrome 109, les captures d'écran dont le
form_factor
est défini sur"wide"
sont ignorées sur Android. Les captures d'écran sansform_factor
s'affichent tout de même pour des raisons de rétrocompatibilité.
Sur ordinateur, Chrome affiche au moins une capture d'écran et au maximum huit qui répondent à ces critères. Les autres sont ignorés.
Chrome sur Android affiche au moins une capture d'écran et au maximum cinq qui répondent à ces critères. Les autres sont ignorées.
Ajouter le fichier manifeste de l'application Web à vos pages
Après avoir créé le fichier manifeste, ajoutez une balise <link>
à toutes les pages de votre progressive web app. Par exemple:
<link rel="manifest" href="/manifest.json">
Tester votre fichier manifeste
Pour vérifier que votre fichier manifeste est correctement configuré, utilisez le volet Manifest (Manifeste) du panneau Application des outils pour les développeurs Chrome.
Ce volet fournit une version lisible de la plupart des propriétés de votre fichier manifeste et vous permet de vérifier que toutes les images se chargent correctement.
Écrans de démarrage sur mobile
Lorsque votre application est lancée pour la première fois sur mobile, le navigateur et l'affichage du contenu initial peuvent prendre un certain temps. Au lieu d'afficher un écran blanc qui pourrait faire croire à l'utilisateur que l'application ne fonctionne pas, le navigateur affiche un écran de démarrage jusqu'au premier rendu.
Chrome crée automatiquement l'écran de démarrage à partir des éléments name
, background_color
et icons
spécifiés dans votre fichier manifeste. Pour créer une transition en douceur de l'écran de démarrage à l'application, utilisez background_color
de la même couleur que la page de chargement.
Chrome choisit l'icône qui correspond le mieux à la résolution de l'appareil pour les écrans de démarrage. Fournir des icônes de 192 et 512 pixels est suffisant dans la plupart des cas, mais vous pouvez fournir des icônes supplémentaires pour une meilleure correspondance.
Complément d'informations
Pour en savoir plus sur les autres propriétés que vous pouvez ajouter au fichier manifeste de votre application Web, consultez la documentation sur le fichier manifeste d'application Web MN.