Habilitación de aplicaciones para sitios web mediante controladores de URI de aplicación

Artículo
07/04/2024

Las aplicaciones para sitios web asocian la aplicación a un sitio web para que cuando alguien abra un vínculo a su sitio web, la aplicación se inicia en lugar de abrir el explorador. Si la aplicación no está instalada, el sitio web se abre en el explorador como de costumbre. Los usuarios pueden confiar en esta experiencia porque solo los propietarios de contenido comprobados pueden registrarse para un vínculo. Los usuarios podrán comprobar todos sus vínculos web a aplicación registrados; para ello, vaya a Aplicaciones > de configuración > para sitios web.

Para habilitar la vinculación web a aplicación, deberá hacer lo siguiente:

Identificación de los URI que controlará la aplicación en el archivo de manifiesto
Archivo JSON que define la asociación entre la aplicación y el sitio web. con el nombre de familia del paquete de la aplicación en la misma raíz de host que la declaración del manifiesto de aplicación.
Controle la activación en la aplicación.

Nota:

A partir de windows 10 Creators update, los vínculos admitidos en Microsoft Edge (versión anterior) iniciarán la aplicación correspondiente. Los vínculos admitidos en otros exploradores (por ejemplo, Microsoft Edge Chromium, Internet Explorer, etc.), le mantendrán en la experiencia de exploración.

Registro para controlar vínculos http y https en el manifiesto de la aplicación

La aplicación debe identificar los URI de los sitios web que controlará. Para ello, agregue el registro de extensión Windows.appUriHandler al archivo de manifiesto de la aplicación Package.appxmanifest.

Por ejemplo, si la dirección del sitio web es "msn.com", realizaría la siguiente entrada en el manifiesto de la aplicación:

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

La declaración anterior registra la aplicación para controlar los vínculos del host especificado. Si el sitio web tiene varias direcciones (por ejemplo: m.example.com, www.example.com y example.com), agregue una entrada independiente <uap3:Host Name=... /> dentro de para <uap3:AppUriHandler> cada dirección.

Asociación de la aplicación y el sitio web con un archivo JSON

Para asegurarse de que solo la aplicación puede abrir contenido en el sitio web, incluya el nombre de familia del paquete de la aplicación en un archivo JSON ubicado en la raíz del servidor web o en el directorio conocido del dominio. Esto significa que su sitio web da su consentimiento para que las aplicaciones enumeradas abran contenido en su sitio. Puede encontrar el nombre de familia del paquete en la sección Paquetes del diseñador de manifiestos de la aplicación.

Importante

El archivo JSON no debe tener un sufijo de archivo .json.

Cree un archivo JSON (sin la extensión de archivo .json) denominado windows-app-web-link y proporcione el nombre de familia de paquete de la aplicación. Por ejemplo:

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

Windows realizará una conexión https a su sitio web y buscará el archivo JSON correspondiente en el servidor web.

Comodines

En el ejemplo de archivo JSON anterior se muestra el uso de caracteres comodín. Los caracteres comodín permiten admitir una amplia variedad de vínculos con menos líneas de código. La vinculación web a aplicación admite dos tipos de caracteres comodín en el archivo JSON:

Wildcard (Carácter comodín)	Descripción
*	Representa cualquier subcadena.
?	Representa un carácter único.

Por ejemplo, dado "excludePaths" : [ "/news/*", "/blog/*" ] en el ejemplo anterior, la aplicación admitirá todas las rutas de acceso que comienzan con la dirección del sitio web (por ejemplo, msn.com), excepto las /news/ de y /blog/. msn.com/weather.html se admitirán, pero no msn.com/news/topnews.html.

Varias aplicaciones

Si tiene dos aplicaciones que desea vincular a su sitio web, enumere ambos nombres de familia de paquetes de aplicación en el archivo JSON windows-app-web-link . Se pueden admitir ambas aplicaciones. Al usuario se le presentará una opción que es el vínculo predeterminado si ambos están instalados. Si quieren cambiar el vínculo predeterminado más adelante, pueden cambiarlo en Aplicaciones de configuración > para sitios web. Los desarrolladores también pueden cambiar el archivo JSON en cualquier momento y ver el cambio tan pronto como el mismo día, pero no más tarde de ocho días después de la actualización.

[{
  "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/*" ]
 }]

Para proporcionar la mejor experiencia para los usuarios, use las rutas de acceso de exclusión para asegurarse de que el contenido solo en línea está excluido de las rutas de acceso admitidas en el archivo JSON.

Las rutas de acceso de exclusión se comprueban primero y si hay una coincidencia con la página correspondiente se abrirá con el explorador en lugar de la aplicación designada. En el ejemplo anterior, '/news/*' incluye cualquier página bajo esa ruta de acceso mientras '/news*' (sin rutas de barra diagonal 'noticias') incluye rutas de acceso bajo 'news*' como 'newslocal/', 'newsinternational/', etc.

Controlar vínculos en Activación para vincular al contenido

Vaya a App.xaml.cs en la solución de Visual Studio de la aplicación y, en OnActivated() agregue control para el contenido vinculado. En el ejemplo siguiente, la página que se abre en la aplicación depende de la ruta de acceso del 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();
}

Importante Asegúrese de reemplazar la lógica final if (rootFrame.Content == null) por rootFrame.Navigate(deepLinkPageType, e); como se muestra en el ejemplo anterior.

Pruóbelo: Herramienta de validación local

Puede probar la configuración de la aplicación y el sitio web mediante la ejecución de la herramienta comprobador de registro del host de la aplicación que está disponible en:

%windir%\system32\AppHostRegistrationVerifier.exe

Pruebe la configuración de la aplicación y el sitio web mediante la ejecución de esta herramienta con los parámetros siguientes:

AppHostRegistrationVerifier.exe nombre de host packagefamilyname filepath

Nombre de host: su sitio web (por ejemplo, microsoft.com)
Nombre de familia de paquete (PFN): PFN de la aplicación
Ruta de acceso del archivo: el archivo JSON para la validación local (por ejemplo, C:\SomeFolder\windows-app-web-link)

Si la herramienta no devuelve nada, la validación funcionará en ese archivo cuando se cargue. Si hay un código de error, no funcionará.

Puede habilitar la siguiente clave del Registro para forzar la coincidencia de rutas de acceso para las aplicaciones cargadas localmente como parte de la validación local:

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

Keyname: ForceValidation Value: 1

Pruóbelo: Validación web

Cierre la aplicación para comprobar que la aplicación está activada al hacer clic en un vínculo. A continuación, copie la dirección de una de las rutas de acceso admitidas en su sitio web. Por ejemplo, si la dirección del sitio web es "msn.com" y una de las rutas de soporte técnico es "path1", usaría http://msn.com/path1

Compruebe que la aplicación está cerrada. Presione Tecla de Windows + R para abrir el cuadro de diálogo Ejecutar y pegue el vínculo en la ventana. La aplicación debe iniciarse en lugar del explorador web.

Además, puede probar la aplicación iniciandola desde otra aplicación mediante la API LaunchUriAsync . También puede usar esta API para probar en teléfonos.

Si desea seguir la lógica de activación del protocolo, establezca un punto de interrupción en el controlador de eventos OnActivated .

Sugerencias de AppUriHandlers:

Asegúrese de especificar solo los vínculos que la aplicación puede controlar.
Enumere todos los hosts que admitirá. Tenga en cuenta que www.example.com y example.com son hosts diferentes.
Los usuarios pueden elegir qué aplicación prefieren controlar los sitios web en Configuración.
El archivo JSON debe cargarse en un servidor https.
Si necesita cambiar las rutas de acceso que desea admitir, puede volver a publicar el archivo JSON sin volver a publicar la aplicación. Los usuarios verán los cambios en 1 a 8 días.
Todas las aplicaciones transferidas localmente con AppUriHandlers tendrán vínculos validados para el host al instalar. No es necesario cargar un archivo JSON para probar la característica.
Esta característica funciona siempre que la aplicación sea una aplicación para UWP iniciada con LaunchUriAsync o una aplicación de escritorio de Windows iniciada con ShellExecuteEx. Si la dirección URL corresponde a un controlador de URI de aplicación registrado, la aplicación se iniciará en lugar del explorador.

Consulte también

En el ejemplo de proyecto de ejemplo web a aplicación windows.protocol registration Handle URI Activation Association Launch (Inicio de asociación de activación de URI) se muestra cómo usar la API LaunchUriAsync().

Compartir a través de