アプリの URI ハンドラーを使用してアプリを Web サイトで有効にする

[アーティクル]
06/02/2023

Web サイト用のアプリ機能によってアプリが Web サイトに関連付けられ、Web サイトへのリンクを開いたときに、ブラウザーが開く代わりにアプリが起動されます。アプリがインストールされていない場合は、通常のように、ブラウザーで Web サイトが開きます。検証済みのコンテンツ所有者だけがリンクに登録できるため、ユーザーはこのエクスペリエンスを信頼することができます。ユーザーは、登録された Web とアプリのリンクすべてを、[設定] > [アプリ] > [Web サイト用のアプリ] で確認できます。

Web とアプリのリンクを有効にするには、次を行う必要があります。

アプリが処理する URI をマニフェストファイル内に指定します。
アプリと Web サイト間の関連付けを定義する JSON ファイル。アプリのマニフェスト宣言と同じホストのルートに配置されているこの JSON ファイルに、アプリのパッケージファミリ名を指定します。
アプリでアクティブ化を処理します。

注意

Windows 10 Creators の更新以降、Microsoft Edge 従来版でクリックされたサポートされているリンクが、対応するアプリを起動します。他のブラウザー (Microsoft Edge Chromium、インターネットエクスプローラーなど) でクリックされたサポートされているリンクは、閲覧エクスペリエンスを維持します。

http リンクや https リンクを処理できるようにアプリマニフェストに登録する

アプリでは、処理する Web サイトの URI を指定する必要があります。そのためには、Windows.appUriHandler 拡張機能登録をアプリのマニフェストファイル Package.appxmanifest に追加します。

たとえば、Web サイトのアドレスが “msn.com” である場合は、アプリのマニフェスト内に次のエントリを作成します。

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

上記の宣言によって、指定されたホストからのリンクを処理するようにアプリが登録されます。 Web サイトに複数のアドレス (m.example.com、www.example.com、example.com など) がある場合は、各アドレスに対応するように、<uap3:AppUriHandler> 内に個別の <uap3:Host Name=... /> エントリを追加します。

アプリと Web サイトを JSON ファイルに関連付ける

アプリで開くことができるのがお客様の Web サイトのコンテンツのみにする場合は、Web サーバーのルートまたはドメイン上の既知のディレクトリに配置されている JSON ファイル内に、アプリのパッケージファミリ名を指定します。これにより、お客様の Web サイトは、指定されている一連のアプリがサイト上のコンテンツを開くことに同意したことになります。パッケージファミリ名は、アプリケーションマニフェストデザイナーの [パッケージ] セクションで確認できます。

重要

JSON ファイルには、.json ファイル接尾辞を指定しないでください。

windows-app-web-link という名前で JSON ファイルを作成し (.json ファイル拡張子は付加しない)、アプリのパッケージファミリ名を指定します。次に例を示します。

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

Windows によって、Web サイトへの https 接続が行われ、Web サーバー上の対応する JSON ファイルが検索されます。

ワイルドカード

上記の JSON ファイルの例では、ワイルドカードの使用も示しています。ワイルドカードを使用すると、数行のコードでさまざまなリンクをサポートすることができます。 Web とアプリのリンクでは、JSON ファイルで 2 種類のワイルドカードを使用できます。

ワイルドカード	説明
*	任意の部分文字列を表します
?	1 つの文字を表します

たとえば、上記の例のように "excludePaths" : [ "/news/*", "/blog/*" ] と指定すると、アプリでは、Web サイトのアドレス (たとえば msn.com) で始まるすべてのパスがサポートされますが、/news/ と /blog/ の下にあるパスはサポートされません。つまり、msn.com/weather.html はサポートされますが、msn.com/news/topnews.html はサポートされません。

複数のアプリ

Web サイトにリンクするアプリが 2 つある場合、両方のアプリケーションのパッケージファミリ名を windows-app-web-link JSON ファイルに指定します。これで、どちらのアプリもサポートされます。両方のアプリがインストールされている場合、ユーザーに対して、どちらを既定のリンクとして選ぶかが示されます。既定のリンクを後で変更する場合は、[設定] > [Web サイト用のアプリ] で変更できます。また、開発者はいつでも 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' の後にスラッシュを付けない) と指定すると、‘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); に置き換えてください。

テストの実行: ローカルの検証ツール

アプリホスト登録検証ツールを実行して、アプリと Web サイトの構成をテストできます。このツールは次の場所にあります。

%windir%\system32\AppHostRegistrationVerifier.exe

次のパラメーターを使用してこのツールを実行し、アプリと Web サイトの構成をテストしてください。

AppHostRegistrationVerifier.exehostname packagefamilyname filepath

ホスト名: Web サイト (例: 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

テストの実行: Web 検証

リンクをクリックしたときにアプリがアクティブ化されるかどうか確認するには、アプリケーションを閉じておきます。次に、Web サイトでサポートされるパスのいずれかのアドレスをコピーします。たとえば、Web サイトのアドレスが “msn.com” であり、サポートされるパスの 1 つが “path1” である場合、http://msn.com/path1 を使用します。

アプリが閉じていることを確認します。 Windows キー + R キーを押し、[ファイル名を指定して実行] ダイアログボックスを開き、ウィンドウにリンクを貼り付けます。 Web ブラウザーではなく、アプリが起動します。

また、LaunchUriAsync API を使用し、他のアプリから目的のアプリを起動してテストすることもできます。この API を使用して、電話でテストすることもできます。

プロトコルのアクティブ化ロジックを実行する場合は、OnActivated イベントハンドラーにブレークポイントを設定します。

AppUriHandlers のヒント:

アプリで処理できるリンクのみを必ず指定してください。
サポートするすべてのホストの一覧を指定します。 www.example.com と example.com は、異なるホストになります。
ユーザーは、Web サイトを処理する特定のアプリを [設定] で選ぶことができます。
JSON ファイルは、https サーバーにアップロードする必要があります。
サポートするパスを変更する場合は、アプリを再公開しなくても、JSON ファイルを再公開することができます。ユーザーには、1 ~ 8 日の間、変更内容が表示されます。
AppUriHandlers と共にサイドロードされたすべてのアプリでは、インストール時にホストのリンクが検証されます。機能をテストするために JSON ファイルをアップロードする必要はありません。
この機能は、アプリが LaunchUriAsync によって起動された UWP アプリである場合、または ShellExecuteEx によって起動された Windows デスクトップアプリである場合は、必ず動作します。 URL が、登録されているアプリの URI ハンドラーに対応している場合、ブラウザーではなくアプリが起動されます。

こちらもご覧ください

Web とアプリのサンプルプロジェクト windows.protocol の登録 URI のアクティブ化の処理関連付けによる起動のサンプルでは、LaunchUriAsync() API の使用方法を説明します。

アプリの URI ハンドラーを使用してアプリを Web サイトで有効にする

http リンクや https リンクを処理できるようにアプリマニフェストに登録する

アプリと Web サイトを JSON ファイルに関連付ける

ワイルドカード

複数のアプリ

コンテンツにリンクするためのアクティブ化でリンクを処理する

テストの実行: ローカルの検証ツール

テストの実行: Web 検証

AppUriHandlers のヒント:

こちらもご覧ください

フィードバック

フィードバック

その他のリソース

アプリの URI ハンドラーを使用してアプリを Web サイトで有効にする

http リンクや https リンクを処理できるようにアプリ マニフェストに登録する

アプリと Web サイトを JSON ファイルに関連付ける

ワイルドカード

複数のアプリ

コンテンツにリンクするためのアクティブ化でリンクを処理する

テストの実行: ローカルの検証ツール

テストの実行: Web 検証

AppUriHandlers のヒント:

こちらもご覧ください

フィードバック

フィードバック

その他のリソース

http リンクや https リンクを処理できるようにアプリマニフェストに登録する