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 sobre música. Imagina que ambos tienen la AWP music.example.com instalada en tus dispositivos. Si quieres compartir tu pista favorita para que la disfrute tu amigo, puedes enviarle un vínculo directo, como https://music.example.com/rick-astley/never-gonna-give-you-up. Dado que 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 segmento, como, por ejemplo, https://🎵.example.com/r-a/n-g-g-y-u.

Las AWP como controladores de URL permiten 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 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.

La AWP como controladores de URL consta de dos incorporaciones:

  1. El miembro del manifiesto de la app web "url_handlers".
  2. Es 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 AWP como controladores de URL

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

  • Sitios de transmisión de música o video para que los vínculos de pistas o playlists se abran en la experiencia del reproductor de la app
  • Los lectores de noticias o RSS que siguen los sitios o los que están suscritos se abren en el modo de lectura de la aplicación.

Cómo usar AWPs como controladores de URL

Habilitación a través de about://flags

Para experimentar con AWP 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 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 un string obligatorio que es un patrón para hacer coincidir los orígenes. Estos patrones pueden tener un prefijo de comodín (*) para incluir varios subdominios (como https://*.example.com). Esta app web podría controlar las URLs que coincidan con estos orígenes. Se supone que el esquema siempre es https://, pero se debe mencionar de forma explícita.

En el siguiente extracto de un manifiesto de app web, se muestra cómo el ejemplo de la AWP de música del párrafo introductorio podría configurar esto. La segunda entrada con el comodín ("https://*.music.example.com") se asegura de que la app también se active para https://www.music.example.com o para otros ejemplos potenciales, 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 (music.example.com) diferente de algunas de las URLs que debe controlar (p.ej., https://🎵.example.com), la app debe verificar la propiedad de esos 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 Predeterminada
"manifest" Cadena de URL (obligatoria) del manifiesto de la app web de la AWP asociada string N/A
"details" (Opcional) 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 Predeterminada
"paths" Array de cadenas de ruta de acceso permitidas (opcional) string[] []
"exclude_paths" (Opcional) Es un array de cadenas de rutas de acceso no permitidas. string[] []

A continuación, se muestra un ejemplo de archivo web-app-origin-association 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 AWP 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 AWP coincide con una URL para su control si se cumplen las siguientes condiciones:

  • La URL coincide con una de las cadenas de origen en "url_handlers".
  • El navegador puede validar a través del archivo web-app-origin-association correspondiente que cada origen acepta permitir que esta app controle esa URL.

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

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

Demostración

Para probar las AWP como controladores de URL, asegúrate de configurar la marca del navegador como se describió anteriormente y, luego, instala la AWP en https://mandymsft.github.io/pwa/. Si observas el manifiesto de la app web, puedes ver que controla las URLs con los siguientes patrones de URL: https://mandymsft.github.io y https://luhuangmsft.github.io. Dado que esta última se encuentra en un origen diferente (luhuangmsft.github.io) que la AWP, la AWP 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 que elijas o un correo electrónico que se vea en un cliente de correo electrónico que no sea web, como Mail en macOS. El correo electrónico o el mensaje de texto debe contener uno de los vínculos https://mandymsft.github.io o https://luhuangmsft.github.io. Ambas deben abrirse en la AWP instalada.

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

Seguridad y permisos

El equipo de Chromium diseñó e implementó AWP como controladores de URL con los principios básicos definidos en Controlling Access to Powerful Web Platform Features, 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 desea controlar el patrón, si es que hay alguna. Esta propuesta no controla las navegaciones que comienzan en una pestaña del navegador, ya que se orienta de forma explícita 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 URL activo para las URLs afectadas. Si los controladores de URL no se implementan correctamente, se pueden usar para usurpar el tráfico de los 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 AWP se registran como controladores de URL a nivel del SO en Windows, su presencia será 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 las asociaciones de las apps web instaladas con regularidad. Si un registro de controlador de URL 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 tu experiencia con las AWP 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.

Denuncia un problema con la implementación

¿Encontraste un error con 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 sea posible, instrucciones simples para reproducirlo y, luego, ingresa UI>Browser>WebAppInstalls en el cuadro Componentes. Glitch funciona muy bien para compartir repros rápidos y fáciles.

Cómo mostrar compatibilidad con la API

¿Planeas usar AWP 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. Joe Medley revisó este artículo. Imagen hero de Bryson Hammer en Unsplash.