Cómo recibir datos compartidos con la API de Web Share Target

Se simplificó el uso compartido en computadoras y dispositivos móviles con la API de Web Share Target

En un dispositivo móvil o de escritorio, el uso compartido debe ser tan sencillo como hacer clic en el botón Compartir, elegir una app y con quién. Por ejemplo, es posible que desees compartir un artículo interesante, ya sea enviándolo por correo electrónico a tus amigos o tuitándolo al mundo.

Antes, solo las apps específicas de la plataforma se podían registrar en el sistema operativo para recibir acciones de otras apps instaladas. Sin embargo, con la API de Web Share Target, las apps web instaladas pueden registrarse con el sistema operativo subyacente como un objetivo de uso compartido para recibir contenido compartido.

Teléfono Android con el panel lateral "Compartir a través de" abierto.
Selector de objetivos de uso compartido a nivel del sistema con una AWP instalada como opción.

Ver el objetivo de uso compartido en la Web

  1. Con Chrome 76 o una versión posterior para Android, o bien Chrome 89 o una versión posterior en computadoras de escritorio, abre la demostración de Web Share Target.
  2. Cuando se te solicite, haz clic en Instalar para agregar la app a la pantalla principal o usa el menú de Chrome para agregarla a la pantalla principal.
  3. Abre cualquier app que admita el uso compartido o usa el botón Compartir en la app de demostración.
  4. En el selector de destinos, elige Prueba de uso compartido en la Web.

Después de compartir, deberías ver toda la información compartida en la app web de destino para el uso compartido web.

Registra tu app como objetivo de uso compartido

Para registrar tu app como un objetivo de uso compartido, esta debe cumplir con los criterios de instalación de Chrome. Además, antes de que un usuario pueda compartir contenido en tu app, debe agregarlo a su pantalla principal. De esta manera, se evita que los sitios se agreguen de forma aleatoria al selector de intents de uso compartido del usuario y garantiza que el uso compartido sea algo que los usuarios quieran hacer con tu app.

Actualiza el manifiesto de tu app web

Para registrar tu app como un objetivo de uso compartido, agrega una entrada share_target al manifiesto de aplicación web. Esto le indica al sistema operativo que incluya tu app como opción en el selector de intents. Lo que agregas al manifiesto controla los datos que aceptará tu app. Existen tres situaciones comunes para la entrada share_target:

  • Aceptación de información básica
  • Aceptando cambios en la aplicación
  • Se aceptan archivos

Aceptación de información básica

Si la app de destino solo acepta información básica como datos, vínculos y texto, agrega lo siguiente al archivo manifest.json:

"share_target": {
  "action": "/share-target/",
  "method": "GET",
  "params": {
    "title": "title",
    "text": "text",
    "url": "url"
  }
}

Si tu aplicación ya tiene un esquema de URL compartida, puedes reemplazar los valores params con tus parámetros de consulta existentes. Por ejemplo, si tu esquema de URL compartida usa body en lugar de text, puedes reemplazar "text": "text" por "text": "body".

Si no se proporciona, el valor method predeterminado es "GET". El campo enctype, que no se muestra en este ejemplo, indica el tipo de codificación para los datos. Para el método "GET", el valor predeterminado de enctype es "application/x-www-form-urlencoded" y se ignora si se establece en cualquier otro valor.

Aceptando cambios en la aplicación

Si los datos compartidos cambian la app de destino de alguna manera (por ejemplo, al guardar un favorito en la aplicación de destino), establece el valor de method en "POST" e incluye el campo enctype. En el siguiente ejemplo, se crea un favorito en la app de destino, por lo que usa "POST" para method y "multipart/form-data" para enctype:

{
  "name": "Bookmark",
  "share_target": {
    "action": "/bookmark",
    "method": "POST",
    "enctype": "multipart/form-data",
    "params": {
      "url": "link"
    }
  }
}

Se aceptan archivos

Al igual que con los cambios en la aplicación, para aceptar archivos es necesario que method sea "POST" y que enctype esté presente. Además, enctype debe ser "multipart/form-data" y se debe agregar una entrada files.

También debes agregar un array files que defina los tipos de archivos que acepta tu app. Los elementos del array son entradas con dos miembros: un campo name y un campo accept. El campo accept toma un tipo de MIME, una extensión de archivo o un array que contiene ambos. Lo mejor es proporcionar un array que incluya un tipo de MIME y una extensión de archivo, ya que los sistemas operativos son los que prefieren.

{
  "name": "Aggregator",
  "share_target": {
    "action": "/cgi-bin/aggregate",
    "method": "POST",
    "enctype": "multipart/form-data",
    "params": {
      "title": "name",
      "text": "description",
      "url": "link",
      "files": [
        {
          "name": "records",
          "accept": ["text/csv", ".csv"]
        },
        {
          "name": "graphs",
          "accept": "image/svg+xml"
        }
      ]
    }
  }
}

Cómo administrar el contenido entrante

La manera en la que manejas los datos compartidos que ingresan depende de ti y de tu app. Por ejemplo:

  • Un cliente de correo electrónico podría redactar un borrador de un correo electrónico nuevo con title como asunto, con text y url concatenados como cuerpo.
  • Una app de redes sociales podría redactar un borrador de una publicación nueva ignorando title, usando text como cuerpo del mensaje y agregando url como vínculo. Si falta text, la app también podría usar url en el cuerpo. Si falta url, la app podría escanear text en busca de una URL y agregarla como un vínculo.
  • Una app para compartir fotos podría crear una nueva presentación de diapositivas con title como título de la presentación, text como descripción y files como las imágenes de la presentación.
  • Una app de mensajería de texto podría redactar un borrador de un mensaje nuevo usando text y url concatenados y sin title.

Procesando archivos compartidos GET

Si el usuario selecciona tu aplicación y tu method es "GET" (la opción predeterminada), el navegador abrirá una ventana nueva en la URL action. Luego, el navegador genera una cadena de consulta con los valores codificados para URL proporcionados en el manifiesto. Por ejemplo, si la app para compartir proporciona title y text, la cadena de consulta es ?title=hello&text=world. Para procesarlo, usa un objeto de escucha de eventos DOMContentLoaded en tu página en primer plano y analiza la cadena de consulta:

window.addEventListener('DOMContentLoaded', () => {
  const parsedUrl = new URL(window.location);
  // searchParams.get() will properly handle decoding the values.
  console.log('Title shared: ' + parsedUrl.searchParams.get('title'));
  console.log('Text shared: ' + parsedUrl.searchParams.get('text'));
  console.log('URL shared: ' + parsedUrl.searchParams.get('url'));
});

Asegúrate de usar un service worker para almacenar en caché previamente la página action para que se cargue con rapidez y funcione de forma confiable, incluso si el usuario no tiene conexión. Workbox es una herramienta que puede ayudarte a implementar el almacenamiento previo en caché en el service worker.

Procesando archivos POST compartidos

Si tu method es "POST", como lo haría si tu app de destino acepta un favorito guardado o archivos compartidos, el cuerpo de la solicitud POST entrante contendrá los datos que pasó la aplicación para compartir, codificados con el valor enctype proporcionado en el manifiesto.

La página en primer plano no puede procesar estos datos directamente. Dado que la página ve los datos como una solicitud, se los pasa al service worker, donde puedes interceptarlos con un objeto de escucha de eventos fetch. Desde aquí, puedes pasar los datos a la página en primer plano con postMessage() o pasarlos al servidor:

self.addEventListener('fetch', event => {
  const url = new URL(event.request.url);
  // If this is an incoming POST request for the
  // registered "action" URL, respond to it.
  if (event.request.method === 'POST' &&
      url.pathname === '/bookmark') {
    event.respondWith((async () => {
      const formData = await event.request.formData();
      const link = formData.get('link') || '';
      const responseUrl = await saveBookmark(link);
      return Response.redirect(responseUrl, 303);
    })());
  }
});

Cómo verificar el contenido compartido

Un teléfono Android muestra la app de demostración con contenido compartido.
La app de destino de uso compartido de muestra.

Asegúrate de verificar los datos entrantes. Lamentablemente, no hay garantía de que otras apps compartan el contenido apropiado en el parámetro correcto.

Por ejemplo, en Android, el campo url estará vacío porque no es compatible con el sistema de uso compartido de Android. En cambio, las URLs a menudo aparecerán en el campo text o, en ocasiones, en el campo title.

Navegadores compatibles

La API de Web Share Target se admite como se describe a continuación:

En todas las plataformas, la app web debe estar instalada antes de que se muestre como un posible destino para recibir datos compartidos.

Aplicaciones de muestra

Demuestra compatibilidad con la API

¿Planeas usar la API de Web Share Target? Tu asistencia pública ayuda al equipo de Chromium a priorizar las funciones y les muestra a otros proveedores de navegadores lo fundamental que es admitirlas.

Envía un tweet a @ChromiumDev con el hashtag #WebShareTarget y cuéntanos dónde y cómo lo estás usando.