Aktivieren von Apps für Websites mit App-URI-Handlern

Artikel
07/04/2024

Apps für Websites verknüpfen Ihre App mit einer Website, sodass Ihre App gestartet wird, wenn jemand einen Link zu Ihrer Website öffnet, anstatt den Browser zu öffnen. Wenn Ihre App nicht installiert ist, wird Ihre Website wie gewohnt im Browser geöffnet. Benutzer können dieser Erfahrung vertrauen, da nur überprüfte Inhaltsbesitzer sich für einen Link registrieren können. Benutzer können alle ihre registrierten Web-to-App-Links überprüfen, indem Sie zu "Apps-Apps > für Websites einstellungen" > wechseln.

Um die Web-zu-App-Verknüpfung zu aktivieren, müssen Sie Folgendes ausführen:

Identifizieren sie die URIs, die Ihre App in der Manifestdatei behandelt.
Eine JSON-Datei, die die Zuordnung zwischen Ihrer App und Ihrer Website definiert. mit dem App-Paketfamiliennamen im selben Hoststamm wie die App-Manifestdeklaration.
Behandeln Sie die Aktivierung in der App.

Hinweis

Ab dem Windows 10 Creators-Update starten unterstützte Links, die in Vorgängerversion von Microsoft Edge geklickt wurden, die entsprechende App. Unterstützte Links, die in anderen Browsern geklickt werden (z. B. Microsoft Edge Chromium, Internet Explorer usw.), behalten Sie in der Browserumgebung bei.

Registrieren, um HTTP- und HTTPS-Links im App-Manifest zu behandeln

Ihre App muss die URIs für die Websites identifizieren, die sie verarbeiten wird. Fügen Sie dazu die Windows.appUriHandler-Erweiterungsregistrierung zur Manifestdatei "Package.appxmanifest" Ihrer App hinzu.

Wenn die Adresse Ihrer Website beispielsweise "msn.com" lautet, würden Sie den folgenden Eintrag im App-Manifest eingeben:

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

Die obige Deklaration registriert Ihre App, um Links vom angegebenen Host zu behandeln. Wenn Ihre Website über mehrere Adressen verfügt (z. B. m.example.com, www.example.com und example.com), fügen Sie für jede Adresse einen separaten <uap3:Host Name=... /> Eintrag hinzu <uap3:AppUriHandler> .

Zuordnen Ihrer App und Website zu einer JSON-Datei

Um sicherzustellen, dass nur Ihre App Inhalte auf Ihrer Website öffnen kann, schließen Sie den Paketfamiliennamen Ihrer App in eine JSON-Datei ein, die sich im Stammverzeichnis des Webservers oder im bekannten Verzeichnis der Domäne befindet. Dies bedeutet, dass Ihre Website die Zustimmung für die aufgeführten Apps erteilt, um Inhalte auf Ihrer Website zu öffnen. Sie finden den Paketfamiliennamen im Abschnitt "Pakete" im App-Manifest-Designer.

Wichtig

Die JSON-Datei sollte kein .json Dateisuffix aufweisen.

Erstellen Sie eine JSON-Datei (ohne die dateierweiterung .json) mit dem Namen "windows-app-web-link ", und geben Sie den Paketfamiliennamen Ihrer App an. Zum Beispiel:

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

Windows stellt eine HTTPS-Verbindung zu Ihrer Website und sucht auf Ihrem Webserver nach der entsprechenden JSON-Datei.

Platzhalter

Im obigen JSON-Dateibeispiel wird die Verwendung von Wildcards veranschaulicht. Mit Wildcards können Sie eine Vielzahl von Links mit weniger Codezeilen unterstützen. Web-zu-App-Verknüpfungen unterstützen zwei Arten von Wildcards in der JSON-Datei:

Platzhalter	Beschreibung
*	Stellt eine beliebige Teilzeichenfolge dar.
?	Stellt ein einzelnes Zeichen dar.

Die App unterstützt beispielsweise alle Pfade, "excludePaths" : [ "/news/*", "/blog/*" ] die mit der Adresse Ihrer Website beginnen (z. B. msn.com), mit Ausnahme derjenigen unter /news/ und /blog/. msn.com/weather.html wird unterstützt, aber nicht msn.com/news/topnews.html.

Mehrere Apps

Wenn Sie über zwei Apps verfügen, die Sie mit Ihrer Website verknüpfen möchten, führen Sie beide Anwendungspaketfamiliennamen in ihrer JSON-Datei "windows-app-web-link " auf. Beide Apps können unterstützt werden. Dem Benutzer wird eine Auswahl angezeigt, bei der es sich um den Standardlink handelt, wenn beide installiert sind. Wenn sie den Standardlink später ändern möchten, können sie ihn in "Einstellungen > "-Apps für Websites ändern. Entwickler können die JSON-Datei auch jederzeit ändern und die Änderung so früh wie am selben Tag, aber nicht später als acht Tage nach dem Update anzeigen.

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

Verwenden Sie Ausgeschlossene Pfade, um sicherzustellen, dass nur Onlineinhalte von den unterstützten Pfaden in Ihrer JSON-Datei ausgeschlossen werden, um die optimale Benutzererfahrung für Ihre Benutzer bereitzustellen.

Ausschlusspfade werden zuerst überprüft, und wenn eine Übereinstimmung mit der entsprechenden Seite vorhanden ist, wird anstelle der vorgesehenen App mit dem Browser geöffnet. Im obigen Beispiel enthält "/news/*" alle Seiten unter diesem Pfad, während "/news*" (keine Schrägstriche "news") alle Pfade unter "news*" wie "newslocal/", "newsinternational/" usw. enthalten sind.

Behandeln von Links zur Aktivierung zum Verknüpfen mit Inhalten

Navigieren Sie zur App.xaml.cs in der Visual Studio-Projektmappe Ihrer App, und fügen Sie in OnActivated() die Behandlung für verknüpfte Inhalte hinzu. Im folgenden Beispiel hängt die in der App geöffnete Seite vom URI-Pfad ab:

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();
}

Wichtig Stellen Sie sicher, dass Sie die endgültige if (rootFrame.Content == null) Logik wie rootFrame.Navigate(deepLinkPageType, e); im obigen Beispiel dargestellt ersetzen.

Testen Sie es: Lokales Überprüfungstool

Sie können die Konfiguration Ihrer App und Website testen, indem Sie das App-Hostregistrierungsprüftool ausführen, das in:

%windir%\system32\AppHostRegistrationVerifier.exe

Testen Sie die Konfiguration Ihrer App und Website, indem Sie dieses Tool mit den folgenden Parametern ausführen:

AppHostRegistrationVerifier.exe Hostname packagefamilyname filepath

Hostname: Ihre Website (z. B. microsoft.com)
Paketfamilienname (PFN): PfN Ihrer App
Dateipfad: Die JSON-Datei für die lokale Überprüfung (z. B. C:\SomeFolder\windows-app-web-link)

Wenn das Tool nichts zurückgibt, funktioniert die Überprüfung beim Hochladen an dieser Datei. Wenn ein Fehlercode vorhanden ist, funktioniert er nicht.

Sie können den folgenden Registrierungsschlüssel aktivieren, um den Pfadabgleich für quergeladene Apps als Teil der lokalen Überprüfung zu erzwingen:

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

Keyname: Wert: ForceValidation1

Testen: Webüberprüfung

Schließen Sie Ihre Anwendung, um zu überprüfen, ob die App aktiviert ist, wenn Sie auf einen Link klicken. Kopieren Sie dann die Adresse eines der unterstützten Pfade auf Ihrer Website. Wenn beispielsweise die Adresse Ihrer Website "msn.com" lautet und einer der Supportpfade "Path1" lautet, verwenden Sie http://msn.com/path1

Stellen Sie sicher, dass Ihre App geschlossen ist. Drücken Sie WINDOWS-TASTE+R , um das Dialogfeld "Ausführen " zu öffnen und den Link in das Fenster einzufügen. Ihre App sollte anstelle des Webbrowsers gestartet werden.

Darüber hinaus können Sie Ihre App testen, indem Sie sie über die LaunchUriAsync-API aus einer anderen App starten. Sie können diese API auch zum Testen auf Smartphones verwenden.

Wenn Sie der Protokollaktivierungslogik folgen möchten, legen Sie einen Haltepunkt im OnActivated-Ereignishandler fest.

Tipps zu AppUriHandlers:

Stellen Sie sicher, dass Sie nur Links angeben, die Ihre App verarbeiten kann.
Auflisten aller Hosts, die Sie unterstützen. Beachten Sie, dass www.example.com und example.com unterschiedliche Hosts sind.
Benutzer können auswählen, welche App sie in den Einstellungen für die Verarbeitung von Websites bevorzugen.
Ihre JSON-Datei muss auf einen HTTPS-Server hochgeladen werden.
Wenn Sie die pfade ändern müssen, die Sie unterstützen möchten, können Sie Ihre JSON-Datei erneut veröffentlichen, ohne Ihre App erneut zu veröffentlichen. Benutzer sehen die Änderungen in 1-8 Tagen.
Alle quergeladenen Apps mit AppUriHandlers verfügen über überprüfte Links für den Host bei der Installation. Sie müssen keine JSON-Datei hochladen, um das Feature zu testen.
Dieses Feature funktioniert, wenn Es sich bei Ihrer App um eine UWP-App handelt, die mit LaunchUriAsync oder einer Windows-Desktop-App gestartet wurde, die mit ShellExecuteEx gestartet wurde. Wenn die URL einem registrierten App-URI-Handler entspricht, wird die App anstelle des Browsers gestartet.

Weitere Informationen

Das Beispiel für web-to-App-Beispielprojekt "windows.protocol registration Handle URI ActivationAssociation Launch" veranschaulicht die Verwendung der LaunchUriAsync()-API.

Freigeben über