Ajouter un fichier manifeste d'application Web

François Beaufort

Pete LePage

Thomas Steiner

Alexey Rodionov

Un fichier manifeste d'application Web est un fichier JSON qui indique au navigateur Les progressive web apps (PWA) doivent se comporter lorsqu'elles sont installées sur le bureau de l'utilisateur appareil mobile. Un fichier manifeste type inclut au minimum les éléments suivants:

• Nom de l'application
• Les icônes que l'application doit utiliser
• URL à ouvrir au lancement de l'application

Créer le fichier manifeste

Le fichier manifeste peut avoir n'importe quel nom, mais il est communément nommé manifest.json et servi à partir de la racine (répertoire de premier niveau de votre site Web). La spécification suggère que l'extension devrait être .webmanifest, mais vous pouvez utiliser JSON pour rendre vos fichiers manifestes plus clairs à lire.

Un fichier manifeste type se présente comme suit:

{
  "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"
    }
  ]
}

Propriétés clés du fichier manifeste

short_name et name

Vous devez fournir au moins l'un des éléments short_name ou name dans votre fichier manifeste. Si vous fournissez les deux, name est utilisé lorsque l'appli est installée, et short_name est utilisées sur l'écran d'accueil de l'utilisateur, dans le lanceur d'applications ou dans tout autre emplacement où l'espace sont limitées.

icons

Lorsqu'un utilisateur installe votre PWA, vous pouvez définir un ensemble d'icônes pour le navigateur à utiliser sur l'écran d'accueil, le lanceur d'applications, le sélecteur de tâches, l'écran de démarrage et dans à d'autres endroits.

La propriété icons est un tableau d'objets image. Chaque objet doit incluez src, une propriété sizes et le type de l'image. Pour utiliser 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 un Icône de 512 x 512 pixels Si seules ces deux tailles d'icônes sont fournies, redimensionne automatiquement les icônes pour les adapter à l'appareil. Si vous préférez adapter nos propres icônes, les ajuster au pixel près, fournir 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 mettre à jour à l'avenir. Pour en savoir plus, consultez Identifier de manière unique les PWA à l'aide de la propriété d'ID du fichier manifeste d'application Web.

start_url

start_url est une propriété obligatoire. Il indique au navigateur l'emplacement l'application doit démarrer lorsqu'elle est lancée et l'empêcher de démarrer la page sur laquelle se trouvait l'utilisateur quand il a ajouté votre application à son écran d'accueil.

Votre start_url doit rediriger l'utilisateur directement vers votre appli, et non vers un produit page de destination. Réfléchissez à ce que l'utilisateur voudra faire immédiatement après avoir ouvrez votre application et placez-les à cet endroit.

background_color

La propriété background_color est utilisée sur l'écran de démarrage lorsque le est lancée sur mobile pour la première fois.

display

Vous pouvez personnaliser l'interface utilisateur du navigateur à afficher lorsque votre application est lancée. Pour Par exemple, vous pouvez masquer la barre d'adresse et les éléments de l'interface utilisateur du navigateur. Jeux peuvent même être lancées en plein écran. La propriété display accepte l'une des valeurs suivantes : les valeurs suivantes:

Propriété	Comportement
fullscreen	Ouvre l'application Web sans interface utilisateur de navigateur et occupe toutes les la zone d'affichage disponible.
standalone	Ouvre l'application Web pour lui donner l'apparence d'une application autonome. L'application s'exécute dans sa propre fenêtre, distincte du navigateur, et masque les paramètres les éléments d'interface utilisateur du navigateur tels que la barre d'adresse. <ph type="x-smartling-placeholder"> </ph>
minimal-ui	Ce mode est semblable à standalone, mais fournit le utilisateur disposant d'un ensemble minimal d'éléments d'interface utilisateur pour contrôler la navigation, comme les boutons Retour et Actualiser. <ph type="x-smartling-placeholder"> </ph>
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 forcément compatibles avec tous les types d'écrans modes, mais ils sont nécessaires pour assurer la compatibilité chaîne de remplacement définie par les spécifications ("fullscreen" → "standalone" → "minimal-ui" → "browser"). Si ce n'est pas le cas, prennent en charge un mode donné, ils reviennent au mode d'affichage suivant dans la chaîne. Dans dans de rares cas, ces solutions peuvent causer des problèmes. Par exemple, un développeur ne peut pas demander "minimal-ui" sans être renvoyé de force dans l'écran "browser" lorsque "minimal-ui" n'est pas pris en charge. Le comportement actuel rend également impossible d'introduire de nouveaux modes d'affichage de manière rétrocompatible, car elles n'ont pas leur place dans la chaîne de créations de remplacement.

Vous pouvez définir votre propre séquence de remplacement à l'aide de la propriété display_override, que le navigateur considère avant la propriété display. Sa valeur est séquence de chaînes considérées dans l'ordre indiqué, et la première mode d'affichage pris en charge est appliqué. Si aucune n'est compatible, le navigateur bascule à 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" n'est pas dans le champ d'application pour cette page.

{
  "display_override": ["window-control-overlay", "minimal-ui"],
  "display": "standalone",
}

Lors du chargement de cette application, le navigateur tente d'utiliser "window-control-overlay" en premier. Si elle n'est pas disponible, la valeur utilisée est "minimal-ui", puis "standalone" à partir de la propriété display. Si aucune de ces options n'est disponible, la navigateur revient alors à la chaîne de remplacement standard.

scope

Le scope de votre application correspond à l'ensemble des URL que le navigateur considère comme faisant partie votre application. scope contrôle la structure d'URL, qui inclut toutes les entrées et sorties pointe vers l'application, et le navigateur s'en sert pour déterminer quand l'utilisateur a quitté la page l'application.

Autres remarques concernant scope:

• Si vous n'incluez pas de scope dans votre fichier manifeste, la valeur implicite par défaut scope 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 autre 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'accès défini dans l'attribut scope.
• Une 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 se refléter dans l'aperçu de l'application dans les sélecteurs de tâches. theme_color doit correspondre au Couleur du thème meta spécifiée dans l'en-tête de votre document.

</ph> <ph type="x-smartling-placeholder">

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ément de couleur du thème meta. Par exemple, vous pouvez définir une couleur pour le mode clair et une autre pour le mode sombre. Cependant, vous ne pouvez pas les définir préférences dans votre fichier manifeste. Pour en savoir plus, consultez 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 de raccourcis d'application. qui permettent d'accéder rapidement aux tâches clés de votre application. Chaque membre est un dictionnaire qui contient 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 le préfixe d'ellipse. Sur Android, la description doit également utiliser au maximum 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 le src, un sizes et le type de l'image. La propriété form_factor est facultative. Vous pouvez la définir sur "wide" pour les captures d'écran applicables aux écrans larges ou "narrow" uniquement pour les captures d'écran étroites.

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 form_factor est défini sur "wide" s'affichent sur les ordinateurs de bureau.
• À partir de Chrome 109, les captures d'écran avec form_factor défini sur "wide" sont ignorés sur Android. Les captures d'écran sans form_factor sont tout de même affichées pour la rétrocompatibilité.

Chrome sur ordinateur affiche au moins une et huit captures d'écran qui respectent ces critères. Les autres sont ignorées.

Chrome sur Android affiche au moins une et cinq captures d'écran qui respectent ces critères. Les autres sont ignorées.

</ph> <ph type="x-smartling-placeholder">

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 fichier 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) dans panneau Application des outils pour les développeurs Chrome.

</ph> <ph type="x-smartling-placeholder">

Ce volet fournit une version lisible d'un grand nombre de vos fichiers manifestes 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 un appareil mobile, le navigateur peut mettre un certain temps à s'afficher. et le contenu initial pour commencer à s'afficher. Au lieu d'afficher une écran blanc qui pourrait donner à l'utilisateur l'impression que l'application ne fonctionne pas, le navigateur affiche un écran de démarrage jusqu’au premier peinture.

Chrome crée automatiquement l'écran de démarrage à partir de name, background_color et icons spécifiés dans votre fichier manifeste. Pour créer un passer de l'écran de démarrage à l'application, faites de background_color la de la même couleur que celle de la page de chargement.

Chrome choisit l'icône qui se rapproche le plus de la résolution de l'appareil écrans de démarrage. Les icônes de 192 et 512 pixels suffisent dans la plupart des cas. mais vous pouvez fournir des icônes supplémentaires pour une meilleure correspondance.

Documentation complémentaire

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