Manifiesto de la aplicación web

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

  1. En el panel izquierdo, en Application, selecciona Manifest.
  2. Verifica los campos del manifiesto tal como los analiza el navegador.

Para Firefox

  1. Abre el Inspector.
  2. Ve a la pestaña Aplicación.
  3. Selecciona la opción Manifiesto en el panel izquierdo.
  4. 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, sizes y campos purpose opcionales, 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-ui o browser, 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 implementan standalone.
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_url como valor de resguardo. Ten en cuenta que, si cambias la start_url en 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.

El área segura marcada como un círculo centrado en un radio del 40% dentro del ícono cuadrado

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.

Un ícono que no es adecuado para un ícono enmascarable.

Esta imagen se podría usar con más padding.

El ícono con más padding es adecuado para las máscaras.

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.

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-color puede 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.

La misma AWP instalada en computadoras de escritorio con un color de tema diferente.

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.

Una AWP en la pantalla de presentación de Android que toma diferentes valores del manifiesto

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 en para inglés, pt-BR para portugués de Brasil o in para hindi.
dir
La dirección para mostrar campos de manifiesto compatibles con la dirección (como name, short_name y description). Los valores válidos son auto, ltr (de izquierda a derecha) y rtl (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 portrait o landscape de 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, type y sizes (similar al objeto icons) 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.

Recursos