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 quieres 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 apps; y metadatos del catálogo, como capturas de pantalla.

Cada AWP debe incluir un único manifiesto por aplicación, generalmente alojado en la carpeta raíz, vinculado a todas las páginas HTML desde las que se pueda 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 aplicación 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 necesita saber que existe.

Cómo vincular 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 configurado 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 el Inspector en Firefox y las 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 según los análisis del 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 según los análisis del navegador.

Cómo diseñar tu experiencia de AWP

Ahora que tu AWP está conectada a su manifiesto, es hora de completar el resto de los campos para definir la experiencia de tus 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. Estos son los siguientes:

name
Nombre completo de tu AWP. Aparecerá junto con el ícono en la pantalla principal, el selector, el conector o el menú del sistema operativo.
short_name
Opcional: Un nombre más corto de tu AWP, que se usa cuando no hay suficiente espacio para mostrar el valor completo del campo name. Asegúrate de que no supere los 12 caracteres para minimizar la posibilidad de que se trunque.
icons
Array de objetos de ícono con campos src, type, sizes y purpose opcionales, que describen qué imágenes deberían representar la AWP.
start_url
Es la URL que debe cargar la AWP cuando el usuario la inicia desde el ícono instalado. Se recomienda usar una ruta de acceso absoluta. Por lo tanto, 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 inicio. Puede ser un vínculo directo, como los detalles de un producto, en lugar de la pantalla principal.
display
Uno 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 la app. La mayoría de los casos de uso implementan standalone.
id
Es una cadena que identifica de forma inequívoca esta AWP frente a 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 cambias un valor de cadena de consulta), es posible que se quite la capacidad del navegador para detectar que una AWP ya está instalada.

Í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. Como la propiedad icons es una colección de objetos de ícono, puedes definir varios íconos en distintos formatos para proporcionar la mejor experiencia de íconos a tus usuarios. Cada navegador elegirá uno o más iconos según sus necesidades y el sistema operativo en el que está instalado, los iconos más cerca de las especificaciones necesarias.

Si necesitas elegir solo un tamaño de ícono, debe ser de 512 por 512 píxeles. Sin embargo, te recomendamos que proporciones más tamaños, incluidas imágenes de tamaño 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 los íconos no están en los tamaños recomendados, 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 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 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 contenido dentro de una “zona segura”, un círculo centrado en el ícono con un radio del 40% del ancho del ícono. (consulta la siguiente imagen). Los dispositivos compatibles con íconos enmascarables ocultarán tu ícono según sea necesario.

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

El siguiente 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 relleno es adecuado para máscaras.

Los íconos enmascarables deben tener un tamaño mínimo de 512 por 512. Una vez que hayas creado uno, puedes agregarlo a tu colección de icons para mejorar la experiencia en 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 bien, 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 es aquel que mejorará la experiencia del usuario, aunque no son obligatorios para la instalación.

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 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 la hoja de estilo. Safari en iOS y iPadOS, y la mayoría de los navegadores de escritorio ignoran este campo actualmente.
scope
Cambia el alcance de navegación de la AWP, lo que te permite definir qué se muestra y qué no se muestra en la ventana de la app instalada. Por ejemplo, si incluyes un vínculo a una página fuera del alcance, se renderizará en un navegador de la app y no 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 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 CSS, como salmon o orange, colores RGB como #FF5500, o funciones de color sin transparencia, como rgb() o hsl(). Para obtener más información, consulta el capítulo Diseño de apps.

Probar

Pantallas de presentación

En algunos dispositivos, se renderiza una imagen estática mientras se carga la AWP para proporcionar 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 aplicación web para generar pantallas de presentación. En cambio, usan una imagen vinculada desde un elemento <link> propio de la misma forma en que 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 del 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 para la app una vez instalada. Un juego puede configurarlo 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 el array de objetos de captura de pantalla con src, type y sizes (similar al objeto icons) para mostrar la AWP. No hay restricciones de tamaño.
categories
Es el array de categorías a las que debe pertenecer la AWP y sirve como sugerencias para las fichas (opcionalmente de la lista de categorías conocidas). Por lo general, estos valores están en minúscula.
iarc_rating_id
El código de certificación de la Coalición Internacional de Clasificación por Edad para la AWP, si tienes uno Está diseñada para determinar para qué edades es adecuada tu AWP.

Puedes ver estos campos promocionales en acción hoy mismo. Por ejemplo, en Android, 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 pasará de ser una barra de información simple "Agregar a la pantalla principal" a 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 agradable si proporcionas valores para los campos promocionales, como se puede ver en el siguiente video.

Observa estos campos de promoción en acción:

Campos de funciones

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, 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, 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