使用應用程式 URI 處理常式為網站啟用應用程式

發行項
04/01/2024

Apps for Websites 會將您的應用程式與網站產生關聯，以便在有人開啟網站連結時啟動您的應用程式，而不是開啟瀏覽器。如果未安裝您的應用程式，您的網站會像往常一樣在瀏覽器中開啟。使用者可以信任此體驗，因為只有已驗證的內容擁有者可以註冊連結。使用者可以透過前往 [設定] > [應用程式] > [Apps for websites]，來檢查所有已註冊的網頁轉應用程式連結。

若要啟用網頁轉應用程式連結，您必須：

識別應用程式將在資訊清單檔案中處理的 URI
JSON 檔案，定義您的應用程式與網站之間的關聯。與應用程式資訊清單宣告位於相同主機根目錄的應用程式套件系列名稱。
處理應用程式中的啟用。

注意

從 Windows 10 Creators Update 開始，舊版 Microsoft Edge 中按一下的支援連結將會啟動對應的應用程式。在其他瀏覽器中按一下的支援連結 (例如 Microsoft Edge Chromium、Internet Explorer 等)，將會讓您繼續瀏覽體驗。

註冊以處理應用程式資訊清單中的 http 和 https 連結

您的應用程式必須識別其將處理之網站的 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:AppUriHandler> 內為每個位址新增個別 <uap3:Host Name=... /> 項目。

將應用程式和網站與 JSON 檔案建立關聯

為了確保只有您的應用程式可以在您的網站開啟內容，請在位於網頁伺服器根目錄的 JSON 檔案中，或位於網域上已知目錄的 JSON 檔案中包含應用程式的套件系列名稱。這表示您的網站同意列出的應用程式在您的網站上開啟內容。您可以在應用程式資訊清單設計工具的 [套件] 區段中找到套件系列名稱。

重要

JSON 檔案不應該有 .json 副檔名。

建立名為 windows-app-web-link 的 JSON 檔案 (不含 .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。

多個應用程式

如果您有兩個想要連結至網站的應用程式，請在 windows-app-web-link JSON 檔案中列出這兩個應用程式套件系列名稱。這兩個應用程式都可以支援。如果兩者都已安裝，使用者將會看到預設的連結選擇。如果他們稍後想要變更預設連結，可以在 [設定] > [Apps for Websites] 中變更。開發人員也可以隨時變更 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/」等等。

處理啟用連結至內容的連結

瀏覽至應用程式 Visual Studio 解決方案中的 App.xaml.cs ，並在 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 (套件系列名稱，PFN)：您應用程式的 PFN
File path (檔案路徑)：本機驗證的 JSON 檔案 (例如 C：\SomeFolder\windows-app-web-link)

如果此工具未傳回任何項目，驗證會在上傳時處理該檔案。如果有錯誤碼，將無法運作。

您可以啟用下列登入機碼，在本機驗證中強制比對側載應用程式的路徑：

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

Keyname：ForceValidation值：1

測試：網路驗證

關閉您的應用程式，以確認當您按一下連結時，應用程式已啟動。然後，複製網站中其中一個支援路徑的位址。例如，如果您的網站位址為「msn.com」，且其中一個支援路徑為「path1」，則會使用 http://msn.com/path1

確認您的應用程式已關閉。按下 Windows 鍵 + R 開啟 [執行] 對話方塊，並將連結貼到視窗中。您的應用程式應該會啟動，而不是網頁瀏覽器。

此外，您可以使用 LaunchUriAsync API 從另一個應用程式啟動應用程式，以測試您的應用程式。您也可以使用此 API 在手機上進行測試。

如果您想要遵循通訊協定啟用邏輯，請在 OnActivated 事件處理常式中設定中斷點。

AppUriHandlers 提示：

請務必只指定應用程式可以處理的連結。
列出您將支援的所有主機。請注意，www.example.com 和 example.com 是不同的主機。
使用者可以在 [設定] 中選擇他們偏好處理網站的應用程式。
您的 JSON 檔案必須上傳至 https 伺服器。
如果需要變更您想要支援的路徑，您可以重新發佈 JSON 檔案，而不重新發布您的應用程式。使用者會在 1-8 天內看到變更。
所有側載應用程式與 AppUriHandlers 都會在安裝時驗證主機的連結。您不需要上傳 JSON 檔案來測試此功能。
每當您的應用程式是使用 LaunchUriAsync 啟動的 UWP 應用程式，或以 ShellExecuteExecuteEx 啟動的 Windows 傳統型應用程式時，此功能就會運作。如果 URL 對應至已註冊的應用程式 URI 處理常式，則會啟動應用程式，而不是瀏覽器。

另請參閱

網站轉應用程式範例專案 windows.protocol 註冊處理 URI 啟用關聯啟動範例說明如何使用 LaunchUriAsync() API。

共用方式為