AWP como controladores de URL

Permite que las AWP instaladas controlen las URLs para obtener una experiencia más integrada.

Thomas Steiner

¿Qué son las AWP como controladores de URL?

Imagina que estás chateando con un amigo con una aplicación de mensajería instantánea, como Mensajes en macOS, y están hablando de música. Además, imagina que ambos tienen instalada la AWP de music.example.com en sus dispositivos. Si quieres compartir tu pista favorita para que la disfrute un amigo, puedes enviarle un vínculo directo, como https://music.example.com/rick-astley/never-gonna-give-you-up. Como este vínculo es bastante largo, es posible que los desarrolladores de music.example.com hayan decidido agregar un vínculo corto adicional a cada pista, como, por ejemplo, https://🎵.example.com/r-a/n-g-g-y-u.

La función de AWP como controladores de URL permite que apps como music.example.com se registren como controladores de URL para URLs que coincidan con patrones como https://music.example.com, https://*.music.example.com o https://🎵.example.com, de modo que los vínculos que provengan de fuera de la AWP, por ejemplo, de una aplicación de mensajería instantánea o un cliente de correo electrónico, se abran en la AWP instalada en lugar de en una pestaña del navegador.

Las PWA como controladores de URL constan de dos adiciones:

  1. El miembro del manifiesto de la app web "url_handlers".
  2. El formato de archivo web-app-origin-association para validar las asociaciones de URLs dentro y fuera del alcance.

Casos de uso sugeridos para las PWA como controladores de URL

Estos son algunos ejemplos de sitios que pueden usar esta API:

  • Sitios de transmisión de música o video, de modo que los vínculos de pistas o playlists se abran en la experiencia de reproducción de la app
  • Lectores de noticias o RSS para que los sitios seguidos o suscritos se abran en el modo de lectura de la app

Cómo usar las AWP como controladores de URLs

Habilita con about://flags

Para experimentar con las PWA como controladores de URL de forma local, sin un token de prueba de origen, habilita la marca #enable-desktop-pwas-url-handling en about://flags.

El miembro del manifiesto de la app web "url_handlers"

Para asociar una AWP instalada con patrones de URL, estos patrones deben especificarse en el manifiesto de la app web. Esto sucede a través del miembro "url_handlers". Acepta un array de objetos con una propiedad origin, que es una string obligatoria que es un patrón para hacer coincidir los orígenes. Estos patrones pueden tener un prefijo comodín (*) para incluir varios subdominios (como https://*.example.com). Esta app web podría controlar las URLs que coincidan con estos orígenes. Siempre se supone que el esquema es https://, pero se debe mencionar de forma explícita.

En el siguiente extracto de un manifiesto de app web, se muestra cómo la PWA de música del párrafo introductorio podría configurar esto. La segunda entrada con el comodín ("https://*.music.example.com") garantiza que la app también se active para https://www.music.example.com o posibles ejemplos, como https://marketing-activity.music.example.com.

{
  "url_handlers": [
    {
      "origin": "https://music.example.com"
    },
    {
      "origin": "https://*.music.example.com"
    },
    {
      "origin": "https://🎵.example.com"
    }
  ]
}

El archivo web-app-origin-association

Dado que la AWP se encuentra en un origen diferente (music.example.com) que algunas de las URLs que necesita controlar (p.ej., https://🎵.example.com), la app debe verificar la propiedad de estos otros orígenes. Esto ocurre en un archivo web-app-origin-association alojado en los otros orígenes.

Este archivo debe contener un JSON válido. La estructura de nivel superior es un objeto, con un miembro llamado "web_apps". Este miembro es un array de objetos, y cada objeto representa una entrada para una app web única. Cada objeto contiene lo siguiente:

Campo Descripción Tipo Predeterminado
"manifest" (Obligatorio) Es la cadena de URL del manifiesto de la app web de la AWP asociada. string N/A
"details" (Opcional) Es un objeto que contiene arrays de patrones de URL incluidos y excluidos. object N/A

Cada objeto "details" contiene lo siguiente:

Campo Descripción Tipo Predeterminado
"paths" (Opcional) Array de cadenas de rutas de acceso permitidas string[] []
"exclude_paths" (Opcional) Array de cadenas de rutas de acceso no permitidas string[] []

A continuación, se muestra un archivo web-app-origin-association de ejemplo para la PWA de música del ejemplo anterior. Se alojaría en el origen 🎵.example.com y establecería la asociación con la PWA music.example.com, identificada por la URL del manifiesto de la app web.

{
  "web_apps": [
    {
      "manifest": "https://music.example.com/manifest.json",
      "details": {
        "paths": ["/*"],
        "exclude_paths": ["/internal/*"]
      }
    }
  ]
}

¿Cuándo coincide una URL?

Una PWA coincide con una URL para su administración si se cumplen las dos condiciones siguientes:

  • La URL coincide con una de las cadenas de origen en "url_handlers".
  • El navegador puede validar con el archivo web-app-origin-association respectivo que cada origen acepta que esta app controle esa URL.

Acerca del descubrimiento de archivos web-app-origin-association

Para que el navegador descubra el archivo web-app-origin-association, los desarrolladores deben colocarloweb-app-origin-association en la carpeta /.well-known/ en la raíz de la app. Para que esto funcione, el nombre del archivo debe ser exactamente web-app-origin-association.

Demostración

Para probar las AWP como controladores de URLs, asegúrate de establecer la marca del navegador como se describe y, luego, instala la AWP en https://mandymsft.github.io/pwa/. Si observas su manifiesto de app web, puedes ver que controla las URLs con los siguientes patrones de URL: https://mandymsft.github.io y https://luhuangmsft.github.io. Como esta última se encuentra en un origen diferente (luhuangmsft.github.io) que la PWA, la PWA en mandymsft.github.io debe demostrar la propiedad, lo que sucede con el archivo web-app-origin-association alojado en https://luhuangmsft.github.io/.well-known/web-app-origin-association.

Para probar que realmente funciona, envíate un mensaje de prueba con una app de mensajería instantánea de tu elección o un correo electrónico visto en un cliente de correo electrónico que no esté basado en la Web, como Mail en macOS. El correo electrónico o mensaje de texto debe contener los vínculos https://mandymsft.github.io o https://luhuangmsft.github.io. Ambos deberían abrirse en la PWA instalada.

La app de mensajería instantánea de Skype para Windows junto a la AWP de demostración instalada, que se abre en modo independiente después de hacer clic en un vínculo que se controla en un mensaje de chat de Skype.

Seguridad y permisos

El equipo de Chromium diseñó e implementó las AWP como controladores de URL con los principios básicos definidos en Control del acceso a funciones potentes de la plataforma web, incluidos el control del usuario, la transparencia y la ergonomía.

Control de usuarios

Si más de una AWP se registra como controlador de URL para un patrón de URL determinado, se le pedirá al usuario que elija con qué AWP quiere controlar el patrón, si es que quiere hacerlo. Esta propuesta no controla las navegaciones que comienzan en una pestaña del navegador, sino que se orienta explícitamente a las navegaciones que comienzan fuera del navegador.

Transparencia

Si, por algún motivo, no se puede completar correctamente la validación de asociación necesaria durante la instalación de la AWP, el navegador no registrará la app como un controlador de URLs activo para las URLs afectadas. Si se implementan de forma incorrecta, los controladores de URLs se pueden usar para apropiarse del tráfico de sitios web. Por este motivo, el mecanismo de asociación de apps es una parte importante del esquema.

Las aplicaciones específicas de la plataforma ya pueden usar las APIs del sistema operativo para enumerar las aplicaciones instaladas en el sistema del usuario. Por ejemplo, las aplicaciones en Windows pueden usar la API de FindAppUriHandlersAsync para enumerar los controladores de URL. Si las PWA se registran como controladores de URLs a nivel del SO en Windows, su presencia sería visible para otras aplicaciones.

Persistencia de permisos

Un origen podría modificar sus asociaciones con las AWP en cualquier momento. Los navegadores intentarán volver a validar con regularidad las asociaciones de las apps web instaladas. Si el registro de un controlador de URLs no se vuelve a validar porque los datos de asociación cambiaron o ya no están disponibles, el navegador quitará los registros.

Comentarios

El equipo de Chromium quiere conocer tus experiencias con las PWA como controladores de URL.

Cuéntanos sobre el diseño de la API

¿Hay algo en la API que no funciona como esperabas? ¿O faltan métodos o propiedades que necesitas para implementar tu idea? ¿Tienes alguna pregunta o comentario sobre el modelo de seguridad? Informa un problema de especificación en el repositorio de GitHub correspondiente o agrega tus comentarios a un problema existente.

Informa un problema con la implementación

¿Encontraste un error en la implementación de Chromium? ¿O la implementación es diferente de la especificación? Informa un error en new.crbug.com. Asegúrate de incluir tantos detalles como puedas, instrucciones para reproducirlo, y escribe UI>Browser>WebAppInstalls en el cuadro Componentes.

Muestra compatibilidad con la API

¿Planeas usar las PWA como controladores de URL? Tu apoyo público ayuda al equipo de Chromium a priorizar las funciones y les muestra a otros proveedores de navegadores lo importante que es admitirlas.

Envía un tweet a @ChromiumDev con el hashtag #URLHandlers y cuéntanos dónde y cómo lo usas.

Vínculos útiles

Agradecimientos

Lu Huang y Mandy Chen, del equipo de Microsoft Edge, especificaron e implementaron las AWP como controladores de URL. Este documento fue revisado por Joe Medley.