Abilitare le app per i siti Web usando i gestori URI delle app

  • Articolo

Le app per i siti Web associano l'app a un sito Web in modo che quando un utente apre un collegamento al sito Web, l'app viene avviata invece di aprire il browser. Se l'app non è installata, il sito Web viene aperto nel browser come di consueto. Gli utenti possono considerare attendibile questa esperienza perché solo i proprietari di contenuti verificati possono registrarsi per un collegamento. Gli utenti potranno controllare tutti i collegamenti da Web a app registrati passando a Impostazioni > App > App per siti Web.

Per abilitare il collegamento da Web a app, è necessario:

  • Identificare gli URI che l'app gestirà nel file manifesto
  • Un file JSON che definisce l'associazione tra l'app e il sito Web. con il nome della famiglia di pacchetti dell'app nella stessa radice host della dichiarazione del manifesto dell'app.
  • Gestire l'attivazione nell'app.

Nota

A partire dall'aggiornamento di Windows 10 Creators, i collegamenti supportati cliccati in Versione precedente di Microsoft Edge avvieranno l'app corrispondente. I collegamenti supportati sono stati selezionati in altri browser (ad esempio, Microsoft Edge Chromium, Internet Explorer e così via), vi manterranno nell'esperienza di esplorazione.

L'app deve identificare gli URI per i siti Web che gestirà. A tale scopo, aggiungere la registrazione dell'estensione Windows.appUriHandler al file manifesto dell'app Package.appxmanifest.

Ad esempio, se l'indirizzo del sito Web è "msn.com", si deve inserire la voce seguente nel manifesto dell'app:

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

La dichiarazione precedente registra l'app per gestire i collegamenti dall'host specificato. Se il sito Web ha più indirizzi (ad esempio: m.example.com, www.example.com, e example.com) aggiungere una voce separata <uap3:Host Name=... /> all'interno di <uap3:AppUriHandler> per ogni indirizzo.

Associare l'app e il sito Web a un file JSON

Per assicurarsi che solo l'app possa aprire il contenuto nel sito Web, includere il nome della famiglia di pacchetti dell'app in un file JSON che si trova nella radice del server Web o nella directory nota del dominio. Questo significa che il sito Web fornisce il consenso per le app elencate per aprire il contenuto nel sito. È possibile trovare il nome della famiglia di pacchetti nella sezione Pacchetti nella finestra di progettazione del manifesto dell'app.

Importante

Il file JSON non deve avere un suffisso di file .json.

Creare un file JSON (senza l'estensione di file .json) denominato windows-app-web-link e specificare il nome della famiglia di pacchetti dell'app. Ad esempio:

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

Windows effettuerà una connessione https al sito Web e cercherà il file JSON corrispondente nel server Web.

Caratteri jolly

L'esempio di file JSON precedente illustra l'uso di caratteri jolly. I caratteri jolly consentono di supportare un'ampia gamma di collegamenti con un minor numero di righe di codice. Il collegamento da Web a app supporta due tipi di caratteri jolly nel file JSON:

Wildcard (Carattere jolly) Descrizione
* Rappresenta qualsiasi sottostringa
? Rappresenta un singolo carattere

Ad esempio, come illustrato "excludePaths" : [ "/news/*", "/blog/*" ] nell'esempio precedente, l'app supporterà tutti i percorsi che iniziano con l'indirizzo del sito Web (ad esempio, msn.com), ad eccezione di quelli in /news/ e /blog/. msn.com/weather.html sarà supportato, ma non msn.com/news/topnews.html.

Più app

Se si hanno due app da collegare al sito Web, elencare entrambi i nomi della famiglia di pacchetti dell'applicazione nel file JSON windows-app-web-link. Entrambe le app possono essere supportate. L'utente verrà visualizzato con una scelta di quale è il collegamento predefinito se entrambi sono installati. Se si vuole modificare il collegamento predefinito in un secondo momento, è possibile modificarlo in Impostazioni > App per siti Web. Gli sviluppatori possono anche modificare il file JSON in qualsiasi momento e visualizzare la modifica all'inizio dello stesso giorno, ma non dopo otto giorni dopo l'aggiornamento.

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

Per offrire un'esperienza ottimale per gli utenti, usare i percorsi di esclusione per assicurarsi che il contenuto solo online sia escluso dai percorsi supportati nel file JSON.

I percorsi di esclusione vengono prima controllati e se esiste una corrispondenza con la pagina corrispondente verrà aperta con il browser anziché con l'app designata. Nell'esempio precedente ,'/news/*' include tutte le pagine in tale percorso mentre '/news*' (nessuna barra tracciata 'news') include tutti i percorsi in 'news*' come 'newslocal/', 'newsinternational/' e così via.

Gestire i collegamenti all'attivazione per il collegamento al contenuto

Passare a App.xaml.cs nella soluzione Visual Studio dell'app e in OnActivated() aggiungere la gestione per il contenuto collegato. Nell'esempio seguente la pagina aperta nell'app dipende dal percorso 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 Assicurarsi di sostituire la logica finale if (rootFrame.Content == null) con rootFrame.Navigate(deepLinkPageType, e); come illustrato nell'esempio precedente.

Testarlo: strumento di convalida locale

È possibile testare la configurazione dell'app e del sito Web eseguendo lo strumento di verifica della registrazione dell'host dell'app disponibile in:

%windir%\system32\AppHostRegistrationVerifier.exe

Testare la configurazione dell'app e del sito Web eseguendo questo strumento con i parametri seguenti:

AppHostRegistrationVerifier.exehostname packagefamilyname filepath

  • Hostname: sito Web (ad esempio, microsoft.com)
  • Nome famiglia di pacchetti (PFN): PFN dell'app
  • Percorso file: file JSON per la convalida locale (ad esempio, C:\SomeFolder\windows-app-web-link)

Se lo strumento non restituisce alcun elemento, la convalida funzionerà su tale file quando viene caricato. Se è presente un codice di errore, non funzionerà.

È possibile abilitare la chiave del Registro di sistema seguente per forzare la corrispondenza dei percorsi per le app trasferite localmente come parte della convalida locale:

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

Keyname: ForceValidation Valore: 1

Testarlo: convalida Web

Chiudere l'applicazione per verificare che l'app sia attivata quando si fa clic su un collegamento. Copiare quindi l'indirizzo di uno dei percorsi supportati nel sito Web. Ad esempio, se l'indirizzo del sito Web è "msn.com" e uno dei percorsi di supporto è "path1", si userà http://msn.com/path1

Verificare che l'app sia chiusa. Premere Tasto Windows + R per aprire la finestra di dialogo Esegui e incollare il collegamento nella finestra. L'app deve essere avviata invece del browser Web.

È anche possibile testare l'app avviandola da un'altra app usando l'API LaunchUriAsync . È possibile usare questa API anche per testare i telefoni.

Se si vuole seguire la logica di attivazione del protocollo, impostare un punto di interruzione nel gestore eventi OnActivated.

Suggerimenti per AppUriHandlers:

  • Assicurarsi di specificare solo i collegamenti che l'app può gestire.
  • Elencare tutti gli host supportati. Si noti che www.example.com e example.com sono host diversi.
  • Gli utenti possono scegliere l'app che preferiscono gestire i siti Web in Impostazioni.
  • Il file JSON deve essere caricato in un server https.
  • Se è necessario modificare i percorsi che si desidera supportare, è possibile ripubblicare il file JSON senza ripubblicare l'app. Gli utenti vedranno le modifiche in 1-8 giorni.
  • Tutte le app trasferite localmente con AppUriHandlers avranno collegamenti convalidati per l'host durante l'installazione. Non è necessario caricare un file JSON per testare la funzionalità.
  • Questa funzionalità funziona ogni volta che l'app è un'app UWP avviata con LaunchUriAsync o un'app desktop di Windows avviata con ShellExecuteEx. Se l'URL corrisponde a un gestore URI dell'app registrato, l'app verrà avviata invece del browser.

Vedi anche

L'esempio di progetto Web-to-Appregistrazione windows.protocolAttivazione di Handle URIesempio di avvio associazione illustra come usare l'API LaunchUriAsync().