Прочитать на английском

Поделиться через

Включение приложений для веб-сайтов с помощью обработчиков URI приложений

  • Статья

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

Важно!

Начиная с обновления Windows 10 Creators и во всех версиях Windows 11 поддерживаемые ссылки, щелкнутые в Microsoft Edge Legacy, будут запускать соответствующее приложение. Поддерживаемые ссылки, щелкнутые в поддерживаемых браузерах (например, Microsoft Edge Chromium, Firefox, Internet Explorer и т. д.), позволят продолжить использование браузера без прерывания просмотра.

Чтобы включить связывание между вебом и приложением, вам потребуется:

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

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

Например, если адрес веб-сайта имеет значение "msn.com", вы сделаете следующую запись в манифесте приложения:

XML 
<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, and example.com), добавьте отдельную запись <uap3:Host Name=... /> внутри <uap3:AppUriHandler> для каждого адреса.

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

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

Важно!

Файл JSON не должен иметь суффикс .json.

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

JSON 
[{
  "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-файл в любое время и просматривать изменения до того же дня, но не более восьми дней после обновления.

JSON 
[{
  "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") включает любые пути под "news*", например, "newslocal/", "newsinternational/" и т. д.

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

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

CS 
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.exeимя_узла packagefamilyname filepath

  • Имя узла: ваш веб-сайт (например, microsoft.com)
  • Имя семейства пакетов (PFN): PFN вашего приложения
  • Путь к файлу: 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.

Советы для обработчиков URI приложений

Эти советы помогут вам получить большую часть функции AppUriHandlers:

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

Связанное содержимое

пример проекта Web-to-App

регистрация windows.protocol

обработка активации URI