Получение общих данных с помощью 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 , и сообщите нам, где и как вы его используете.