Deep-Link zu einer Anwendung

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. Verwenden Sie Deep-Links in Bot- und Connectornachrichten, um Benutzer über Änderungen an Ihrer Registerkarte oder ihren Elementen zu informieren.

Sie können deep links für eine benutzerdefinierte App erstellen. 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. Sie können auch einen Deep-Link zur App für Mobilgeräte erstellen, nachdem Ihre App für die mobile Teams-Plattform 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-Links ermöglichen es Benutzern, mehr über eine App zu erfahren und sie in verschiedenen Bereichen zu installieren. Sie können auch Deep-Links für Ihre App-Benutzer erstellen, um zu bestimmten Seiten in Ihrer App zu wechseln. In diesem Artikel erfahren Sie, wie Sie einen Deep Link erstellen:

• So öffnen Sie das Anwendungsinstallationsdialogfeld
• So navigieren Sie in Ihrer App
• So wechseln Sie zu einem Chat mit der Anwendung
• So geben Sie deep link für eine Registerkarte
• So öffnen Sie ein Dialogfeld (in TeamsJS v1.x als Aufgabenmodul bezeichnet)
• So rufen Sie Stageview auf

Deep Link zum Öffnen des Anwendungsinstallationsdialogfelds

Deep-Links ermöglichen es App-Benutzern, ein Anwendungsinstallationsdialogfeld zu öffnen, um weitere Informationen zur App zu erhalten oder sie in verschiedenen Kontexten zu installieren. Sie können einen Deep-Link zur Anwendung auf folgende Weise erstellen:

• Manuelles Konfigurieren von Deep Link mithilfe Ihrer App-ID
• Konfigurieren eines Deep-Links zu einer Registerkarte mithilfe von TeamsJS

Manuelles Konfigurieren von Deep Link mithilfe Ihrer App-ID

Dies ist das Deep Link-Format, das Sie benötigen, um ein App-Installationsdialogfeld über Ihren Teams-Client mithilfe der App-ID zu öffnen:

https://teams.microsoft.com/l/app/<your-app-id>?tenantId=<tenantId>

Dabei <your-app-id> ist Ihre Anwendungs-ID (f46ad259-0fe5-4f12-872d-c737b174bcb4).

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.

Anwendungen können die TeamsJS-Bibliothek verwenden, um das Dialogfeld für die App-Installation 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 Anwendung:

// 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>");

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, nach Möglichkeit typisierte Funktionen von TeamsJS zu verwenden.

TeamsJS ermöglicht Teams-Apps, die über Outlook und Microsoft 365 erweitert wurden, um zu überprüfen, ob der Host die Funktion unterstützt, die Sie verwenden möchten. Um die Unterstützung einer Funktion durch einen Host zu überprüfen, können Sie die isSupported()-Funktion verwenden, die dem Namespace der API zugeordnet ist. TeamsJS organisiert APIs in Funktionen über Namespaces. Bevor Sie beispielsweise eine API im pages Namespace verwenden, können Sie den zurückgegebenen booleschen Wert von pages.isSupported() überprüfen und die entsprechende Aktion im Kontext Ihrer App und der Benutzeroberfläche Ihrer App ausführen.

Weitere Informationen zu Funktionen und APIs in TeamsJS finden Sie unter Erstellen von Registerkarten und anderen gehosteten Umgebungen mit der TeamsJS-Bibliothek.

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

Verwenden Sie das folgende Format für einen Deep Link in einem Bot, Connector oder einer Nachrichtenerweiterung Karte:

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

• Wenn der Bot eine Nachricht TextBlock mit einem Deeplink sendet, wird eine neue Browserregisterkarte geöffnet, wenn der Benutzer den Link auswählt. Dies geschieht in Chrome und in der Teams-Desktop-App, wenn sie unter Linux ausgeführt werden.

• Wenn der Bot dieselbe Deep Link-URL an ein Action.OpenUrlsendet, wird die Registerkarte Teams auf der aktuellen Browserregisterkarte geöffnet, wenn der Benutzer den Link auswählt.

Die Abfrageparameter sind:

Beispiele:

• Link zu einer eigentlichen statischen (persönlichen) Registerkarte:

  https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123&label=Task List 123

• Link zu einem Aufgabenelement auf der statischen (persönlichen) Registerkarte:

  https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123/456&label=Task 456&context={"subEntityId": "task456"}

• Link zu der jeweiligen konfigurierbaren Registerkarte:

  https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123&label=Task List 123&context={"channelId": "19:cbe3683f25094106b826c9cada3afbe0@thread.skype"}

• Link zu einem Aufgabenelement auf der konfigurierbaren Registerkarte:

  https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123/456&label=Task 456&context={"subEntityId": "task456","channelId": "19:cbe3683f25094106b826c9cada3afbe0@thread.skype"}

• Link zu einer Registerkarten-App, die einem Besprechungs- oder Gruppenchat hinzugefügt wurde:

  https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123/456&label=Task 456?context={"chatId": "17:b42de192376346a7906a7dd5cb84b673@thread.v2","contextType":"chat"}

Konfigurieren eines Deep-Links zu einer Registerkarte mithilfe von TeamsJS

Sie können Deep-Links in Ihrer App über TeamsJS konfigurieren, damit die App-Benutzer verschiedene Seiten in Ihrer App durchsuchen können. 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*/);

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.

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 im folgenden Format konfigurieren:

https://teams.microsoft.com/l/entity/<appId>/conversations?tenantId=<tenantId>, wobei appId Ihre Anwendungs-ID ist. Informationen zu verschiedenen verwendeten App-IDs finden Sie unter App-ID für verschiedene Arten von Apps.

Deep-Link für eine Registerkarte freigeben

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

Sie können das folgende Deep Link-Format in einem Bot, Connector oder einer Nachrichtenerweiterung Karte verwenden: https://teams.microsoft.com/l/entity/<appId>/<EntityId>?webUrl=<entityWebUrl>/<EntityName>.

Die Abfrageparameter sind:

• appID: Ihre Manifest-ID, z. B. fe4a8eba-2a31-4737-8e33-e5fae6fee194.

• entityID: Die Element-ID, die Sie beim Konfigurieren der Registerkarteangegeben haben. Zum Beispiel: tasklist123.

• entityWebUrl: Ein optionaler Parameter mit einer Fallback-URL, die verwendet werden soll, wenn der Client das Rendern der Registerkarte https://tasklist.example.com/123https://tasklist.example.com/list123/task456oder nicht unterstützt.

• entityName: Eine Bezeichnung für das Element auf der Registerkarte, die beim Anzeigen des Deep-Links verwendet werden soll, z Task List 123 . B. oder Task 456.

Beispiel: https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123&TaskList

Deep-Link zum Öffnen eines Dialogfelds

Ein Dialog deep link ist eine Serialisierung des TaskInfo Objekts mit zwei weiteren Details: APP_ID und optional BOT_APP_ID:

• https://teams.microsoft.com/l/task/APP_ID?url=<TaskInfo.url>&height=<TaskInfo.height>&width=<TaskInfo.width>&title=<TaskInfo.title>&completionBotId=BOT_APP_ID

• https://teams.microsoft.com/l/task/APP_ID?card=<TaskInfo.card>&height=<TaskInfo.height>&width=<TaskInfo.width>&title=<TaskInfo.title>&completionBotId=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:

Generieren eines Deep-Links zum Freigeben von Inhalten, die in Besprechungen bereitgestellt werden sollen

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. Verwenden Sie das folgende Format für einen Deep-Link zum Seitenbereich der Besprechung:

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

Beispiel:

https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123/456&label=Task 456&context={"chatId": "17:b42de192376346a7906a7dd5cb84b673@thread.v2","contextType":"chat"}

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 im Deep Link-Format hinzu openInMeeting=false :

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 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.

Codebeispiel