Agrega un manifiesto de aplicación web

Navegadores compatibles

  • 39
  • 79
  • x
  • x

Origen

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.
Ejemplo de una ventana de AWP con pantalla independiente.
La IU independiente.
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.
Ejemplo de una ventana de AWP con pantalla de IU mínima.
La IU mínima.
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 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, la scope 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 atributo scope.
  • 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.

Ejemplo de una ventana de AWP con theme_color personalizado.
Ejemplo de una ventana de AWP con theme_color personalizados.

theme_color en consultas de medios

Navegadores compatibles

  • 93
  • 93
  • 106
  • 15

Origen

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, las capturas de pantalla con form_factor establecido en "wide" se ignoran en Android. Se siguen mostrando capturas de pantalla sin form_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.

Capturas de pantalla de una IU de instalación más completa en computadoras y dispositivos móviles.
IU de instalación más completa para computadoras y dispositivos móviles.

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.

El panel de la aplicación en Herramientas para desarrolladores de Chrome con la pestaña del manifiesto seleccionada.
Prueba tu manifiesto en Herramientas para desarrolladores.

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.