Un manifiesto de aplicación web es un archivo JSON que le indica al navegador cómo debería comportarse tu app web progresiva (AWP) cuando se instale en la computadora de escritorio o en un dispositivo móvil del usuario. Como mínimo, un archivo de manifiesto típico incluye lo siguiente:
- El nombre de la app
- Los íconos que la app debe usar
- La URL que se debe abrir cuando se inicia la app
Cómo crear 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 (el directorio de nivel superior de tu sitio web). La especificación sugiere que la extensión debería ser .webmanifest
, pero te recomendamos que uses archivos JSON para que los manifiestos sean más claros de lectura.
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 el manifiesto. Si proporcionas ambos, se usa name
cuando se instala la app, y short_name
se usa en la pantalla principal, el selector o cualquier otro lugar donde el espacio sea limitado.
icons
Cuando un usuario instala tu AWP, puedes definir un conjunto de íconos para que el navegador use en la pantalla principal, el selector de aplicaciones, el selector de tareas, la pantalla de presentación y otros lugares.
La propiedad icons
es un array de objetos de imagen. Cada objeto debe incluir el src
, una propiedad sizes
y el type
de imagen. Para usar íconos enmascarables, a veces denominados íconos 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 uno de 512 x 512 píxeles. Si solo se proporcionan esos dos tamaños de íconos, Chrome ajustará automáticamente la escala de los íconos para que se ajusten al dispositivo. Si prefieres escalar tus propios íconos y ajustarlos para obtener una perfección de píxeles, proporciona íconos en incrementos de 48 dp.
id
La propiedad id
te permite definir de forma explícita el identificador que se usa para tu aplicación. Si agregas la propiedad id
al manifiesto, se quitará la dependencia de start_url
o de la ubicación del manifiesto, y podrás actualizarlas en el futuro. Para obtener más información, consulta Cómo identificar de forma única las AWP con la propiedad de ID de manifiesto de aplicación web.
start_url
start_url
es una propiedad obligatoria. Le indica al navegador dónde debe iniciarse la app cuando se inicia y evita que se inicie en cualquier página en la que se encontraba el usuario cuando agregó la app a la pantalla principal.
Tu start_url
debe dirigir al usuario directamente a tu app, no a una página de destino del producto. Piensa en lo que el usuario querrá hacer inmediatamente después de abrir tu app y colócalo allí.
background_color
La propiedad background_color
se usa en la pantalla de presentación cuando la aplicación se inicia en un dispositivo móvil por primera vez.
display
Puedes personalizar la IU del navegador que se muestra cuando se inicia tu app. Por ejemplo, puedes ocultar la barra de direcciones y los elementos de la interfaz de usuario del navegador. Incluso es posible hacer que se inicien juegos en pantalla completa. La propiedad display
toma uno de los siguientes valores:
Propiedad | Comportamiento |
---|---|
fullscreen |
Abre la app web sin ninguna IU del navegador y ocupa todo el área de visualización disponible. |
standalone |
Abre la app web de modo que tenga el aspecto de una app independiente. La app se ejecuta en su propia ventana, separada del navegador, y oculta los elementos estándar de la IU del navegador, como la barra de direcciones. |
minimal-ui |
Este modo es similar a standalone , pero proporciona al usuario un conjunto mínimo de elementos de la IU para controlar la navegación, como los botones para volver atrás y volver a cargar.
|
browser |
Una experiencia de navegador estándar |
display_override
Para elegir cómo se muestra la app web, configura un modo display
en su manifiesto como se explicó anteriormente. No es necesario que los navegadores admitan todos los modos de visualización, pero sí lo son para admitir la cadena de resguardo definida por especificaciones ("fullscreen"
→ "standalone"
→ "minimal-ui"
→ "browser"
). Si no admiten un modo determinado, regresan al siguiente modo de visualización en la cadena. En casos excepcionales, estos resguardos pueden causar problemas. Por ejemplo, un desarrollador no puede solicitar "minimal-ui"
sin verse obligado a volver al modo de visualización "browser"
cuando no se admite "minimal-ui"
. El comportamiento actual también hace que sea imposible introducir nuevos modos de visualización de una manera retrocompatible, ya que no tienen un lugar en la cadena de resguardo.
Puedes establecer tu propia secuencia de resguardo con la propiedad display_override
, que el navegador tiene en cuenta antes de la propiedad display
. Su valor es una secuencia de cadenas que se consideran en el orden de la lista y se aplica el primer modo de visualización admitido. Si no se admite ninguno, el navegador recurre a la evaluación del campo display
. Si no hay ningún campo display
, el navegador ignorará display_override
.
El siguiente es un ejemplo de cómo usar display_override
. Los detalles de "window-control-overlay"
están fuera del alcance de esta página.
{
"display_override": ["window-control-overlay", "minimal-ui"],
"display": "standalone",
}
Cuando se carga esta app, el navegador primero intenta usar "window-control-overlay"
. Si no está disponible, recurre a "minimal-ui"
y, luego, a "standalone"
desde la propiedad display
. Si no hay ninguno disponible, el navegador regresa a la cadena de resguardo estándar.
scope
El scope
de tu app es el conjunto de URLs que el navegador considera parte de ella. scope
controla la estructura de la URL que incluye todos los puntos de entrada y salida de la app, y el navegador la usa para determinar cuándo el usuario abandonó la app.
Otras notas sobre scope
:
- Si no incluyes un
scope
en tu manifiesto, lascope
implícita predeterminada será la URL de inicio, pero se quitarán su nombre de archivo, consulta y fragmento. - El atributo
scope
puede ser una ruta de acceso relativa (../
) o de un nivel superior (/
) 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 atributoscope
. - Un elemento
start_url
que comience 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 botones de cambio de tareas. El theme_color
debe coincidir con el color del tema meta
especificado en el encabezado del documento.
theme_color
en consultas de medios
Puedes ajustar theme_color
en una consulta de medios con el atributo media
del elemento de color de 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 estas preferencias en tu manifiesto. Para obtener más información, consulta el problema de 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 propiedad shortcuts
es un array de objetos de acceso directo a la app 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 carácter de puntos suspensivos. En Android, la descripción debe usar 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 el src
, una propiedad sizes
y el type
de la imagen. La propiedad form_factor
es opcional.
Puedes establecerlo en "wide"
para las capturas de pantalla aplicables únicamente a pantallas anchas o en "narrow"
solo para capturas de pantalla estrechas.
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 de la dimensión mínima.
- Todas las capturas de pantalla que coincidan con el factor de forma adecuado deben tener la misma relación de aspecto.
- A partir de Chrome 109, solo se muestran capturas de pantalla con
form_factor
establecido en"wide"
en computadoras de escritorio.
- A partir de Chrome 109, solo se muestran capturas de pantalla con
- A partir de Chrome 109, las capturas de pantalla con
form_factor
establecido en"wide"
se ignoran en Android. Se siguen mostrando capturas de pantalla sinform_factor
para brindar retrocompatibilidad.
En Chrome para computadoras de escritorio, se muestran al menos una y ocho capturas de pantalla como máximo que cumplen con estos criterios. El resto se ignora.
Chrome en Android muestra al menos una captura de pantalla y cinco como máximo que cumplen con estos criterios. El resto se ignora.
Agrega el manifiesto de la aplicación 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">
Cómo probar tu manifiesto
Para verificar que tu manifiesto esté configurado correctamente, usa el panel Manifiesto del panel Aplicación de las Herramientas para desarrolladores de Chrome.
En este panel, se proporciona una versión legible de muchas de las propiedades del manifiesto y te permite verificar que todas las imágenes se carguen correctamente.
Pantallas de presentación en dispositivos móviles
Cuando se inicia tu app por primera vez en un dispositivo móvil, el navegador puede tardar un momento en iniciarse y la renderización del contenido inicial. En lugar de mostrar una pantalla blanca que podría hacer que el usuario crea que la app no funciona, el navegador muestra una pantalla de presentación hasta el primer procesamiento de imagen.
Chrome crea automáticamente la pantalla de presentación a partir de los elementos name
, background_color
y icons
especificados en tu manifiesto. Para crear una transición fluida de la pantalla de presentación a la app, haz que background_color
tenga el mismo color que la página de carga.
Chrome elige el ícono que más coincida con la resolución del dispositivo para 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 una mejor coincidencia.
Lecturas adicionales
Para obtener información sobre otras propiedades que puedes agregar al manifiesto de tu app web, consulta la documentación del manifiesto de apps web de MDN.