Получение общих данных с помощью API-интерфейса Web Share Target.

Совместное использование на мобильных устройствах и настольных компьютерах упрощено с помощью API Web Share Target.

Pete LePage

Joe Medley

На мобильном или настольном устройстве поделиться должно быть так же просто, как нажать кнопку «Поделиться» , выбрать приложение и выбрать, с кем поделиться. Например, вы можете поделиться интересной статьей, отправив ее друзьям по электронной почте или опубликовав ее в Твиттере для всего мира.

Раньше только приложения, специфичные для конкретной платформы, могли регистрироваться в операционной системе и получать общие ресурсы от других установленных приложений. Но с помощью API-интерфейса Web Share Target установленные веб-приложения могут регистрироваться в базовой операционной системе в качестве цели общего доступа для получения общего контента.

Посмотрите цель общего доступа в Интернет в действии

1. Используя Chrome 76 или более позднюю версию для Android или Chrome 89 или более позднюю версию для настольного компьютера, откройте демонстрацию Web Share Target .
2. При появлении запроса нажмите «Установить», чтобы добавить приложение на главный экран, или воспользуйтесь меню Chrome, чтобы добавить его на главный экран.
3. Откройте любое приложение, поддерживающее общий доступ, или воспользуйтесь кнопкой «Поделиться» в демонстрационном приложении.
4. В средстве выбора цели выберите «Тест веб-ресурса» .

После публикации вы должны увидеть всю общую информацию в целевом веб-приложении.

Зарегистрируйте свое приложение в качестве цели общего доступа

Чтобы зарегистрировать ваше приложение в качестве объекта общего доступа, оно должно соответствовать критериям установки Chrome . Кроме того, прежде чем пользователь сможет поделиться вашим приложением, он должен добавить его на свой главный экран. Это предотвращает случайное добавление сайтов к пользователю, выбирающему намерение поделиться, и гарантирует, что пользователи захотят поделиться с вашим приложением.

Обновите манифест вашего веб-приложения

Чтобы зарегистрировать свое приложение в качестве цели общего доступа, добавьте share_target в манифест его веб-приложения . Это указывает операционной системе включить ваше приложение в качестве опции в средство выбора намерений. То, что вы добавляете в манифест, определяет данные, которые будет принимать ваше приложение. Существует три распространенных сценария использования share_target :

• Принятие основной информации
• Принятие изменений приложения
• Прием файлов

Принятие основной информации

Если ваше целевое приложение просто принимает базовую информацию, такую ​​как данные, ссылки и текст, добавьте в файл manifest.json следующее:

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

Если в вашем приложении уже есть общая схема URL-адресов, вы можете заменить значения params существующими параметрами запроса. Например, если в вашей схеме URL-адреса общего доступа используется body вместо text , вы можете заменить "text": "text" на "text": "body" .

Значение method по умолчанию равно "GET" , если оно не указано. Поле enctype , не показанное в этом примере, указывает тип кодировки данных. Для метода "GET" enctype по умолчанию имеет значение "application/x-www-form-urlencoded" и игнорируется, если для него установлено любое другое значение.

Принятие изменений приложения

Если общие данные каким-либо образом изменяют целевое приложение (например, при сохранении закладки в целевом приложении), установите значение method "POST" и включите поле enctype . В приведенном ниже примере создается закладка в целевом приложении, поэтому для method используется "POST" , а для enctype "multipart/form-data" :

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

Прием файлов

Как и в случае с изменениями приложения, для принятия файлов требуется, чтобы method был "POST" и присутствовал enctype . Кроме того, enctype должен быть "multipart/form-data" и необходимо добавить запись files .

Вы также должны добавить массив files , определяющий типы файлов, которые принимает ваше приложение. Элементы массива представляют собой записи с двумя членами: полем name и полем accept . Поле accept принимает тип MIME, расширение файла или массив, содержащий и то, и другое. Лучше всего предоставить массив, включающий как MIME-тип, так и расширение файла, поскольку операционные системы различаются по своим предпочтениям.

{
  "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"
        }
      ]
    }
  }
}

Обрабатывать входящий контент

То, как вы поступите с входящими общими данными, зависит от вас и вашего приложения. Например:

• Почтовый клиент может составить новое электронное письмо, используя title в качестве темы электронного письма, а text и url объединяются в тело.
• Приложение социальной сети может создать черновик нового сообщения, игнорируя title , используя text в качестве тела сообщения и добавляя url в качестве ссылки. Если text отсутствует, приложение также может использовать url в теле сообщения. Если url отсутствует, приложение может сканировать text в поисках URL-адреса и добавить его в качестве ссылки.
• Приложение для обмена фотографиями может создать новое слайд-шоу, используя title в качестве заголовка слайд-шоу, text в качестве описания и files в качестве изображений слайд-шоу.
• Приложение для обмена текстовыми сообщениями может составить новое сообщение, используя text и url объединенные вместе, и отбрасывая title .

Обработка общих ресурсов GET

Если пользователь выбирает ваше приложение и выбран method "GET" (по умолчанию), браузер открывает новое окно по URL-адресу action . Затем браузер генерирует строку запроса, используя значения в URL-кодировке, указанные в манифесте. Например, если приложение для обмена предоставляет title и text , строка запроса будет ?title=hello&text=world . Чтобы обработать это, используйте прослушиватель событий DOMContentLoaded на странице переднего плана и проанализируйте строку запроса:

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'));
});

Обязательно используйте сервис-воркера для предварительного кэширования страницы action , чтобы она загружалась быстро и надежно работала, даже если пользователь находится в автономном режиме. Workbox — это инструмент, который может помочь вам реализовать предварительное кэширование в вашем сервис-воркере.

Обработка общих ресурсов POST

Если ваш method — "POST" , как если бы ваше целевое приложение принимало сохраненную закладку или общие файлы, тогда тело входящего запроса POST содержит данные, передаваемые приложением совместного доступа, закодированные с использованием значения enctype указанного в манифесте. .

Страница переднего плана не может обрабатывать эти данные напрямую. Поскольку страница воспринимает данные как запрос, она передает их сервисному работнику, где вы можете перехватить их с помощью прослушивателя событий fetch . Отсюда вы можете передать данные обратно на страницу переднего плана с помощью postMessage() или передать их на сервер:

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);
    })());
  }
});

Проверка общего контента

Обязательно проверяйте входящие данные. К сожалению, нет никакой гарантии, что другие приложения будут использовать соответствующий контент в правильном параметре.

Например, в Android поле url будет пустым , поскольку оно не поддерживается в общей системе Android. Вместо этого URL-адреса часто появляются в text поле или иногда в поле title .

Поддержка браузера

API-интерфейс Web Share Target поддерживается, как описано ниже:

На всех платформах ваше веб-приложение должно быть установлено, прежде чем оно станет потенциальным объектом для получения общих данных.

Примеры приложений

• Сквош
• Альбом для вырезок PWA

Показать поддержку API

Планируете ли вы использовать API-интерфейс Web Share Target? Ваша публичная поддержка помогает команде Chromium расставлять приоритеты в функциях и показывает другим поставщикам браузеров, насколько важно их поддерживать.

Отправьте твит @ChromiumDev, используя хэштег #WebShareTarget , и сообщите нам, где и как вы его используете.