Deep-Link zu einer Anwendung

Deep-Links in Microsoft Teams sind leistungsstarke Tools, mit denen Benutzer direkt zu bestimmten Inhalten oder Aktionen innerhalb einer App navigieren können. Deep Links werden so konfiguriert, dass verschiedene Aktionen wie das Öffnen einer Registerkarte, das Initiieren eines App-Installationsdialogfelds oder das Durchsuchen innerhalb der App ausgeführt werden.

Deep Link-Szenarien

Im Folgenden finden Sie einige Szenarien, in denen Sie einen Deep Link verwenden können:

• App-Installation: Sie können Deep-Links verwenden, mit denen Benutzer mehr über eine App erfahren und sie in verschiedenen Bereichen installieren können.
• Bots und Connectors: Sie können Deep-Links in Bots und Connectors-Nachrichten verwenden, um Benutzer über Änderungen an Ihrer Registerkarte oder ihren Elementen zu informieren.
• Navigieren zu einer bestimmten Seite: Sie können Deep-Links erstellen, mit denen Benutzer zu bestimmten Seiten in Ihrer App navigieren können.
• Benutzerdefinierte App: Sie können Deep-Links für eine benutzerdefinierte App generieren. Wenn eine App im Microsoft Teams Store jedoch dieselbe App-ID wie die benutzerdefinierte App-ID verwendet, öffnet der Deep-Link die App aus dem Teams Store anstelle der benutzerdefinierten App.
• Für Mobilgeräte: Sie können auch einen Deep-Link zu einer App für Mobilgeräte erstellen, nachdem Ihre App für den mobilen Teams-Client genehmigt wurde. Damit der Deep-Link unter Teams iOS funktioniert, benötigen Sie die Apple App Store Connect Team-ID. Weitere Informationen finden Sie unter Aktualisieren der Team-ID von Apple App Store Connect.

Deep-Link zum Öffnen eines App-Installationsdialogfelds

Deep-Links ermöglichen es App-Benutzern, ein Dialogfeld für die App-Installation zu öffnen, um Informationen zur App zu erhalten oder sie in verschiedenen Kontexten zu installieren. Sie können einen Deep-Link zu einer App auf folgende Weise erstellen:

• Manuelles Konfigurieren von Deep Link mithilfe der App-ID
• Konfigurieren von Deep Link mithilfe von TeamsJS

Manuelles Konfigurieren von Deep Link mithilfe der App-ID

Mit Deep Link können Sie ein App-Installationsdialogfeld direkt über Ihren Teams-Client öffnen, indem Sie die App-ID verwenden.

App-ID für verschiedene Arten von Apps

In der folgenden Tabelle sind die verschiedenen Typen von App-IDs aufgeführt, die für verschiedene Typen von Apps für Deep-Links verwendet werden:

Weitere Informationen finden Sie unter Ermitteln der ID basierend auf der App-Manifest-ID.

Konfigurieren von Deep Link mithilfe von TeamsJS

Apps können die Microsoft Teams JavaScript-Clientbibliothek (TeamsJS) verwenden, um das App-Installationsdialogfeld zu initiieren, sodass keine manuelle Deep Link-Generierung erforderlich ist. Hier sehen Sie ein Beispiel für das Auslösen des App-Installationsdialogfelds mithilfe von TeamsJS in Ihrer App:

// Open an app install dialog from your tab
if(appInstallDialog.isSupported()) {
    const dialogPromise = appInstallDialog.openAppInstallDialog({ appId: "<appId>" });
    dialogPromise.
      then((result) => {/*Successful operation*/}).
      catch((error) => {/*Unsuccessful operation*/});
}
else { /* handle case where capability isn't supported */ }

// Open an app install dialog from your tab
microsoftTeams.executeDeepLink("https://teams.microsoft.com/l/app/<appId>");

Weitere Informationen finden Sie unter appInstallDialog.

Deep-Link zum Durchsuchen in Ihrer App

App-Benutzer können Inhalte in Teams über Ihre Registerkarte mithilfe von TeamsJS durchsuchen. Sie können einen Deep-Link verwenden, um in Ihrer App zu navigieren, wenn Ihre Registerkarte Benutzer mit anderen Inhalten in Teams verbinden muss, z. B. mit einem Kanal, einer Nachricht, einer anderen Registerkarte oder zum Öffnen eines Planungsdialogfelds. In einigen Fällen kann die Navigation auch mithilfe von TeamsJS erfolgen, und es wird empfohlen, die typisierten Funktionen von TeamsJS nach Möglichkeit zu verwenden.

Sie können DeepLinks für die Navigation in Ihrer App auf folgende Weise konfigurieren:

• Konfigurieren von Deep Link zum manuellen Durchsuchen in Ihrer App
• Konfigurieren eines Deep-Links zu einer Registerkarte mithilfe von TeamsJS
• Konfigurieren von Deep Link für die Navigation zwischen Registerkarten

Konfigurieren von Deep Link zum manuellen Durchsuchen in Ihrer App

Persönliche Registerkarten haben einen personal Bereich, während Kanal- und Gruppenregisterkarten team oder group Bereiche nutzen. Die syntax der beiden Registerkartentypen unterscheidet sich leicht, da nur der konfigurierbaren Registerkarte eine channel -Eigenschaft zugeordnet ist. Weitere Informationen zu Registerkartenbereichen finden Sie unter App-Manifest.

Abfrageparameter

Konfigurieren eines Deep-Links zu einer Registerkarte mithilfe von TeamsJS

Sie können Deep-Links in Ihrer App über TeamsJS konfigurieren, damit Benutzer verschiedene Seiten in Ihrer App durchsuchen können. Das Navigationsverhalten einer Teams-App, die über Microsoft 365 Office erweitert wird, hängt von zwei Faktoren ab:

1. Das Ziel, auf das der Deep-Link verweist.
2. Der Host, auf dem die Teams-App ausgeführt wird.

Wenn die Teams-App auf dem Host ausgeführt wird, auf den der Deep Link ausgerichtet ist, wird Ihre App direkt auf dem Host geöffnet. Wenn die Teams-App jedoch auf einem anderen Host als auf dem Deep Link ausgeführt wird, wird die App zuerst im Browser geöffnet.

Der folgende Code veranschaulicht, wie Sie in Ihrer Teams-App zu einer bestimmten Entität navigieren:

if (pages.isSupported()) {
  const navPromise = pages.navigateToApp({ appId: <appId>, pageId: <pageId>, webUrl: <webUrl>, subPageId: <subPageId>, channelId:<channelId>});
  navPromise.
     then((result) => {/*Successful navigation*/}).
     catch((error) => {/*Failed navigation*/});
}
else { /* handle case where capability isn't supported */ }

microsoftTeams.executeDeepLink(/*deepLink*/);

• Weitere Informationen finden Sie unter Navigieren innerhalb einer Registerkarten-App.
• Weitere Informationen zur Seitenfunktion finden Sie unter pages.navigateToApp() und im Pages-Namespace für andere Navigationsoptionen.
• Informationen zum direkten Öffnen eines Deep-Links mit app.openLink() finden Sie unter app.openLink() -Funktion.

Konfigurieren von Deep Link für die Navigation zwischen Registerkarten

Die Seitenfunktion der TeamsJS-Bibliothek bietet Unterstützung für die Navigation zwischen Registerkarten innerhalb einer App. Insbesondere bietet der pages.currentApp -Namespace eine Funktion navigateTo(NavigateWithinAppParams) , die die Navigation zu einer bestimmten Registerkarte innerhalb der aktuellen App ermöglicht, und eine Funktion navigateToDefaultPage() , um zur ersten Registerkarte zu navigieren, die im Manifest der App definiert ist. Der folgende Code veranschaulicht, wie Sie zu einer bestimmten Und Standardregisterkarte navigieren:

if (pages.currentApp.isSupported()) {
    const navPromise = pages.currentApp.navigateTo({pageId: <pageId>, subPageId: <subPageId>});
    navPromise.
        then((result) => {/*Successful navigation*/}).
        catch((error) => {/*Failed navigation*/});
}
else {/*Handle situation where capability isn't supported*/
    const navPromise = pages.navigateToApp({appId: <appId>, pageId: <pageId>});
    navPromise.
        then((result) => {/*Successful navigation*/}).
        catch((error) => {/*Failed navigation*/});
}

if (pages.currentApp.isSupported()) {
    const navPromise = pages.currentApp.navigateToDefaultPage();
    navPromise.
        then((result) => {/*Successful navigation*/}).
        catch((error) => {/*Failed navigation*/});
}
else {/*Handle situation where capability isn't supported*/}

Konfigurieren der Navigation auf der Schaltfläche "Zurück"

Wenn eine App über mehrere Registerkarten verfügt, kann ein Benutzer die Schaltfläche "Zurück" der Microsoft 365-Host-App verwenden, um den Navigationsverlauf rückwärts zu durchlaufen. Der Verlauf enthält jedoch nicht die Aktionen, die ein Benutzer auf einer Registerkarte ausführt. Wenn Sie die Schaltfläche "Zurück" verbessern möchten, können Sie Ihren eigenen internen Navigationsstapel verwalten und einen benutzerdefinierten Handler für die Auswahl der Zurück-Schaltfläche konfigurieren. Dies kann über die registerBackButtonHandler() -Funktion im pages.backStack -Namespace erreicht werden.

Nachdem Sie den Handler registriert haben, hilft es Ihnen, die Navigationsanforderung zu behandeln, bevor das System eine Aktion ausführt. Wenn der Handler in der Lage ist, die Anforderung zu verwalten, sollte er zurückgeben true , damit das System weiß, dass keine weitere Aktion erforderlich ist. Wenn der interne Stapel leer ist, sollte er zurückgegeben false werden, damit das System stattdessen die navigateBack() Funktion aufrufen und die entsprechende Aktion ausführen kann.

Zurückgeben des Fokus auf die Host-App

Nachdem der Benutzer mit der Verwendung von Elementen auf einer Registerkarte begonnen hat, bleibt der Fokus standardmäßig bei den Elementen Ihres iFrames, bis der Benutzer außerhalb des Elements auswählt. Wenn der iFrame teil des Benutzers ist, der mit Tastenkombinationen (TAB-TASTE oder F6-Taste) navigiert, können Sie sich auf die Host-App konzentrieren. Sie können sich mit der -Funktion auf die pages.returnFocus() Host-App konzentrieren. Die returnFocus() -Funktion akzeptiert einen Booleschen Wert, der die Richtung angibt, in der der Host-App falsetrue den Fokus vor und rückwärts verschoben werden soll. Im Allgemeinen hebt Vorwärts die Suchleiste hervor, und rückwärts hebt die App-Leiste hervor.

Deep-Link zu einem Chat mit der Anwendung

Sie können App-Benutzern erlauben, zu einem persönlichen Chat mit der Anwendung zu navigieren, indem Sie den Deep Link manuell konfigurieren.

Freigeben eines Deep-Links für eine Registerkarte

Sie können Deep-Links zu Entitäten in Teams-Apps freigeben, um zu den Inhalten und Informationen in Ihrer Registerkarten-App zu navigieren. Wenn Ihre Registerkarten-App beispielsweise eine Aufgabenliste enthält, können Teammitglieder Links zu einzelnen Aufgaben erstellen und freigeben. Wenn der App-Benutzer den Link auswählt, navigiert er zu Ihrer Registerkarte, die sich auf das jeweilige Element konzentriert.

pages.shareDeepLink({ subPageId: <subPageId>, subPageLabel: <subPageLabel>, subPageWebUrl: <subPageWebUrl> })

microsoftTeams.shareDeepLink({ subEntityId: <subEntityId>, subEntityLabel: <subEntityLabel>, subEntityWebUrl: <subEntityWebUrl> })

Deep-Link für SharePoint-Framework Registerkarten

Deeplinks für SharePoint-Framework (SPFx)-Registerkarten ermöglichen Es Benutzern, direkt zu bestimmten Registerkarten innerhalb einer SharePoint-Website oder Teams-App zu navigieren. Dadurch wird die Benutzerfreundlichkeit verbessert, indem schneller Zugriff auf relevante Inhalte und Funktionen bereitgestellt wird.

Abfrageparameter

Deep-Link zum Öffnen eines Dialogfelds

Ein Deep Link für Dialoge ist eine Serialisierung des TaskInfo -Objekts mit zwei weiteren Details, und APP_ID optional .BOT_APP_ID

Die Datentypen und zulässigen Werte für <TaskInfo.url>, , <TaskInfo.card><TaskInfo.height>, <TaskInfo.width>und <TaskInfo.title>finden Sie unter TaskInfo-Objekt.

Die folgende Tabelle enthält Informationen zu APP_ID und BOT_APP_ID:

Deep-Link zum Freigeben von Inhalten in der Besprechungsphase

Sie können auch einen Deep-Link generieren, um die App zu teilen, um eine Besprechung zu starten oder zu starten.

Deep-Links zum Freigeben von Inhalten für die Staging finden Sie unter Deep-Link zum Freigeben von Inhalten für die Bühne in Besprechungen.

Deep-Link zum Besprechungsseitenbereich

Sie können einen Deep-Link zum Besprechungsseitenbereich in einer Besprechung generieren.

Standardmäßig wird ein Deep-Link in einem Besprechungsseitenbereich geöffnet. Um einen Deep-Link direkt in einer App anstelle des Besprechungsseitenbereichs zu öffnen, fügen Sie wie openInMeeting=false im folgenden Deep-Link-Format gezeigt hinzu:

https://teams.microsoft.com/l/entity/<appId>/<entityId>?webUrl=<entityWebUrl>&label=<entityLabel>&context=<context>&openInMeeting=false

Weitere Informationen finden Sie unter Deep-Link zu einer Registerkarte.

In den folgenden Szenarien wird kein Deep-Link im Besprechungsseitenbereich geöffnet:

• Es gibt keine aktive Besprechung.
• Für die App ist im App-Manifest kein sidePanel Kontext deklariert.
• openInMeeting wird im Deep-Link auf false festgelegt.
• Der Deep-Link wird außerhalb des Besprechungsfensters oder der Komponente ausgewählt.
• Der Deep-Link stimmt nicht mit der aktuellen Besprechung überein, z. B. wenn der Deep Link aus einer anderen Besprechung erstellt wird.

Deep-Link zum Aufrufen von Stageview

Sie können Stageview über einen Deep-Link von Ihrer Registerkarte aufrufen, indem Sie die Deep Link-URL in der app.openLink(url) API umschließen. Der Deep-Link kann auch durch eine OpenURL-Aktion auf der Karte übergeben werden. Die openMode in der API definierte Eigenschaft bestimmt die Stageview-Antwort. Weitere Informationen finden Sie unter Aufrufen von Stageview über deep link.

Bewährte Methoden

• DeepLinks funktionieren nur ordnungsgemäß, wenn die Registerkarte mit der Bibliothek v0.4 oder höher konfiguriert wurde, da sie über eine Entitäts-ID verfügt. Deep-Links zu Registerkarten ohne Entitäts-IDs wechseln weiterhin zur Registerkarte, können aber nicht den Sub'EntityId für die Registerkarte angeben.
• In Microsoft Windows kann Teams aufgrund des Grenzwerts in der Windows ShellExecuteEx-API keine Deep-Links verarbeiten, die INTERNET_MAX_URL_LENGTH 2048 Zeichen überschreiten.
• Stellen Sie beim Erstellen eines Deep-Links sicher, dass der Pfad zum Teams-Client und andere Metadaten innerhalb dieses Grenzwerts passen.
• Wenn Ihr Deep Link große Daten enthält, fügen Sie einen eindeutigen Bezeichner in den Link ein, den Ihre App zum Abrufen der erforderlichen Daten aus Ihrem Back-End-Dienst verwenden kann.

Codebeispiel