Uso de un manifiesto de aplicación web para integrar un PWA en el sistema operativo

  • Artículo

Una aplicación web progresiva (PWA) debe tener un manifiesto de aplicación web para definir cómo se integra la PWA con el sistema operativo (SO). En este artículo se explica qué es un manifiesto de aplicación web y qué datos obligatorios y opcionales contiene un manifiesto de aplicación web.

El archivo de manifiesto de aplicación web rige el aspecto y comportamiento de la PWA cuando se instala en un dispositivo. El manifiesto de aplicación web proporciona información como el nombre de la aplicación, la ubicación del archivo de los iconos que representan la aplicación en los menús del sistema y los colores del tema que usa el sistema operativo en la barra de título.

Un manifiesto de aplicación web es un archivo JSON al que se debe hacer referencia desde la página HTML del sitio web mediante un vínculo de manifiesto. Inserte el código siguiente entre las etiquetas y </head> de la <head> página HTML del sitio web para vincularlo al archivo de manifiesto:

<link rel="manifest" href="/manifest.json">

Tipo de archivo de manifiesto de aplicación web

El contenido del manifiesto de la aplicación web debe ser JSON válido, pero la extensión de archivo puede ser o .json.webmanifest.

Si decide usar la .webmanifest extensión, compruebe que el servidor HTTP la atiende con el application/manifest+json tipo MIME.

Miembros del manifiesto

Como mínimo, un archivo de manifiesto debe contener los siguientes miembros de manifiesto:

{
    "name": "My Sample PWA",
    "lang": "en-US",
    "start_url": "/"
}

A continuación se muestra un ejemplo de un archivo de manifiesto que contiene más miembros:

{
    "name": "My Sample PWA",
    "lang": "en-us",
    "short_name": "SamplePWA",
    "description": "A sample PWA for testing purposes",
    "start_url": "/",
    "scope": "/",
    "display": "standalone",
    "theme_color": "#2f3d58",
    "background_color": "#2f3d58",
    "orientation": "any",
    "icons": [
        {
            "src": "/icon512.png",
            "sizes": "512x512"
        }
    ]
}

Un PWA se puede personalizar aún más mediante otros miembros del manifiesto, como los siguientes:

Member Descripción
name Nombre de la aplicación, que usa el sistema operativo para mostrarse junto al icono de la aplicación.
short_name Esto se puede usar para mostrar el nombre de la aplicación cuando no hay suficiente espacio para name.
description Descripción de la aplicación.
categories Lista de categorías a las que pertenece la aplicación.
icons Matriz de objetos de imagen de icono que usa el sistema operativo en contextos diferentes.
screenshots Matriz de objetos de imagen de captura de pantalla, que también usa el sistema operativo en contextos diferentes.
start_url Dirección URL preferida a la que se debe navegar cuando el sistema operativo inicia la aplicación.
scope Define el ámbito de navegación de la aplicación. Fuera de este ámbito, la página visitada se revierte a una página web normal, no a una PWA. Este valor predeterminado es start_url.
display Qué aspecto debe tener la aplicación. Esto cambia la cantidad de la interfaz de usuario del explorador que se muestra al usuario.
display_override Se usa para determinar la pantalla preferida para la aplicación, en función de lo que admita el dispositivo.
theme_color Color de tema predeterminado para la aplicación. Esto afecta al modo en que el sistema operativo muestra el sitio.
background_color Color de fondo de la ventana donde se inicia la aplicación, antes de aplicar la hoja de estilos.
orientation En los dispositivos compatibles, esto define la orientación predeterminada de la aplicación (por ejemplo, horizontal o vertical).
protocol_handlers Lista de esquemas de protocolo URI predefinidos o personalizados a los que está asociada la aplicación.
shortcuts La lista de tareas comunes que los usuarios podrán realizar haciendo clic con el botón derecho o presionando durante mucho tiempo en el icono de la aplicación.
share_target Tipo de datos que la aplicación acepta cuando el contenido se comparte a través del cuadro de diálogo recurso compartido del sistema operativo.
file_handlers Tipo de archivos con los que se puede iniciar la aplicación.

Para más información sobre los miembros del manifiesto, consulte manifiestos de aplicaciones web en MDN.

Controlar esquemas de protocolo específicos

Puede registrar el PWA como controlador de protocolo. Cuando un usuario hace clic en un vínculo que usa el esquema de protocolo en el que se registró la aplicación, la aplicación se inicia automáticamente. Esto permite a los usuarios compartir fácilmente vínculos a partes específicas o funciones de la aplicación entre sí.

Para registrarse como controlador de protocolo, use el miembro de protocol_handlers manifiesto:

{
    "protocol_handlers": [
        {
            "protocol": "mailto",
            "url": "/newEmail?to=%s"
        }
    ]
}

Para obtener más información, consulte Control de protocolos en Aplicaciones web progresivas.

Uso de accesos directos para proporcionar acceso rápido a las características

La mayoría de los sistemas operativos proporcionan acceso rápido a las características clave de la aplicación mediante accesos directos en el menú contextual que está conectado al icono de la aplicación. Para usar accesos directos en la PWA, incluya el miembro en el shortcuts manifiesto de la aplicación web.

En el código siguiente se muestra cómo definir un acceso directo en un manifiesto de aplicación web.

"shortcuts": [
    {
        "name": "Play Later",
        "description": "View the list of podcasts you saved for later",
        "url": "/play-later",
        "icons": [
            {
                "src": "/icons/play-later.svg",
                "type": "image/svg+xml",
                "purpose": "any"
            }
        ]
    },
    {
        "name": "Subscriptions",
        "description": "View the list of podcasts available in your subscription",
        "url": "/subscriptions?sort=desc"
    }
]

Para más información, consulte Definición de accesos directos de aplicaciones.

Identificación de la aplicación como destino de recurso compartido

Para permitir que los usuarios compartan rápidamente vínculos y archivos con aplicaciones nativas, use el share_target objeto en el manifiesto de aplicación web. Una action página es similar a un formulario. En el share_target objeto , defina la action página y los parámetros que espera que se pasen a la action página.

"share_target": {
    "action": "/share.html",
    "params": {
        "title": "name",
        "text": "description",
        "url": "link"
    }
}

El objeto anterior share_target se establece /share.html como la action página de un recurso compartido. En este ejemplo también se definen tres parámetros que se pasarían a esa action página: title, texty url.

Para más información sobre el uso de la característica Compartir destino, consulte Uso compartido de contenido con otras aplicaciones.

Asociación de la aplicación con archivos

Cuando un PWA se registra como controlador de archivos para determinados tipos de archivos, el sistema operativo puede iniciar automáticamente la aplicación cuando el usuario abre esos archivos, de forma similar a cómo Microsoft Word controla .docx los archivos. Los PWA que controlan archivos se sienten más nativos para los usuarios y se integran mejor en el sistema operativo.

Para controlar los archivos, enumere los tipos mime de archivo y las extensiones con las que desea asociar la aplicación y defina la dirección URL con la que se debe iniciar la aplicación:

{
    "file_handlers": [
        {
            "action": "/openFile",
            "accept": {
                "text/*": [
                    ".txt"
                ]
            }
        }
    ]
}

A continuación, controle los archivos mediante el window.launchQueue() método :

if ('launchQueue' in window) {
    launchQueue.setConsumer(launchParams => {
        // Do something with launchParams.files ...
    });
}

Para más información, consulte Control de archivos en Aplicaciones web progresivas.