Разрешите установленным PWA обрабатывать URL, чтобы лучше интегрироваться с системой.
Что такое PWA как обработчики URL?
Представьте, что вы общаетесь с другом в мессенджере, например в Сообщениях на macOS, и обсуждаете музыку. Представьте, что у вас обоих на устройствах установлено прогрессивное веб-приложение music.example.com. Если вы хотите поделиться с другом любимым треком, отправьте ему ссылку на контент, например https://music.example.com/rick-astley/never-gonna-give-you-up. Поскольку эта ссылка довольно длинная, разработчики music.example.com могли решить добавить дополнительную короткую ссылку на каждый трек, например https://🎵.example.com/r-a/n-g-g-y-u.
Функция "PWA как обработчики URL" позволяет таким приложениям, как music.example.com, регистрироваться в качестве обработчиков URL, соответствующих шаблонам https://music.example.com, https://*.music.example.com или https://🎵.example.com. Благодаря этому ссылки, открываемые не из PWA, например из мессенджера или почтового клиента, будут открываться в установленном PWA, а не на вкладке браузера.
Функция "PWA как обработчики URL" состоит из двух дополнений:
- Элемент манифеста веб-приложения
"url_handlers". - Формат файла
web-app-origin-associationдля проверки связей URL, входящих и не входящих в область действия.
Рекомендуемые варианты использования PWA в качестве обработчиков URL
Примеры сайтов, которые могут использовать этот API:
- Сайты с потоковой передачей музыки или видео, чтобы ссылки на треки или плейлисты открывались в проигрывателе приложения.
- Новостные приложения или RSS-ридеры, в которых сайты, на которые подписан пользователь, открываются в режиме чтения.
Как использовать прогрессивные веб-приложения в качестве обработчиков URL
Включить с помощью about://flags
Чтобы протестировать обработчики URL в PWA локально без токена эксперимента с источником, включите параметр #enable-desktop-pwas-url-handling в about://flags.
Элемент манифеста веб-приложения "url_handlers"
Чтобы связать установленное прогрессивное веб-приложение с шаблонами URL, укажите их в манифесте веб-приложения. Это происходит через элемент "url_handlers". Он принимает массив объектов со свойством origin, которое является обязательным объектом string, представляющим собой шаблон для сопоставления источников. В шаблонах можно использовать префикс с подстановочным знаком (*), чтобы включить несколько субдоменов (например, https://*.example.com). URL, соответствующие этим источникам, могут обрабатываться веб-приложением. Схема всегда считается https://, но ее нужно указывать явно.
В следующем фрагменте манифеста веб-приложения показано, как это можно настроить на примере музыкального PWA из вводного абзаца. Вторая запись с подстановочным знаком ("https://*.music.example.com") гарантирует, что приложение также будет активировано для https://www.music.example.com или других возможных примеров, таких как https://marketing-activity.music.example.com.
{
"url_handlers": [
{
"origin": "https://music.example.com"
},
{
"origin": "https://*.music.example.com"
},
{
"origin": "https://🎵.example.com"
}
]
}
Файл web-app-origin-association
Поскольку PWA находится в другом источнике (music.example.com), чем некоторые URL, которые ему нужно обрабатывать (например, https://🎵.example.com), приложению необходимо подтвердить право собственности на эти другие источники. Это происходит в файле web-app-origin-association, размещенном в других источниках.
Файл должен содержать действительный код JSON. Структура верхнего уровня – это объект с элементом "web_apps". Этот элемент представляет собой массив объектов, каждый из которых соответствует уникальному веб-приложению. Каждый объект содержит:
| Поле | Описание | Тип | По умолчанию |
|---|---|---|---|
"manifest" |
(Обязательно) Строка URL манифеста веб-приложения, связанного с PWA. | string |
Н/Д |
"details" |
Объект, содержащий массивы включенных и исключенных шаблонов URL (необязательно). | object |
Н/Д |
Каждый объект "details" содержит:
| Поле | Описание | Тип | По умолчанию |
|---|---|---|---|
"paths" |
Массив допустимых строк пути (необязательно) | string[] |
[] |
"exclude_paths" |
Массив строк запрещенных путей (необязательно) | string[] |
[] |
Ниже приведен пример файла web-app-origin-association для музыкального PWA, описанного выше. Он будет размещен в источнике 🎵.example.com и установит связь с PWA music.example.com, идентифицированным по URL манифеста веб-приложения.
{
"web_apps": [
{
"manifest": "https://music.example.com/manifest.json",
"details": {
"paths": ["/*"],
"exclude_paths": ["/internal/*"]
}
}
]
}
Когда URL считается совпадающим?
Прогрессивное веб-приложение может обрабатывать URL, если выполняются оба следующих условия:
- URL соответствует одной из строк источника в правиле
"url_handlers". - Браузер может проверить с помощью соответствующего файла
web-app-origin-association, что каждый источник согласен разрешить этому приложению обрабатывать такой URL.
Обнаружение файлов web-app-origin-association
Чтобы браузер мог обнаружить файл web-app-origin-association, разработчикам необходимо
поместить его web-app-origin-associationв папку
/.well-known/ в корневом каталоге приложения.
Чтобы это сработало, файл должен называться именно web-app-origin-association.
Демоверсии
Чтобы протестировать PWA в качестве обработчиков URL, установите флаг браузера, как описано выше, а затем установите PWA по адресу https://mandymsft.github.io/pwa/. В манифесте веб-приложения указано, что оно обрабатывает URL со следующими шаблонами URL: https://mandymsft.github.io и https://luhuangmsft.github.io. Поскольку у него другой источник (luhuangmsft.github.io), чем у PWA, PWA на mandymsft.github.io должно подтвердить право собственности. Это делается с помощью файла web-app-origin-association, размещенного по адресу https://luhuangmsft.github.io/.well-known/web-app-origin-association.
Чтобы проверить, работает ли функция, отправьте себе тестовое сообщение в мессенджере или электронное письмо, которое можно открыть в почтовом клиенте, не являющемся веб-версией, например в Почте на macOS. В письме или текстовом сообщении должна быть ссылка https://mandymsft.github.io или https://luhuangmsft.github.io. Обе ссылки должны открываться в установленном PWA.
Безопасность и разрешения
Команда Chromium разработала и реализовала PWA в качестве обработчиков URL, используя основные принципы, определенные в статье Controlling Access to Powerful Web Platform Features (Управление доступом к мощным функциям веб-платформы), включая контроль со стороны пользователя, прозрачность и эргономику.
Возможности пользователей
Если несколько PWA зарегистрированы как обработчики URL для определенного шаблона URL, пользователю будет предложено выбрать, какое PWA он хочет использовать для обработки шаблона (если он вообще хочет это делать). Переходы, которые начинаются на вкладке браузера, не рассматриваются в этом предложении. Оно касается только переходов, которые начинаются за пределами браузера.
Прозрачность
Если во время установки PWA по какой-либо причине не удастся проверить связь, браузер не зарегистрирует приложение как активный обработчик для затронутых URL. Неправильно реализованные обработчики URL могут использоваться для перехвата трафика сайтов. Поэтому механизм связывания приложений – важная часть схемы.
Приложения для конкретных платформ уже могут использовать API операционной системы для перечисления установленных приложений в системе пользователя. Например, приложения в Windows могут использовать API FindAppUriHandlersAsync для перечисления обработчиков URL. Если прогрессивные веб-приложения зарегистрированы в Windows как обработчики URL на уровне ОС, их присутствие будет видно другим приложениям.
Сохранение разрешений
Источник может в любое время изменить свои связи с PWA. Браузеры будут регулярно пытаться повторно подтвердить связи установленных веб-приложений. Если повторная проверка регистрации обработчика URL не удалась из-за того, что данные о связи изменились или больше недоступны, браузер удалит регистрацию.
Как оставить отзыв
Команда Chromium хочет узнать о вашем опыте работы с PWA в качестве обработчиков URL.
Расскажите нам о дизайне API
Что-то в API работает не так, как вы ожидали? Или, может быть, вам не хватает методов или свойств, чтобы реализовать свою идею? У вас есть вопросы или комментарии по поводу модели безопасности? Сообщите о проблеме со спецификацией в соответствующем хранилище GitHub или добавьте комментарий к существующей проблеме.
Сообщить о проблеме с реализацией
Вы обнаружили ошибку в реализации Chromium? Или реализация отличается от спецификации?
Сообщите об ошибке на сайте new.crbug.com. Опишите проблему как можно подробнее, укажите, как ее воспроизвести, и введите UI>Browser>WebAppInstalls в поле Components (Компоненты).
Поддержка API
Планируете ли вы использовать PWA в качестве обработчиков URL? Ваша поддержка помогает команде Chromium определять приоритеты функций и показывает другим поставщикам браузеров, насколько важно их поддерживать.
Отправьте твит на @ChromiumDev с хештегом #URLHandlers и расскажите, где и как вы его используете.
Полезные ссылки
- Общедоступное объяснение
- Демоверсия | Исходный код демоверсии
- Ошибка отслеживания Chromium
- Запись на сайте ChromeStatus.com
- Компонент Blink:
UI>Browser>WebAppInstalls - Проверка TAG
- документации Microsoft
Благодарности
Спецификацию и реализацию обработки URL в прогрессивных веб-приложениях разработали Лу Хуан (Lu Huang) и Мэнди Чэнь (Mandy Chen) из команды Microsoft Edge. Этот документ проверил Джо Медли (Joe Medley).