Manifiesto de aplicación web

Qué es

Un manifiesto de aplicación web es un documento JSON que describe un
sitio web como aplicación: cómo se llama, en qué dirección se abre,
qué direcciones le pertenecen, cómo debe verse su ventana y qué
imágenes lo representan. Una página señala el archivo mediante un
elemento `link` cuyo `rel` es `manifest`; un navegador que ofrece
instalación lo lee para decidir cómo será la copia instalada. La
especificación del W3C que lo define lo llama simplemente
manifiesto, y así se suele llamar también en el uso cotidiano.

El archivo es JSON corriente. Su tipo de medio registrado es
`application/manifest+json` y su extensión registrada es
`.webmanifest`, aunque la especificación acepta cualquier tipo de
medio JSON y muchos sitios sirven un `manifest.json`. Todos los
miembros son opcionales. Un manifiesto pequeño para un sitio
imaginario de tablas de mareas sería así:

```json
{
    "name": "Harbour Tide Tables",
    "short_name": "Tides",
    "start_url": "/tides/",
    "display": "standalone",
    "background_color": "#ffffff",
    "icons": [
        {
            "src": "/icons/tides-512.png",
            "sizes": "512x512",
            "type": "image/png"
        }
    ]
}
```

Tres miembros deciden qué es la aplicación, a diferencia de cómo se
ve. `start_url` propone la página que abre la aplicación instalada;
el navegador puede ignorarla o permitir que el usuario la cambie.
`scope` es el conjunto de direcciones que se consideran parte de la
aplicación. Si falta, la especificación toma la URL inicial y le
quita el nombre del archivo, la cadena de consulta y el fragmento,
de modo que el ejemplo abarca todo lo situado bajo `/tides/`. `id`
es la identidad de la aplicación y, si falta, toma la URL inicial.
Las direcciones relativas de los iconos y la URL inicial se
resuelven con respecto a la URL del propio manifiesto, no a la
página que lo enlazó. Un `id` relativo, en cambio, se resuelve con
respecto al origen de la URL inicial.

El resto es presentación. `display` solicita `fullscreen`,
`standalone`, `minimal-ui` o `browser`; un navegador que no puede
cumplirlo desciende por esa lista en orden. Cada icono puede llevar
un `purpose`: `any` de forma predeterminada, `maskable` para una
imagen diseñada para resistir recortes, o `monochrome` para una cuyo
color se descarta y de la que solo se usa el canal alfa.
`theme_color` tiñe la ventana que rodea a la aplicación. Una nota
complementaria del W3C añade `description`, `categories` y
`screenshots`, que pueden mostrarse en diálogos de instalación y
tiendas de aplicaciones.

Por qué importa

El manifiesto aporta metadatos de instalación controlados por el
sitio. La especificación deja la decisión de instalar al navegador:
puede ofrecer una forma de hacerlo, y cada navegador fija sus
condiciones, algunas de las cuales requieren ciertos miembros. El
equipo entrega los datos de entrada y el navegador decide qué hacer
con ellos. La pregunta útil no es tanto si conviene tener un
manifiesto como qué promete.

La identidad es la promesa que dura más que el archivo. Cuando un
navegador vuelve a obtener el manifiesto, la especificación indica
que debería usar un `id` coincidente como señal de que el nuevo
archivo sustituye al manifiesto de una aplicación ya instalada. Como
un `id` ausente toma la URL inicial, mover la página de inicio
cambia silenciosamente la identidad; el navegador debería tratar el
nuevo archivo como una aplicación distinta de la que tiene el lector
en su dispositivo. Fijar `id` en la primera versión cuesta una línea
y elimina ese riesgo.

El alcance decide dónde termina la ventana de la aplicación. La
navegación dentro de ese alcance permanece en la ventana instalada.
Un enlace que sale de él se abre igualmente, pero la especificación
espera que el navegador indique al lector que está fuera de la
aplicación. Un alcance más estrecho que el sitio hace que los
enlaces habituales entre secciones parezcan salidas.

Los iconos concentran la mayoría de los daños visibles. Los
lanzadores los recortan en círculos, cuadrados redondeados y otras
formas; un logotipo que llena todo su cuadrado pierde los bordes. La
especificación define la zona segura de un icono enmascarable como
un círculo central cuyo radio es dos quintos del lado más corto del
icono; lo que quede fuera puede recortarse. Un icono monocromo
conserva solo su canal alfa, por lo que uno dibujado sobre un fondo
opaco se convierte en un cuadrado sólido.

Los miembros de color tienen un alcance menor del que parece.
`background_color` está pensado solo para el momento anterior a la
llegada de la hoja de estilos, y la especificación prohíbe al
navegador usarlo cuando esta ya está disponible. Es el color del
primer fotograma, y de nada posterior.

Cómo se aplica en la práctica

Este sitio genera su manifiesto a partir de una plantilla en lugar
de mantener un archivo a mano. Su configuración de Hugo registra
`application/manifest+json` con el sufijo `webmanifest` y establece
el manifiesto como salida de la página de inicio de cada idioma.
Así, cada idioma tiene su propio archivo y la cabecera de cada
página enlaza el correspondiente a su idioma. La configuración deja
escrita la razón: una sola copia global solo puede indicar una URL
inicial, y un visitante que instalaba la versión danesa del sitio
obtenía una aplicación que abría la página de inicio en inglés.

La plantilla compone el manifiesto como un mapa y lo entrega al
codificador JSON de Hugo: el escape y las comas son responsabilidad
del codificador, y no puede publicarse un JSON al que le falte una
coma. Cada dirección de icono parte de la raíz del servidor. El
comentario explica por qué: una dirección relativa en
`/da/manifest.webmanifest` se resolvería bajo `/da/`, y todos los
iconos en danés darían un 404. Los iconos se leen del disco desde
tres carpetas, una por propósito, con diez tamaños cada una, de 36 a
512 píxeles. El tamaño se obtiene del nombre del archivo, así que
uno añadido por el generador aparece en el manifiesto sin editar
nada.

`id` está fijado a la dirección de inicio del idioma, y `scope`
abarca todo el origen, por lo que un enlace a otro idioma sigue
dentro de la ventana instalada. Las capturas se llaman
`<lang>-<form_factor>-<WxH>.webp`, y la plantilla extrae los tres
datos del nombre: inglés y danés tienen cada uno una captura ancha
de 1.280 por 800 y otra estrecha de 780 por 1.688. Un idioma sin
capturas no recibe ningún miembro `screenshots`, en lugar de una
lista vacía.

La página de créditos incluye la especificación del W3C entre los
estándares que sigue el sitio, y PWABuilder entre las comprobaciones
externas que cualquiera puede ejecutar: un servicio que lee el
manifiesto y los demás elementos que permiten instalar el sitio,
desde equipos de Microsoft.

La página de instalación es la parte del mismo archivo dirigida al
lector. Explica dónde tiene cada navegador el comando de instalación
y señala que los navegadores de Apple nunca lo ofrecen por
iniciativa propia. Firefox dispone de una función separada de
ventanas de aplicaciones web, activada de forma predeterminada en
Windows desde la versión 143, o desde la 150 para instalaciones de
Microsoft Store. La documentación de implementación de Mozilla
indica que el soporte de Linux está desactivado de forma
predeterminada y que el de macOS no está disponible. La página
también aclara qué esperar de este sitio: la aplicación instalada es
un icono y una ventana propia. El sitio no publica ningún service
worker ni una copia sin conexión gestionada, por lo que necesita
conexión para el uso normal.

Dónde surgen los problemas

Todos los iconos devuelven un 404 bajo una ruta traducida. Un `src`
relativo se resuelve con respecto a la URL del manifiesto. Si este
se sirve bajo un prefijo de idioma, pide los iconos bajo ese mismo
prefijo. Escriba las direcciones de los iconos desde la raíz del
servidor o como URL completas.

La aplicación instalada abre el idioma equivocado. Un manifiesto
puede indicar una URL inicial, por lo que todos los lectores
instalan la misma página de inicio. Sirva un manifiesto por idioma,
cada uno con sus propios `start_url` e `id`, y enlace el
correspondiente desde cada página.

Las copias instaladas ignoran el nuevo manifiesto. Sin `id`, la
identidad es la URL inicial. Mover la página de inicio da al archivo
una identidad nueva y el navegador debería tratarlo como una
aplicación distinta de la que ya tienen los lectores. Defina `id`
antes de la primera versión y no lo cambie después.

El lanzador recorta el logotipo. Un icono con propósito `any` se
coloca o recorta como decida la plataforma. Añada un icono
`maskable` que mantenga todo lo importante dentro del círculo
central, con un radio del 40 % del lado más corto del icono.

Editar el manifiesto no cambia nada. El estándar HTML usa solo el
primer elemento `link` cuyo `rel` contiene `manifest`. Si un tema o
complemento ha insertado su propio enlace antes en la página, el
archivo editado nunca es el que se lee. Mantenga exactamente un
enlace al manifiesto por página.

Lecturas adicionales

  * Web Application Manifest — todos los miembros, procesamiento del
archivo por el navegador y reglas de `id`, `scope` y propósitos de
los iconos.

  * Web App Manifest - Application Information — `description`,
`categories` y `screenshots`, con factores de forma y etiquetas.

  * IANA: application/manifest+json — registro del tipo de medio y
de su extensión `.webmanifest`.

  * HTML Standard: link type manifest — obtención del enlace al
manifiesto y por qué solo cuenta el primero.

  * Use web apps in Firefox for Windows — función de Windows,
disponible desde la versión 143, o desde la 150 para instalaciones
de Microsoft Store.

  * Firefox Source Docs: Web Apps in Firefox — implementación
actual: Windows activado de forma predeterminada, Linux desactivado
de forma predeterminada y macOS no admitido.

hEsta página en la web	URL:https://engineer.company/es/glossary/webmanifest/	engineer.company	70
