Добавление поддержки приложений для веб-сайтов, использующих обработчики URI приложений

  • Статья

Приложения для веб-сайтов связывают ваше приложение с веб-сайтом, чтобы при переходе по ссылке на ваш веб-сайт вместо открытия браузера запускалось ваше приложение. Если ваше приложение не установлено, ваш сайт откроется в браузере, как обычно. Пользователи могут доверять такому подходу, поскольку только проверенные владельцы содержимого могут зарегистрироваться для предоставления ссылки. Пользователи смогут проверка все свои зарегистрированные ссылки "веб-приложение", перейдя в раздел Параметры > Приложения Приложения > для веб-сайтов.

Для включения привязки приложения к веб-страницам необходимо выполнить следующие требования.

  • Определите URI, которые ваше приложение будет обрабатывать, в файле манифеста
  • JSON-файл, определяющий связь между вашим приложением и веб-сайтом, с именем семейства пакетов для приложения должен находиться в той же корневой папке, что и объявление манифеста приложения.
  • Обработка активации в приложении.

Примечание

Начиная с обновления Windows 10 Creators, поддерживаемые ссылки, щелкаемые в устаревшая версия Microsoft Edge, запускают соответствующее приложение. Поддерживаемые ссылки, щелкаемые в других браузерах (например, Microsoft Edge Chromium, Интернет-Обозреватель и т. д.), помогут вам оставаться в режиме просмотра.

Ваше приложение должно распознавать URI для веб-сайтов, которые оно будет обрабатывать. Для этого добавьте регистрацию расширения Windows.appUriHandler в файл манифеста вашего приложения Package.appxmanifest.

Например, если адрес вашего сайта — msn.com, следует внести следующую запись в манифест приложения:

<Applications>
  <Application ... >
      ...
      <Extensions>
         <uap3:Extension Category="windows.appUriHandler">
          <uap3:AppUriHandler>
            <uap3:Host Name="msn.com" />
          </uap3:AppUriHandler>
        </uap3:Extension>
      </Extensions>
  </Application>
</Applications>

Приведенное выше объявления регистрирует ваше приложение для обработки ссылок, относящихся к указанному узлу. Если у вашего сайта несколько адресов (например, m.example.com, www.example.com и example.com), добавьте отдельную запись <uap3:Host Name=... /> в разделе <uap3:AppUriHandler> для каждого адреса.

Связывание приложения и веб-сайта в JSON-файле

Для обеспечения возможности открытия расположенного на сайте содержимого вашим приложением добавьте имя семейства пакетов вашего приложения в JSON-файл, расположенный в корневом каталоге вашего веб-сервера или в известном каталоге в домене. Это указывает, что ваш сайт дает согласие на открытие содержимого в перечисленных приложениях. Имя семейства пакетов можно найти в разделе Packages в конструкторе манифеста приложения.

Важно!

JSON-файл не должен иметь расширение .json.

Создайте JSON-файл (без расширения .json) с именем windows-app-web-link и укажите имя семейства пакетов вашего приложения. Пример:

[{
  "packageFamilyName" : "Your app's package family name, e.g MyApp_9jmtgj1pbbz6e",
  "paths" : [ "*" ],
  "excludePaths" : [ "/news/*", "/blog/*" ]
 }]

Windows установит https-соединение с вашим сайтом и будет искать соответствующий JSON-файл на вашем сервере.

подстановочные знаки;

В приведенном выше примере JSON-файла демонстрируется использование подстановочных символов. Подстановочные символы позволяют поддерживать разнообразные ссылки, используя меньше строк кода. Привязка приложений к Интернету поддерживает два типа подстановочных символов в файле JSON:

Подстановочный знак Описание
* Представляет любую подстроку
? Представляет единичный символ

Например, в "excludePaths" : [ "/news/*", "/blog/*" ] приведенном выше примере ваше приложение будет поддерживать все пути, начинающиеся с адреса веб-сайта (например, msn.com), кроме путей в /news/ и /blog/. msn.com/weather.html будет поддерживаться, но не msn.com/news/topnews.html.

Несколько приложений

Если вы хотите привязать к своему сайту два приложения, укажите оба имени семейства пакетов приложения в вашем JSON-файле windows-app-web-link. Возможна поддержка обоих приложений. Пользователю будет предлагаться выбрать способ открытия ссылки по умолчанию, если установлены оба приложения. Если они захотят изменить ссылку по умолчанию позже, они могут изменить ее в разделе Параметры > Приложения для веб-сайтов. Разработчики также могут изменить файл JSON в любое время, и изменения могут вступить в силу в тот же день, но не позднее чем через 8 дней после обновления.

[{
  "packageFamilyName": "Your apps's package family name, e.g MyApp_9jmtgj1pbbz6e",
  "paths": [ "*" ],
  "excludePaths" : [ "/news/*", "/blog/*" ]
 },
 {
  "packageFamilyName": "Your second app's package family name, for example, MyApp2_8jmtgj2pbbz6e",
  "paths": [ "/example/*", "/links/*" ]
 }]

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

Пути исключений проверяются в первую очередь, и, если обнаруживается соответствие, эта страница будет открыта в браузере, а не в заданном приложении. В приведенном выше примере "/news/*" включает все страницы в этом пути, а "/news*" (без косой черты "новости") включает все пути в разделе "news*", например "newslocal/", "newsinternational/" и т. д.

Обработка ссылок на активацию для привязки ссылки к содержимому

Перейдите к файлу App.xaml.cs в вашем проекте Visual Studio и добавьте обработку связанного содержимого в разделе OnActivated(). В следующем примере страница, открываемая в приложении, зависит от URI:

protected override void OnActivated(IActivatedEventArgs e)
{
    Frame rootFrame = Window.Current.Content as Frame;
    if (rootFrame == null)
    {
        ...
    }

    // Check ActivationKind, Parse URI, and Navigate user to content
    Type deepLinkPageType = typeof(MainPage);
    if (e.Kind == ActivationKind.Protocol)
    {
        var protocolArgs = (ProtocolActivatedEventArgs)e;        
        switch (protocolArgs.Uri.AbsolutePath)
        {
            case "/":
                break;
            case "/index.html":
                break;
            case "/sports.html":
                deepLinkPageType = typeof(SportsPage);
                break;
            case "/technology.html":
                deepLinkPageType = typeof(TechnologyPage);
                break;
            case "/business.html":
                deepLinkPageType = typeof(BusinessPage);
                break;
            case "/science.html":
                deepLinkPageType = typeof(SciencePage);
                break;
        }
    }

    if (rootFrame.Content == null)
    {
        // Default navigation
        rootFrame.Navigate(deepLinkPageType, e);
    }

    // Ensure the current window is active
    Window.Current.Activate();
}

Важно! Не забудьте заменить заключительный фрагмент if (rootFrame.Content == null) кодом rootFrame.Navigate(deepLinkPageType, e);, как показано в примере выше.

Тестирование: локальное средство проверки

Вы можете тестировать конфигурацию своего приложения и веб-сайта путем запуска средства проверки регистрации хоста приложения, расположенного в папке:

%windir%\system32\AppHostRegistrationVerifier.exe

Проверяйте конфигурацию своего приложения и веб-сайта путем запуска этого средства со следующими параметрами:

AppHostRegistrationVerifier.exehostname packagefamilyname filepath

  • Hostname: ваш веб-сайт (например, microsoft.com)
  • Package Family Name: имя семейства пакетов вашего приложения
  • Путь к файлу: JSON-файл для локальной проверки (например, C:\SomeFolder\windows-app-web-link).

Если средство ничего не возвращает, проверки будут работать для этого файла при отправке. Если возникает код ошибки, функция не будет работать.

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

HKCU\Software\Classes\LocalSettings\Software\Microsoft\Windows\CurrentVersion\ AppModel\SystemAppData\YourApp\AppUriHandlers

Имя ключа: ForceValidation значение: 1

Тестирование: проверка в Интернете

Закройте свое приложение, чтобы убедиться, что приложение запускается, когда вы нажимаете на ссылку. Затем скопируйте адрес одного из поддерживаемых путей на вашем веб-сайте. Например, если адрес веб-сайта — "msn.com", а один из путей поддержки — "path1", следует использовать http://msn.com/path1

Убедитесь, что ваше приложение закрыто. Нажмите клавишу Windows + R, чтобы открыть диалоговое окно Выполнить, и вставьте ссылку в этом окне. Вместо браузера должно запуститься ваше приложение.

Кроме того, можно протестировать приложение, запустив его из другого приложения с помощью API LaunchUriAsync. Можно также использовать этот API для тестирования на телефонах.

Если вы хотите отслеживать логику активации протокола, установите точку останова в обработчике событий OnActivated.

Советы по AppUriHandlers.

  • Следите за тем, чтобы были указаны только те ссылки, которые ваше приложение может обработать.
  • Перечисляйте все узлы, которые вы будете поддерживать. Обратите внимание, что www.example.com и example.com — это различные узлы.
  • Пользователи могут выбрать, какое приложение они предпочитают использовать для открытия сайтов, в Параметрах.
  • Файл JSON должен быть размещен на https-сервере.
  • Если вам нужно изменить пути, которые вы хотите поддерживать, можно повторно опубликовать JSON-файл, не переиздавая приложение. Пользователи увидят изменения через 1-8 дней.
  • Все неопубликованные приложения с AppUriHandlers будут иметь проверенные ссылки для данного узла при установке. Для проверки функциональности не требуется передавать JSON-файл на сайт.
  • Эта функция работает всякий раз, когда ваше приложение является приложением UWP, запущенным с помощью LaunchUriAsync , или классическим приложением Windows, запущенным с помощью ShellExecuteEx. Если URL-адрес совпадает с зарегистрированным обработчиком URI приложения, вместо браузера будет запущено приложение.

См. также раздел

Пример проекта веб-приложенияРегистрация windows.protocolАктивация обработки URIПример привязки запуска показывает, как использовать API LaunchUriAsync().