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 accesos directos a aplicaciones y metadatos del catálogo, como las 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 asignarle a tu manifiesto un nombre 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"
}

Pero 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 reconozca 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 la AWP. Esto es similar a cómo se vincula 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 Application.
  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 la experiencia de una 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 sobre 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, el Dock o el menú del sistema operativo.
short_name
Opcional (es decir, un nombre más corto de la AWP) que se usa cuando no hay suficiente espacio 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
La URL que la AWP debe cargar cuando el usuario la inicie desde el ícono instalado. Se recomienda una ruta de acceso absoluta; por lo tanto, si la página principal de tu AWP es la raíz de tu sitio, puedes establecer esto en "/" para abrirlo cuando se inicia la app. Si no proporcionas una URL de inicio, el navegador puede usar la URL desde la que se instaló la AWP como inicio. Puede ser un vínculo directo, como los detalles de un producto, en lugar de tu pantalla principal.
display
Un elemento 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 configura, 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 todas las plataformas cuando se instalan, así que es importante definir al menos uno. Como la propiedad icons es una colección de objetos de ícono, puedes definir varios íconos en diferentes formatos para brindar la mejor experiencia de ícono a tus usuarios. Cada navegador elegirá uno o más iconos en función de sus necesidades y del sistema operativo en el que esté instalado, los iconos 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 por 192, 384 por 384 y 1024 por 1024 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 estos no tienen el tamaño recomendado, en algunas plataformas no cumplirás con 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 mediante 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 cuadrado que tenga su ícono principal dentro de una “zona segura”, un círculo centrado en el ícono con un radio del 40% del ancho del ícono. (consulte la imagen a continuación). Los dispositivos que admiten íconos enmascarables enmascaran 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 enmascarable renderizado en varias formas de uso general:

En la siguiente imagen, si usas el ícono de la izquierda como un ícono enmascarable, obtendrás malos resultados 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 hacer que se pueda usar con más padding.

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

Los íconos enmascarables deben tener, como mínimo, 512 por 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 el ícono enmascarable no se muestra correctamente, puedes mejorarlo agregando más padding. 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 son obligatorios para la instalación.

theme_color
El color predeterminado de la app, que a veces afecta la forma en que el SO muestra el sitio (por ejemplo, el color de la ventana y la barra de título en computadoras de escritorio o el color de la barra de estado en dispositivos móviles). Este color se puede anular con el elemento HTML theme-color <meta>.
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 dentro de la ventana de la app instalada. Por ejemplo, si vinculas una página fuera del alcance, se renderizará en un navegador integrado en la app y no en la ventana de tu 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 de 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 defines colores en el manifiesto, como dentro de theme_color y background_color, debes usar colores con nombre de CSS, como salmon o orange, colores RGB (como #FF5500) o funciones de color sin transparencia, como rgb() o hsl(). Consulta el capítulo 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 instalas una AWP en Android, el dispositivo genera 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 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
Es la dirección en la que se muestran los 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
La orientación deseada de 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
Array de objetos de captura de pantalla con src, type y sizes (similares al objeto icons) destinados 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 es instalable y proporcionas valores para, al menos, los campos description y screenshots, la experiencia de diálogo de instalación se transforma de una simple función "Agregar a la pantalla principal" o la barra de información, hasta un diálogo de instalación más completo, 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 puedes ver en el siguiente video.

Observa estos campos promocionales en acción:

Campos de capacidades

Por último, hay una serie de campos relacionados con diferentes capacidades que tu AWP puede usar en navegadores compatibles, como los campos shortcuts, share_target y display_overrides, tal 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) para conectar tu AWP a apps instaladas, por lo general 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