앱 URI 처리기를 사용하여 웹 사이트에 앱 사용

2025-08-26

웹 사이트용 앱은 다른 사용자가 웹 사이트에 대한 링크를 열 때 브라우저를 여는 대신 앱이 시작되도록 앱을 웹 사이트와 연결합니다. 앱이 설치되지 않은 경우 웹 사이트가 평소와 같이 브라우저에서 열립니다. 확인된 콘텐츠 소유자만 링크를 등록할 수 있으므로 사용자는 이 환경을 신뢰할 수 있습니다. 사용자는 웹 사이트용 Settings > Apps > 앱으로 이동하여 등록된 모든 웹앱 링크를 확인할 수 있습니다.

중요합니다

Windows 10 크리에이터스 업데이트 및 모든 Windows 11 버전부터 Microsoft Edge 레거시에서 클릭한 지원되는 링크가 해당 앱을 시작합니다. 지원되는 브라우저(예: Microsoft Edge Chromium, Firefox, Internet Explorer 등)에서 클릭한 지원되는 링크는 검색 환경을 유지합니다.

웹-앱 연결을 사용하도록 설정하려면 다음을 수행해야 합니다.

앱이 매니페스트 파일에서 처리할 URI 식별
앱과 웹 사이트 간의 연결을 정의하는 JSON 파일입니다. 앱 매니페스트 선언과 동일한 호스트 루트에 앱 패키지 패밀리 이름을 사용합니다.
앱에서 활성화를 처리합니다.

앱 매니페스트에서 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, and example.com) 각 주소 내에 <uap3:AppUriHandler> 별도의 <uap3:Host Name=... /> 항목을 추가합니다.

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 파일을 찾습니다.

하위 도메인 지원

앱 매니페스트에 주 도메인(예: example.com)과 와일드카드 하위 도메인(예 *.example.com: )이 모두 포함된 경우 하위 도메인 연결을 사용하도록 설정하려면 JSON 파일에 필드를 추가 allowSubdomains 해야 합니다. 이 필드가 없으면 하위 도메인에 대한 링크가 앱 대신 브라우저에서 열립니다.

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

설정true되면 allowSubdomains 브라우저 대신 앱에서 하위 도메인에 subdomain.example.com/path 대한 링크가 올바르게 열립니다.

와일드카드

위의 JSON 파일 예제에서는 와일드카드를 사용하는 방법을 보여 줍니다. 와일드카드를 사용하면 코드 줄이 적은 다양한 링크를 지원할 수 있습니다. 웹앱 간 연결은 JSON 파일에서 다음 두 가지 유형의 와일드카드를 지원합니다.

와일드 카드	설명
*	모든 부분 문자열을 나타냅니다.
?	단일 문자를 나타냅니다.

예를 들어 위의 예제에서 앱 "excludePaths" : [ "/news/*", "/blog/*" ] 은 아래와 /blog/아래를 제외하고/news/ 웹 사이트의 주소(예: msn.com)로 시작하는 모든 경로를 지원합니다. msn.com/weather.html 지원되지만 msn.com/news/topnews.html않습니다.

여러 앱

웹 사이트에 연결하려는 앱이 두 개 있는 경우 windows-app-web-link JSON 파일에 애플리케이션 패키지 패밀리 이름을 모두 나열합니다. 두 앱 모두 지원될 수 있습니다. 둘 다 설치되어 있는 경우 기본 링크 중에서 선택할 수 있는 옵션이 사용자에게 표시됩니다. 나중에 기본 링크를 변경하려는 경우 웹 사이트용 설정 > 앱에서 변경할 수 있습니다. 또한 개발자는 언제든지 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 파일의 각 앱 항목에 추가 "allowSubdomains": true 합니다.

사용자에게 최상의 환경을 제공하려면 제외 경로를 사용하여 온라인 전용 콘텐츠가 JSON 파일의 지원되는 경로에서 제외되도록 합니다.

제외 경로가 먼저 선택되고 일치하는 항목이 있는 경우 지정된 앱 대신 브라우저에서 해당 페이지가 열립니다. 위의 예제에서 '/news/*'에는 해당 경로 아래에 모든 페이지가 포함되어 있지만 '/news*'(슬래시 트레일 'news'없음)에는 'newslocal/', 'newsinternational/'과 같은 'news*' 아래의 경로가 포함됩니다.

콘텐츠에 연결하기 위한 활성화의 링크 처리

앱의 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); 바꿔야 합니다.

로컬 유효성 검사 도구에서 테스트

다음에서 사용할 수 있는 앱 호스트 등록 검증 도구 도구를 실행하여 앱 및 웹 사이트의 구성을 테스트할 수 있습니다.

\system32\AppHostRegistrationVerifier.exe%windir%

다음 매개 변수를 사용하여 이 도구를 실행하여 앱 및 웹 사이트의 구성을 테스트합니다.

hostname packagefamilyname 파일 경로AppHostRegistrationVerifier.exe

호스트 이름: 웹 사이트(예: 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을 눌러 실행 대화 상자를 열고 창에 링크를 붙여넣습니다. 웹 브라우저 대신 앱이 시작됩니다.

또한 LaunchUriAsync API를 사용하여 다른 앱에서 앱을 시작하여 앱을 테스트할 수 있습니다. 이 API를 사용하여 휴대폰에서도 테스트할 수 있습니다.

프로토콜 활성화 논리를 따르려면 OnActivated 이벤트 처리기에서 중단점을 설정합니다.

AppUriHandlers 팁

이러한 팁은 AppUriHandlers 기능을 최대한 활용할 수 있도록 도와줍니다.

앱에서 처리할 수 있는 링크만 지정해야 합니다.
지원할 호스트를 모두 나열합니다. www.example.com and example.com 서로 다른 호스트입니다.
사용자는 설정에서 웹 사이트를 처리하려는 앱을 선택할 수 있습니다.
JSON 파일을 https 서버에 업로드해야 합니다.
지원하려는 경로를 변경해야 하는 경우 앱을 다시 게시하지 않고 JSON 파일을 다시 게시할 수 있습니다. 사용자는 1-8일 후에 변경 내용을 볼 수 있습니다.
AppUriHandlers를 사용하여 테스트용으로 로드된 모든 앱에는 설치할 때 호스트에 대한 유효성이 검사된 링크가 있습니다. 기능을 테스트하기 위해 JSON 파일을 업로드할 필요가 없습니다.
이 기능은 앱이 LaunchUriAsync 로 시작된 UWP 앱이거나 ShellExecuteEx에서 시작된 Windows 데스크톱 앱일 때마다 작동합니다. URL이 등록된 앱 URI 처리기에 해당하는 경우 브라우저 대신 앱이 시작됩니다.

웹-앱 예제 프로젝트

windows.protocol 등록

URI 활성화 처리