Deep-Link zu einer Anwendung

  • Artikel

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:

Hinweis

Dieses Thema enthält Version 2.0.x der Microsoft Teams JavaScript-Clientbibliothek (TeamsJS). Wenn Sie eine frühere Version verwenden, finden Sie in der Übersicht über die TeamsJS-Bibliothek Anleitungen zu den Unterschieden zwischen den neuesten Versionen von TeamsJS und früheren Versionen.

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:

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:

App-Typ Typ der App-ID
In Teams hochgeladene benutzerdefinierte App Manifest-ID
An den Organisationskatalog übermittelte Apps Organisationskatalog-ID
An den Teams Store übermittelte Apps Store-ID

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 */ }

Weitere Informationen zum appInstallDialog Modul finden Sie unter appInstallDialog-Modul.

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:

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:

Parametername Beschreibung Beispiel
appId  Die ID aus dem Microsoft Teams Admin Center. fe4a8eba-2a31-4737-8e33-e5fae6fee194
entityId  Die ID der Registerkarte, die Sie beim Konfigurieren der Registerkarte angegeben haben. Verwenden Sie beim Generieren einer URL für Deep Linking weiterhin die Entitäts-ID als Parameternamen in der URL. Beim Konfigurieren der Registerkarte verweist das Kontextobjekt auf den entityId als page.id. Aufgabenliste 123
entityWebUrl oder subEntityWebUrl  Ein optionales Feld mit einer Fallback-URL, das verwendet werden soll, wenn der Client das Rendern der Registerkarte nicht unterstützt. https://tasklist.example.com/123 oder https://tasklist.example.com/list123/task456
entityLabel oder subEntityLabel  Eine Bezeichnung für das Element auf Der Registerkarte, die beim Anzeigen des Deep-Links verwendet werden soll. Aufgabenliste 123 oder Aufgabe 456
context.subEntityId  Eine ID für das Element auf der Registerkarte. Verwenden Sie subEntityId beim Generieren einer URL für Deep Linking weiterhin als Parameternamen in der URL. Beim Konfigurieren der Registerkarte verweist das Kontextobjekt auf den subEntityId als page.subPageId. Aufgabe 456
context.channelId  Microsoft Teams-Kanal-ID, die auf der Registerkarte Kontextverfügbar ist. Diese Eigenschaft ist nur in konfigurierbaren Registerkarten mit einem Bereich von Team verfügbar. Sie ist nicht in statischen Registerkarten verfügbar, die über einen persönlichen Bereich verfügen. 19:cbe3683f25094106b826c9cada3afbe0@thread.skype
context.chatId  Chat-ID, die im Registerkartenkontext für Gruppen- und Besprechungschats verfügbar ist. 17:b42de192376346a7906a7dd5cb84b673@thread.v2
context.contextType  Chat wird nur für Besprechungen unterstützt contextType . Chat
&openInMeeting=false Verwenden Sie openInMeeting , um die Benutzererfahrung zu steuern, wenn die Zielregisterkarte einer Besprechung zugeordnet ist. Wenn der Benutzer mit dem Deep-Link in einer laufenden Besprechungsumgebung interagiert, öffnet Teams die App im Seitenbereich der Besprechung. Legen Sie diesen Wert auf festfalse, um die App immer auf der Registerkarte "Besprechungschat" und nicht im Seitenbereich zu öffnen, unabhängig vom status der Besprechung. Teams ignoriert alle anderen Werte als false. false

Hinweis

  • Persönliche Registerkarten haben einen personal Bereich, während Kanal- und Gruppenregisterkarten team oder group Bereiche nutzen. Die Syntax der beiden Registerkartentypen unterscheidet sich geringfügig, da nur dem Kontextobjekt der konfigurierbaren Registerkarte eine channel Eigenschaft zugeordnet ist. Weitere Informationen zu Registerkartenbereichen finden Sie im App-Manifest.
  • 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 die untergeordnete Entitäts-ID für die Registerkarte nicht angeben.

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"}

Wichtig

Stellen Sie sicher, dass alle Abfrageparameter und Leerzeichen ordnungsgemäß URI-codiert sind. Sie müssen den vorangehenden Beispielen anhand des letzten Beispiels folgen:

var encodedWebUrl = encodeURIComponent('https://tasklist.example.com/123/456&label=Task 456');
var encodedContext = encodeURIComponent(JSON.stringify({"subEntityId": "task456"}));
var taskItemUrl = 'https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=' + encodedWebUrl + '&context=' + encodedContext;

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:

Sie können die Navigation von Ihrer Registerkarte aus mithilfe der pages.navigateToApp()-Funktion auslösen, wie im folgenden Code dargestellt:

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 */ }

Weitere Informationen zur Navigation innerhalb einer Registerkarten-App finden Sie unter Navigieren innerhalb einer Registerkarten-App. Weitere Informationen zur Verwendung der pages-Funktion finden Sie unter pages.navigateToApp() und im pages-Namespace für andere Navigationsoptionen. Öffnen Sie bei Bedarf direkt einen Deep Link mit der App.openLink() -Funktion.

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.

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.

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.

Fügen Sie jedem Element eine Aktion zum Kopieren eines Links hinzu, ganz gleich, wie es für Ihre Benutzeroberfläche am besten geeignet ist. Wenn der Benutzer diese Aktion ausführt, rufen Sie auf pages.shareDeepLink() , um ein Dialogfeld anzuzeigen, das einen Link enthält, den der Benutzer in die Zwischenablage kopieren kann. Wenn Sie diesen Aufruf ausführen, übergeben Sie eine ID für Ihr Element. Sie erhalten sie wieder im Kontext, wenn dem Link gefolgt und Ihre Registerkarte neu geladen wird.

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

Sie müssen die folgenden Parameter durch die entsprechenden Informationen ersetzen:

  • subPageId: Ein eindeutiger Bezeichner für das Element auf Ihrer Seite, zu dem Sie eine Deep-Link-Verknüpfung erstellen.
  • subPageLabel: Eine Beschriftung für das Element, das zum Anzeigen des Deeplinks verwendet werden soll.
  • subPageWebUrl: Eine Fallback-URL, die verwendet werden soll, wenn der Client die Seite nicht rendern kann.

Weitere Informationen finden Sie unter pages.shareDeepLink().For more information, see pages.shareDeepLink().

Hinweis

  • Dieser Deep Link unterscheidet sich von den Links, die vom Menüelement Link auf Registerkarte kopieren bereitgestellt werden, das nur einen Deep-Link generiert, der auf diese Registerkarte verweist.
  • shareDeepLink funktioniert nicht auf mobilen Teams-Plattformen.

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

Hinweis

  • Wenn ein Bot eine TextBlock Nachricht mit einem Deep-Link sendet, wird eine neue Browserregisterkarte geöffnet, wenn Benutzer den Link auswählen. Dies erfolgt in der Chrome und Microsoft Teams Desktop-App, die unter Linux ausgeführt wird.
  • Wenn der Bot dieselbe Deep Link-URL in einem Action.OpenUrlsendet, wird die Registerkarte Teams im aktuellen Browser geöffnet, wenn der Benutzer den Link auswählt. Es wird keine neue Browserregisterkarte geöffnet.

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

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.

Tipp

Codieren Sie die Deep Link-URL, wenn Sie den card Parameter verwenden, z. B. die JavaScript-FunktionencodeURI().

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

Wert Typ Erforderlich Beschreibung
APP_ID string Ja Verwenden Sie für Drittanbieter-Apps die App id aus dem Manifest oder aus dem APP_ID Teams Admin Center, da sie identisch sind. Verwenden Sie für benutzerdefinierte Apps oder benutzerdefinierte Apps, die für Ihre Organisation (BRANCHEN-Apps) erstellt wurden, das aus dem APP_ID Teams Admin Center oder die Graph-API. Das validDomains-Array im Manifest für APP_ID muss die Domäne für url enthalten, wenn url in der Deep-Link-URL vorhanden ist. Die App-ID ist bereits bekannt, wenn ein Dialogfeld von einer Registerkarte oder einem Bot aufgerufen wird, weshalb es nicht in TaskInfoenthalten ist.
BOT_APP_ID string Nein Wenn ein Wert für completionBotId angegeben wird, wird das result Objekt mithilfe einer task/submit invoke Nachricht an den angegebenen Bot gesendet. Geben Sie BOT_APP_ID im Manifest der App als Bot an, den Sie nicht an einen Bot senden können.

Hinweis

APP_ID und BOT_APP_ID können in vielen Fällen identisch sein, wenn eine App über einen empfohlenen Bot verfügt, der als APP-ID verwendet werden soll, und wenn es einen gibt.

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.

Hinweis

  • Das Generieren eines Deep-Links zum Freigeben von Inhalten für besprechungsbezogene Besprechungen ist nur in der öffentlichen Entwicklervorschau verfügbar.
  • Deep-Link zum Freigeben von Inhalten für die Besprechung wird nur im Teams-Desktopclient unterstützt.

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.

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

Beispielname Beschreibung .NET Node.js
Deep Link, der die Subentity-ID verwendet In diesem Beispiel wird gezeigt, wie Sie einen Deep-Link aus einem Botchat zu einer Registerkarte verwenden, die die Subentity-ID verwendet. Außerdem werden Deep-Links für Folgendes angezeigt:
– Navigieren zu einer App
– Navigieren zu einem Chat
– Dialogfeld "Profil öffnen"
– Öffnen eines Planungsdialogfelds		 View Anzeigen