Condividi tramite

Abilitare le app per i siti Web usando i gestori URI dell'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.

Importante

A partire dall'aggiornamento di Windows 10 Creators e in tutte le versioni di Windows 11, i collegamenti supportati su cui è stato fatto clic in Microsoft Edge Legacy avvieranno l'app corrispondente. I collegamenti selezionati e supportati nei browser supportati (ad esempio, Microsoft Edge Chromium, Firefox, Internet Explorer e così via) vi manterranno nell'esperienza di navigazione.

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

  • Identificare gli URI che l'app gestirà nel file manifesto
  • 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.

L'app deve identificare gli URI per i siti Web che gestirà. Per raggiungere questo obiettivo, aggiungi la registrazione dell'estensione Windows.appUriHandler al file di manifesto dell'app Package.appxmanifest.

Ad esempio, se l'indirizzo del sito Web è "msn.com", devi 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, and example.com) aggiungere una voce <uap3:Host Name=... /> separata all'interno del <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. Per 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 del file JSON sopra riportato illustra l'uso di caratteri jolly. I caratteri jolly consentono di supportare un'ampia gamma di collegamenti con un numero ridotto di righe di codice. Il collegamento da Web a app supporta due tipi di caratteri jolly nel file JSON:

con caratteri jolly Descrizione
* Rappresenta qualsiasi sottostringa
? Rappresenta un singolo carattere

Ad esempio, data "excludePaths" : [ "/news/*", "/blog/*" ] nell'esempio precedente, l'app supporterà tutti i percorsi che iniziano con l'indirizzo del sito Web (ad esempio, msn.com), tranne 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 proprio sito Web, elenca i nomi di entrambe le famiglie 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*' (nessuno slash dopo 'news') include tutti i percorsi sotto 'news*' come 'newslocal/', 'newsinternational/' e così via.

Gestire i collegamenti durante l'attivazione per indirizzare al contenuto

Passare al file App.xaml.cs nella soluzione Visual Studio dell'app e in OnActivated() aggiungere la gestione del 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 di if (rootFrame.Content == null) finale con rootFrame.Navigate(deepLinkPageType, e); come illustrato nell'esempio precedente.

Eseguire il test in uno 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.exenome host packagefamilyname filepath

  • Hostname: sito Web (ad esempio, microsoft.com)
  • Nome famiglia di pacchetti (PFN): PFN dell'applicazione
  • 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 seguente chiave del Registro di sistema per forzare l'associazione del percorso per le app sideloaded come parte della convalida locale:

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

Keyname: ForceValidation Valore: 1

Testalo: validazione 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 link nella finestra. L'app deve essere avviata invece del Web browser.

È 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

Questi suggerimenti consentono di sfruttare al meglio la funzionalità AppUriHandlers:

  • Assicurarsi di specificare solo i collegamenti che l'app può gestire.
  • Elencare tutti gli host supportati. Si noti che www.example.com and 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 caricate lateralmente con AppUriHandlers avranno collegamenti convalidati per l'host al momento dell'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.

Contenuto correlato

progetto di esempio da Web ad App

registrazione windows.protocol

Gestire l'attivazione di URI