El manifiesto de la aplicación web es un archivo que creas y que le indica al navegador cómo deseas que se muestre tu contenido web como una aplicación en el sistema operativo. El manifiesto puede incluir información básica, como el nombre, el ícono y el color del tema de la app; preferencias avanzadas, como la orientación deseada y los atajos de la app; y metadatos del catálogo, como capturas de pantalla.
Cada AWP debe incluir un solo manifiesto por aplicación, que generalmente se aloja en la carpeta raíz y que está vinculado a todas las páginas HTML desde las que se puede instalar la AWP. Su extensión oficial es .webmanifest, por lo que puedes nombrar tu manifiesto como app.webmanifest.
Cómo agregar un manifiesto de app web a tu AWP
Para crear un manifiesto de app web, primero crea un archivo de texto con un objeto JSON que contenga al menos un campo name con un valor de cadena:
app.webmanifest:
{
"name": "My First Application"
}
Sin embargo, crear el archivo no es suficiente, el navegador también debe saber que existe.
Cómo establecer vínculos a tu manifiesto
Para que el navegador conozca el manifiesto de tu app web, debes vincularlo a tu AWP con un elemento HTML <link> y el atributo rel establecido en manifest en todas las páginas HTML de tu AWP. Esto es similar a la forma en que vinculas una hoja de estilo CSS a un documento.
index.html:
<html lang="en">
<title>This is my first PWA</title>
<link rel="manifest" href="/app.webmanifest">
Cómo depurar el manifiesto
Para asegurarte de que el manifiesto esté configurado correctamente, puedes usar Inspector en Firefox y Herramientas para desarrolladores en todos los navegadores basados en Chromium.
Para navegadores Chromium
En Herramientas para desarrolladores
- En el panel izquierdo, en Application, selecciona Manifest.
- Verifica los campos del manifiesto tal como los analiza el navegador.
Para Firefox
- Abre el Inspector.
- Ve a la pestaña Aplicación.
- Selecciona la opción Manifiesto en el panel izquierdo.
- Verifica los campos del manifiesto tal como los analiza el navegador.
Cómo diseñar tu experiencia de AWP
Ahora que la AWP está conectada a su manifiesto, es hora de completar el resto de los campos para definir la experiencia de los usuarios.
Campos básicos
El primer conjunto de campos representa la información principal de tu AWP. Se usan para compilar el ícono y la ventana de la AWP instalada, y determinar cómo se inicia. Son los siguientes:
name- Nombre completo de tu AWP. Aparecerá junto con el ícono en la pantalla principal, el selector, la estación de carga o el menú del sistema operativo.
short_name- Opcional, un nombre más corto de tu AWP, que se usa cuando no hay espacio suficiente para mostrar el valor completo del campo
name. No puede superar los 12 caracteres para minimizar la posibilidad de que se trunque. icons- Array de objetos de ícono con
src,type,sizesy campospurposeopcionales, que describen qué imágenes deben representar a la AWP. start_url- Es la URL que la AWP debe cargar cuando el usuario la inicia desde el ícono instalado. Se recomienda una ruta de acceso absoluta, por lo que, si la página principal de tu AWP es la raíz de tu sitio, puedes establecerla en "/" para abrirla cuando se inicie la app. Si no proporcionas una URL de inicio, el navegador puede usar la URL desde la que se instaló la AWP como punto de partida. Puede ser un vínculo directo, como los detalles de un producto en lugar de la pantalla principal.
display- Uno de
fullscreen,standalone,minimal-uiobrowser, que describe cómo el SO debe dibujar la ventana de la AWP. Puedes obtener más información sobre los diferentes modos de visualización en el capítulo Diseño de apps. La mayoría de los casos de uso implementanstandalone. id- Es una cadena que identifica de forma única a esta AWP de otras que pueden estar alojadas en el mismo origen. Si no se establece, se usará
start_urlcomo valor de resguardo. Ten en cuenta que, si cambias lastart_urlen el futuro (como cuando cambies el valor de una cadena de consulta), es posible que el navegador no pueda detectar que ya se instaló una AWP.
Íconos
El ícono de tu AWP es su identidad visual en los dispositivos de tus usuarios cuando se instala, por lo que es importante definir al menos uno. Debido a que la propiedad icons es una colección de objetos de íconos, puedes definir varios íconos en diferentes formatos para brindar la mejor experiencia de íconos a tus usuarios. Cada navegador elegirá uno o más íconos según sus necesidades y el sistema operativo en el que está instalado, los íconos más cercanos a las especificaciones necesarias.
Si necesitas elegir un solo tamaño de ícono, este debe ser de 512 por 512 píxeles. Sin embargo, se recomienda proporcionar más tamaños, incluidas imágenes de 192 × 192, 384 × 384 y 1,024 × 1,024 píxeles.
"icons": [
{
"src": "icons/512.png",
"type": "image/png",
"sizes": "512x512"
},
{
"src": "icons/1024.png",
"type": "image/png",
"sizes": "1024x1024"
}
]
Si no proporcionas un ícono o los íconos no tienen los tamaños recomendados, en algunas plataformas no aprobarás los criterios de instalación. En otras plataformas, el ícono se generará automáticamente, por ejemplo, a partir de una captura de pantalla de la AWP o con un ícono genérico.
Íconos enmascarables
Algunos sistemas operativos, como Android, adaptan los íconos a diferentes tamaños y formas. Por ejemplo, en Android 12, diferentes fabricantes o parámetros de configuración pueden cambiar la forma de los íconos de círculos a cuadrados o cuadrados con esquinas redondeadas. Para admitir este tipo de íconos adaptables, puedes proporcionar un ícono enmascarable con el campo purpose.
Para ello, proporciona un archivo de imagen cuadrada que tenga el ícono principal contenido en una "zona segura", un círculo centrado en el ícono con un radio del 40% de la anchura del ícono. (consulta la imagen a continuación). Los dispositivos que admiten íconos enmascarables enmascararán tu ícono según sea necesario.
Este es un ejemplo de un ícono que se puede enmascarar renderizado en varias formas de uso general:
En la siguiente imagen, si usas el ícono de la izquierda como un ícono adaptable, obtendrás resultados deficientes en los dispositivos cuando se aplique una máscara de forma.
Esta imagen se podría usar con más padding.
Los íconos enmascarables deben tener un tamaño mínimo de 512 × 512. Cuando crees uno, podrás agregarlo a tu colección de icons para mejorar la experiencia de los dispositivos 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"
},
]
En la mayoría de los casos, si tu ícono enmascarable no se muestra bien, puedes agregar más padding para mejorarlo. Maskable.app es una herramienta en línea gratuita para probar y crear una versión enmascarable de tu ícono.
Campos recomendados
El siguiente conjunto de campos que debes incluir son los que mejorarán la experiencia del usuario, aunque no sean obligatorios para la instalabilidad.
theme_color- Es el color predeterminado de la aplicación, que a veces afecta la forma en que el SO muestra el sitio (por ejemplo, el color de la ventana y la barra del título en computadoras de escritorio, o el color de la barra de estado en dispositivos móviles). El elemento HTML
<meta>theme-colorpuede anular este color. background_color- Es el color del marcador de posición que se mostrará en el fondo de la aplicación antes de que se cargue su hoja de estilo. Actualmente, Safari en iOS y iPadOS, y la mayoría de los navegadores de escritorio, ignora este campo.
scope- Cambia el alcance de navegación de la AWP, lo que te permite definir qué se muestra y qué no en la ventana de la app instalada. Por ejemplo, si vinculas a una página fuera del alcance, se renderizará en un navegador integrado en la app en lugar de en la ventana de la AWP. Sin embargo, esto no cambiará el alcance de tu service worker.
En la siguiente imagen, se muestra cómo se usa el campo theme_color para la barra del título en un dispositivo de escritorio cuando instalas una AWP.
Cuando definas colores en el manifiesto, como dentro de theme_color y background_color, debes usar colores con nombres de CSS, como salmon o orange, colores RGB, como #FF5500, o funciones de color sin transparencia, como rgb() o hsl(). Consulta el capítulo de diseño de apps para obtener más información.
Probar
Pantallas de presentación
En algunos dispositivos, se renderiza una imagen estática mientras se carga tu AWP para proporcionarle comentarios inmediatos al usuario.
Android usa los valores theme_color, background_color y icon para generar la pantalla de presentación.
Cuando instales una AWP en Android, el dispositivo generará una pantalla de presentación con la información que proviene de tu manifiesto, como se muestra en el siguiente diagrama.
Por otro lado, Safari en iOS y iPadOS no usa el manifiesto de la app web para generar pantallas de presentación. En cambio, usan una imagen vinculada desde un elemento <link> propio de manera similar a cómo se manejan los íconos. Consulta el capítulo Mejoras para obtener más detalles.
Campos extendidos
El siguiente conjunto de campos ofrece información adicional sobre tu AWP. Todas son opcionales.
lang- Es una etiqueta de idioma que especifica el idioma principal de los valores del manifiesto, como
enpara inglés,pt-BRpara portugués de Brasil oinpara hindi. dir- La dirección para mostrar campos de manifiesto compatibles con la dirección (como
name,short_nameydescription). Los valores válidos sonauto,ltr(de izquierda a derecha) yrtl(de derecha a izquierda). orientation- Es la orientación deseada para la app una vez instalada. Un juego puede configurar esto para solicitar una orientación solo horizontal. Se aceptan varios valores, pero si se incluyen, suele ser
portraitolandscapede forma explícita.
Campos promocionales
El cuarto conjunto de campos te permite proporcionar información promocional sobre tu AWP, por ejemplo, en los flujos de instalación, las fichas y los resultados de la búsqueda.
description- Una explicación de lo que hace la AWP.
screenshots- Es un array de objetos de captura de pantalla con
src,typeysizes(similar al objetoicons) destinado a mostrar la AWP. No hay restricciones de tamaño. categories- Array de categorías a las que debe pertenecer la AWP para usar como sugerencias para las fichas, opcionalmente de la lista de categorías conocidas. Por lo general, estos valores están en minúsculas.
iarc_rating_id- El código de certificación de la AWP de la Coalición Internacional de Clasificación por Edad (si tienes uno) Está diseñado con el fin de determinar para qué edades es adecuada tu AWP.
Puedes ver estos campos promocionales en acción hoy mismo. En Android, por ejemplo, si tu AWP se puede instalar y proporcionas valores para, al menos, los campos description y screenshots, la experiencia del diálogo de instalación se transforma de una simple barra de información "Agregar a la pantalla principal" a un diálogo de instalación más rico, similar al de una tienda de aplicaciones.
En Android, puedes obtener una IU de instalación más atractiva si proporcionas valores para los campos promocionales, como se muestra en el siguiente video.
Consulta estos campos promocionales en acción:
Campos de capacidades
Por último, hay varios campos relacionados con diferentes funciones que tu AWP puede usar en navegadores compatibles, como los campos shortcuts, share_target y display_override, como se explica en el capítulo Funciones. También hay campos, como related_apps y prefer_related_apps (consulta el capítulo Detección para obtener más información), que permiten conectar tu AWP a las apps instaladas, a menudo desde una tienda de aplicaciones.
Es posible que aparezcan muchos campos nuevos en el futuro, mientras que los navegadores agregan más capacidades a las apps web progresivas.