Agrega un manifiesto de aplicación web

François Beaufort

Pete LePage

Thomas Steiner

Alexey Rodionov

Navegadores compatibles

• (39)
• (79)
• ×
• (17)

Origen

Un manifiesto de aplicación web es un archivo JSON que le indica al navegador cómo se La app web progresiva (AWP) debería comportarse cuando se instale en el escritorio del usuario o dispositivo móvil. Como mínimo, un archivo de manifiesto típico incluye lo siguiente:

• Nombre de la app
• Los íconos que debe usar la app
• La URL que se debe abrir cuando se inicia la app

Crea el archivo de manifiesto

El archivo de manifiesto puede tener cualquier nombre, pero comúnmente se llama manifest.json y se entrega desde la raíz (directorio de nivel superior de tu sitio web). La especificación sugiere que la extensión debería ser .webmanifest, pero es posible que quieras usar JSON para que la lectura de los manifiestos sea más clara.

Un manifiesto típico tiene el siguiente aspecto:

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

Propiedades clave del manifiesto

short_name y name

Debes proporcionar al menos uno de los valores short_name o name en tu manifiesto. Si tú proporcionas ambos, name se usa cuando la app está instalada, y short_name es se use en la pantalla principal del usuario, en el selector o en otros lugares donde haya espacio limitado.

Nota: Por lo general, los sistemas operativos esperan tener un título para cada ventana de la app. Esta el título se muestra en varias plataformas de cambio de ventana, como alt+tab, el modo de vista general y la lista de ventanas de la biblioteca. Para las AWP que se ejecutan en modo independiente, Chromium agrega el short_name (o, si no está disponible, el name) a la inicio del <title> del documento HTML para evitar ataques de ocultamiento en los que las apps independientes podrían confundirse, por ejemplo, con sistemas operativos los diálogos. Para ayudar a mantener tu app segura, no repitas el nombre de la app en la <title> para el modo independiente.

icons

Cuando un usuario instala tu AWP, puedes definir un conjunto de íconos para el navegador para usar en la pantalla principal, el selector de aplicaciones, el selector de tareas, la pantalla de presentación y en otros lugares.

La propiedad icons es un array de objetos de imagen. Cada objeto debe incluye src, una propiedad sizes y el type de la imagen. Para usar íconos enmascarables, a veces denominados adaptables en Android, agrega "purpose": "any maskable" a la propiedad icon.

Para Chromium, debes proporcionar un ícono de al menos 192 x 192 píxeles y una Ícono de 512 x 512 píxeles Si solo se proporcionan esos dos tamaños de íconos, Chrome ajusta automáticamente los iconos para que se ajusten al dispositivo. Si prefieres escalar propios íconos y ajustarlos para que sean perfectos, proporcionar íconos en incrementos de 48 dp.

Nota: Los navegadores basados en Chromium también admiten íconos SVG que se pueden escalar. de manera arbitraria sin verse pixelada y que admiten funciones avanzadas como capacidad de respuesta a prefers-color-scheme. Sin embargo, estos íconos permanecen en el estado en el que se encontraban en el momento de la instalación, en lugar de actualizando en vivo. Para usar íconos SVG de forma segura, especifica siempre un ícono rasterizado como y resguardo para navegadores que no admiten íconos SVG.

id

La propiedad id te permite definir de forma explícita el identificador que se usa para tu y mantener la integridad de su aplicación. Si agregas la propiedad id al manifiesto, se quitará la dependencia de el start_url o la ubicación del manifiesto, y permite actualizar sobre ellos en el futuro. Para obtener más información, consulta Identificación única de las AWP con la propiedad del ID del manifiesto de la aplicación web.

start_url

start_url es una propiedad obligatoria. Le indica al navegador dónde la app debería iniciarse cuando se inicia y evita que se inicie en en la página en la que estaba el usuario cuando agregó tu app a la pantalla principal.

Tu start_url debe dirigir al usuario directamente a tu app, no a un producto. la página de destino. Piensa en lo que el usuario querrá hacer inmediatamente después de abre tu app y colócalos allí.

background_color

La propiedad background_color se usa en la pantalla de presentación cuando la aplicación se lanza en el dispositivo móvil por primera vez.

display

Puedes personalizar la IU del navegador que se muestra cuando se inicia tu app. Para Por ejemplo, puedes ocultar la barra de direcciones y los elementos de la interfaz de usuario del navegador. Juegos incluso para que se abran en pantalla completa. La propiedad display toma uno de los siguientes valores:

Propiedad	Comportamiento
fullscreen	Abre la aplicación web sin ninguna IU del navegador y ocupa todas las área de visualización disponible.
standalone	Abre la aplicación web para verse y sentirse como una aplicación independiente. La app se ejecuta en su propia ventana, separada del navegador, y oculta de la IU del navegador, como la barra de direcciones. La IU independiente.
minimal-ui	Este modo es similar a standalone, pero proporciona la con un conjunto mínimo de elementos de la IU para controlar la navegación como los botones para volver y volver a cargar. La IU mínima.
browser	Una experiencia de navegador estándar

display_override

Para elegir cómo se muestra tu app web, establece un modo display en su manifiesto como se explicó anteriormente. No es necesario que los navegadores admitan todas las pantallas pero son necesarios para admitir la cadena de resguardo definida por especificaciones ("fullscreen" → "standalone" → "minimal-ui" → "browser"). Si no lo hacen, admiten un modo determinado, recurren al siguiente modo de visualización de la cadena. En en casos excepcionales, estos resguardos pueden causar problemas. Por ejemplo, un desarrollador no puede solicitar "minimal-ui" sin que se te redireccione de nuevo a la pantalla "browser" cuando "minimal-ui" no es compatible. El comportamiento actual también hace que es imposible introducir nuevos modos de visualización de una manera retrocompatible porque no tienen un lugar en la cadena de resguardo.

Puedes establecer tu propia secuencia de resguardo con la propiedad display_override. que el navegador considera antes de la propiedad display. Su valor es un de cadenas de texto que se consideran en el orden enumerado, y el primer se aplica el modo de visualización admitido. Si no se admite ninguno, el navegador recurre para evaluar el campo display. Si no hay un campo display, el navegador Ignora display_override.

El siguiente es un ejemplo de cómo usar display_override. Los detalles de "window-control-overlay" están fuera del permiso de esta página.

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

Cuando se carga esta app, el navegador intenta usar "window-control-overlay" antes de empezar. Si no está disponible, recurre a "minimal-ui" y, luego, a "standalone" de la propiedad display. Si ninguna de estas opciones está disponible, navegador y, luego, regresa a la cadena de resguardo estándar.

scope

El elemento scope de tu app es el conjunto de URLs que el navegador considera parte tu app. scope controla la estructura de la URL que incluye todas las entradas y salidas. apunta a la aplicación, y el navegador la usa para determinar cuándo el usuario se va la aplicación.

Precaución: Si el usuario hace clic en un vínculo de tu app que navega fuera de scope, el vínculo se abre y se renderiza dentro de la ventana de la AWP existente. Si quieres el vínculo para abrirlo en una pestaña del navegador, agrega target="_blank" a la etiqueta <a>. Activada Android, los vínculos con target="_blank" se abren en una pestaña personalizada de Chrome.

Otras notas sobre scope:

• Si no incluyes un scope en tu manifiesto, el valor predeterminado scope es la URL de inicio, pero sin su nombre de archivo, consulta y fragmento.
• El atributo scope puede ser una ruta de acceso relativa (../) o cualquier nivel superior. ruta (/) que permitiría un aumento en la cobertura de las navegaciones en tu app web.
• El start_url debe estar dentro del alcance.
• El start_url está relacionado con la ruta de acceso definida en el atributo scope.
• Un start_url que comienza con / siempre será la raíz del origen.

theme_color

theme_color establece el color de la barra de herramientas y se puede reflejar en la vista previa de la app en los selectores de tareas. theme_color debe coincidir con Se especificó el color de tema meta en el encabezado de tu documento.

Ejemplo de una ventana de AWP con theme_color personalizado.

theme_color en consultas de medios

Navegadores compatibles

• (93)
• (93)
• 106
• (15)

Origen

Puedes ajustar theme_color en una consulta de medios con el atributo media de la Elemento de color del tema meta. Por ejemplo, puedes definir un color para el modo claro. y otro para el modo oscuro de esta manera. Sin embargo, no puedes definir preferencias en tu manifiesto. Para obtener más información, consulta el problema w3c/manifest#975 de GitHub.

<meta name="theme-color" media="(prefers-color-scheme: light)" content="white">
<meta name="theme-color" media="(prefers-color-scheme: dark)"  content="black">

shortcuts

La propiedad shortcuts es un array de acceso directo a apps. objetos que proporcionan acceso rápido a tareas clave dentro de tu app. Cada miembro es un diccionario que contiene al menos un name y un url.

description

La propiedad description describe el propósito de tu app.

En Chrome, la longitud máxima de la descripción es de 300 caracteres en todas las plataformas. Si la descripción es más larga, el navegador la trunca con un elipsis. En Android, la descripción también debe incluir un máximo de siete líneas de texto.

screenshots

La propiedad screenshots es un array de objetos de imagen que representan tu app. en situaciones de uso comunes. Cada objeto debe incluir src, un sizes y el type de la imagen. La propiedad form_factor es opcional. Puedes establecerlo en "wide" para las capturas de pantalla aplicables a pantallas panorámicas. o "narrow" solo para capturas de pantalla angostas.

En Chrome, la imagen debe cumplir con los siguientes criterios:

• El ancho y la altura deben ser de 320 px como mínimo y 3840 px como máximo.
• La dimensión máxima no puede ser más de 2.3 veces la longitud del mínimo dimensión.
• Todas las capturas de pantalla que coincidan con el factor de forma apropiado deben tener la misma relación de aspecto.
  • A partir de Chrome 109, solo las capturas de pantalla con form_factor establecido en "wide" se muestran en computadoras.
• A partir de Chrome 109, se mostrarán las capturas de pantalla con el form_factor establecido en "wide" ignorados en Android. Aún se muestran capturas de pantalla sin form_factor retrocompatibilidad.

Chrome en computadoras de escritorio muestra al menos una y, como máximo, ocho capturas de pantalla que cumplen con los estos criterios. Se ignora el resto.

Chrome en Android muestra al menos una y, como máximo, cinco capturas de pantalla que cumplan con estos criterios. Se ignora el resto.

IU de instalación más completa en computadoras y dispositivos móviles

Agrega el manifiesto de app web a tus páginas

Después de crear el manifiesto, agrega una etiqueta <link> a todas las páginas de tu App web progresiva Por ejemplo:

<link rel="manifest" href="/manifest.json">

La solicitud del manifiesto se realiza sin credenciales, incluso si están en el mismo dominio. Si el manifiesto requiere credenciales, debes incluir crossorigin="use-credentials" en la etiqueta del manifiesto.

Prueba tu manifiesto

Para verificar que tu manifiesto esté configurado correctamente, usa el panel Manifest en Panel Application de Chrome Herramientas para desarrolladores.

Prueba tu manifiesto en Herramientas para desarrolladores.

Este panel proporciona una versión en lenguaje natural de muchos de los archivos y permite verificar que todas las imágenes se carguen correctamente.

Pantallas de presentación en dispositivos móviles

Cuando tu app se inicia por primera vez en un dispositivo móvil, el navegador puede tardar un momento para que se inicie y el contenido inicial para comenzar a renderizarlo. En lugar de mostrar pantalla blanca que podría hacer creer que la aplicación no funciona, el navegador muestra una pantalla de presentación hasta que se aplique la primera pintura.

Chrome crea automáticamente la pantalla de presentación desde el name, background_color y icons especificados en tu manifiesto. Para crear un patrón de la pantalla de presentación a la app, te background_color del mismo color que la de la página de carga.

Chrome elige el ícono que más coincida con la resolución del dispositivo para la en las pantallas de presentación. Proporcionar íconos de 192 y 512 píxeles es suficiente para la mayoría de los casos, pero puedes proporcionar íconos adicionales para mejorar la coincidencia.

Lecturas adicionales

Para obtener información sobre otras propiedades que puedes agregar al manifiesto de tu app web, consulta Documentación del manifiesto de apps web de MDN