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

Uso compartido en dispositivos móviles y computadoras simplificado con la API de Web Share Target

Pete LePage

Joe Medley

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 elegir con quién compartir. Por ejemplo, tal vez quieras compartir un artículo interesante, ya sea enviándolo por correo electrónico a amigos o enviándolo a todo el mundo.

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

Observa el objetivo de uso compartido web en acción

1. Con Chrome 76 o una versión posterior para Android, o bien Chrome 89 o una versión posterior para computadoras, 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 Web Share Test.

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

Registra tu app como destino de uso compartido

Para registrar tu app como un objetivo de uso compartido, debe cumplir con los criterios de instalación de Chrome. Además, antes de que un usuario pueda compartir contenido con 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 deseen 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 la app 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 los cambios de la aplicación
• Se aceptan archivos

Aceptación de información básica

Si tu 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 para compartir usa body en lugar de text, puedes reemplazar "text": "text" por "text": "body".

Si no se proporciona, el valor predeterminado de method 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", enctype se establece de forma predeterminada como "application/x-www-form-urlencoded" y se ignora si se establece en cualquier otro valor.

Aceptando los cambios de la aplicación

Si los datos compartidos cambian la app de destino de alguna manera (por ejemplo, guardando 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 contenga ambos. Es mejor proporcionar un array que incluya un tipo de MIME y una extensión de archivo, ya que los sistemas operativos prefieren los distintos tipos de sistemas.

{
  "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 entrantes depende de tu app. Por ejemplo:

• Un cliente de correo electrónico podría redactar un borrador de un nuevo correo electrónico con title como asunto, con text y url concatenados como el cuerpo.
• Una app de redes sociales podría redactar un borrador de una entrada 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 analizar 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 de diapositivas, 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 mensaje nuevo con 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 abre una ventana nueva en la URL action. Luego, el navegador genera una cadena de consulta mediante los valores codificados como 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 previamente en caché la página action, a fin de 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 tu service worker.

Procesando archivos compartidos POST

Si tu method es "POST", como sucedería si tu app de destino acepta un favorito guardado o archivos compartidos, el cuerpo de la solicitud POST entrante contiene los datos que pasó la aplicación compartida, 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

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, ocasionalmente, en el campo title.

Navegadores compatibles

La API de Web Share Target se admite de la siguiente manera:

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

Aplicaciones de muestra

• Squoosh
• AWP del libro de notas

Muestra compatibilidad con la API

¿Planeas usar la API de Web Share Target? Tu asistencia pública ayuda al equipo de Chromium a priorizar funciones y le muestra a otros proveedores de navegadores la importancia de admitirlas.

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