Partager via

Lien profond vers une application

  • Article

Les liens profonds dans Microsoft Teams sont des outils puissants qui permettent aux utilisateurs de naviguer directement vers du contenu ou des actions spécifiques au sein d’une application. Les liens profonds sont configurés pour effectuer diverses actions, telles que l’ouverture d’un onglet, le lancement d’une boîte de dialogue d’installation d’application ou la navigation dans l’application.

Remarque

Cette rubrique reflète la version 2.0.x de la bibliothèque de client JavaScript Microsoft Teams (TeamsJS). Si vous utilisez une version antérieure, reportez-vous à la vue d’ensemble de la bibliothèque TeamsJS pour obtenir des conseils sur les différences entre la dernière version de TeamsJS et les versions antérieures.

Voici quelques-uns des scénarios dans lesquels vous pouvez utiliser un lien profond :

  • Installation de l’application : vous pouvez utiliser des liens profonds qui permettent aux utilisateurs d’en savoir plus sur une application et de l’installer dans différentes étendues.
  • Bots et connecteurs : vous pouvez utiliser des liens profonds dans les messages des bots et des connecteurs pour informer les utilisateurs des modifications apportées à votre onglet ou à ses éléments.
  • Accéder à une page spécifique : vous pouvez créer des liens profonds qui permettent aux utilisateurs d’accéder à des pages spécifiques au sein de votre application.
  • Application personnalisée : vous pouvez générer des liens profonds pour une application personnalisée. Toutefois, si une application dans le Microsoft Teams Store partage le même ID d’application que l’ID d’application personnalisée, le lien profond ouvre l’application à partir du Magasin Teams au lieu de l’application personnalisée.
  • Pour les appareils mobiles : vous pouvez également créer un lien profond vers une application pour mobile une fois votre application approuvée pour le client mobile Teams. Pour que le lien profond fonctionne sur Teams iOS, vous avez besoin de l’ID d’équipe Apple App Store Connect. Pour plus d’informations, consultez comment mettre à jour l’ID d’équipe Apple App Store Connect.

Les liens profonds permettent aux utilisateurs de l’application d’ouvrir une boîte de dialogue d’installation d’application pour connaître des informations sur l’application ou l’installer dans différents contextes. Vous pouvez créer un lien profond vers une application des manières suivantes :

Avec un lien profond, vous pouvez ouvrir une boîte de dialogue d’installation d’application directement à partir de votre client Teams à l’aide de l’ID d’application.

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

<your-app-id> est votre ID d’application (fxxxxxxx-0xxx-4xxx-8xxx-cxxxxxxxxxxxxxxx).

ID d’application pour différents types d’applications

Le tableau suivant répertorie les différents types d’ID d’application utilisés pour différents types d’applications pour les liens profonds :

Type d’application Type d’ID d’application
Application personnalisée chargée dans Teams ID de manifeste
Applications soumises au catalogue d’organisations ID de catalogue d’organisation
Applications soumises au Magasin Teams ID du magasin

Pour plus d’informations, consultez Comment rechercher l’ID basé sur l’ID du manifeste de l’application.

Les applications peuvent utiliser la bibliothèque de client JavaScript Microsoft Teams (TeamsJS) pour lancer la boîte de dialogue d’installation de l’application, ce qui élimine la nécessité de générer manuellement des liens profonds. Voici un exemple montrant comment déclencher la boîte de dialogue d’installation de l’application à l’aide de TeamsJS dans votre application :

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

Pour plus d’informations, reportez-vous à l’article appInstallDialog.

Les utilisateurs de l’application peuvent parcourir le contenu dans Teams à partir de votre onglet à l’aide de TeamsJS. Vous pouvez utiliser un lien profond pour parcourir votre application si votre onglet doit connecter les utilisateurs à d’autres contenus dans Teams, tels qu’un canal, un message, un autre onglet, ou pour ouvrir une boîte de dialogue de planification. Dans certains cas, la navigation peut également être effectuée à l’aide de TeamsJS, et nous vous recommandons d’utiliser les fonctionnalités typées de TeamsJS dans la mesure du possible.

Vous pouvez configurer des liens profonds pour parcourir votre application des manières suivantes :

Les onglets personnels ont un personalscope, tandis que les onglets canal et groupe utilisent teamor groupscopes. Les deux types d’onglets ont une syntaxe légèrement différente, car seul l’onglet configurable a une channel propriété associée à son objet de contexte. Pour plus d’informations sur les étendues d’onglets, consultez manifeste de l’application.

Pour créer un lien profond dans un bot, un connecteur ou une extension de message carte, utilisez le format suivant :

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

  • Si le bot envoie un message contenant un TextBlock avec un lien profond, un nouvel onglet de navigateur est ouvert lorsque l’utilisateur sélectionne le lien. Cela se produit dans Chrome et dans l’application de bureau Teams lorsqu’ils s’exécutent sur Linux.

  • Si le bot envoie la même URL de lien profond dans un Action.OpenUrl, l’onglet Teams s’ouvre dans l’onglet actuel du navigateur lorsque l’utilisateur sélectionne le lien.

Paramètres de requête

Nom du paramètre Description
appId  ID du Centre d’administration Microsoft Teams.

Exemple : fe4a8eba-2a31-4737-8e33-e5fae6fee194
entityId  ID de l’onglet que vous avez fourni lors de la configuration de l’onglet. Lors de la génération d’une URL pour la liaison approfondie, continuez à utiliser l’ID d’entité comme nom de paramètre dans l’URL. Lors de la configuration de l’onglet, l’objet de contexte fait référence à .entityIdpage.id

Exemple : Liste de tâches 123
entityWebUrl ou subEntityWebUrl  Champ facultatif avec une URL de secours à utiliser si le client ne prend pas en charge le rendu de l’onglet.

Exemple : https://tasklist.example.com/123
ou
https://tasklist.example.com/list123/task456
entityLabel ou subEntityLabel  Étiquette pour l’élément de votre onglet à utiliser lors de l’affichage du lien profond.

Exemple : Liste des tâches 123 ou Tâche 456
context.subEntityId  ID de l’élément dans l’onglet. Lors de la génération d’une URL pour la liaison approfondie, continuez à utiliser subEntityId comme nom de paramètre dans l’URL. Lors de la configuration de l’onglet, l’objet de contexte fait référence à .subEntityIdpage.subPageId

Exemple : Tâche 456
context.channelId  ID de canal Microsoft Teams disponible à partir de l’onglet contexte. Cette propriété est disponible uniquement dans les onglets configurables avec une étendue d’équipe. Il n’est pas disponible dans les onglets statiques, qui ont une étendue personnelle .

Exemple : 19 :cbe3683f25094106b826c9cada3afbe0@thread.skype
context.chatId  ID de conversation disponible à partir du contexte d’onglet pour la conversation de groupe et de réunion.

Exemple : 17 :b42de192376346a7906a7dd5cb84b673@thread.v2
context.contextType  La conversation est la seule prise en charge contextType pour les réunions.

Exemple : conversation
openInMeeting Permet openInMeeting de contrôler l’expérience utilisateur lorsque l’onglet cible est associé à une réunion. Si l’utilisateur interagit avec le lien profond dans une expérience de réunion en cours, Teams ouvre l’application dans le panneau latéral de la réunion. Définissez cette valeur false sur pour toujours ouvrir l’application dans l’onglet de conversation de réunion plutôt que dans le panneau latéral, quelle que soit la status de la réunion. Teams ignore toute valeur autre que false.

Exemple : false

Importante

  • Vérifiez que tous les paramètres de requête et les espaces blancs sont correctement encodés dans l’URI. Voici un exemple de paramètres de requête encodés par URI :

    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;

  • Le lien profond vers une application Teams avec un URI encodé n’est pas pris en charge dans Outlook.

Vous pouvez configurer des liens profonds dans votre application via TeamsJS pour permettre aux utilisateurs de parcourir différentes pages au sein de votre application. Le comportement de navigation d’une application Teams étendue dans Microsoft 365 Office dépend de deux facteurs :

  1. Cible vers laquelle pointe le lien profond.
  2. Hôte sur lequel l’application Teams s’exécute.

Si l’application Teams s’exécute dans l’hôte où le lien profond est ciblé, votre application s’ouvre directement dans l’hôte. Toutefois, si l’application Teams s’exécute dans un hôte différent de celui où le lien profond est ciblé, l’application s’ouvre d’abord dans le navigateur.


Prise en charge des liens profonds dans TeamsJS

TeamsJS permet aux applications Teams étendues dans Outlook et Microsoft 365 de case activée si l’hôte prend en charge la fonctionnalité que vous essayez d’utiliser. Pour vérifier la prise en charge d’une fonctionnalité par un hôte, vous pouvez utiliser la isSupported() fonction associée à l’espace de noms de l’API. TeamsJS organise les API en fonctionnalités à l’aide d’espaces de noms. Par exemple, avant d’utiliser une API dans l’espace pages de noms, vous pouvez case activée la valeur booléenne retournée à partir de pages.isSupported() et effectuer l’action appropriée dans le contexte de votre application et de l’interface utilisateur de votre application. Pour plus d’informations, consultez Création d’onglets et d’autres expériences hébergées avec la bibliothèque TeamsJS.

Le code suivant montre comment accéder à une entité spécifique dans votre application Teams :

Vous pouvez déclencher une navigation à partir de votre onglet à l’aide de la fonction pages.navigateToApp(), comme indiqué dans le code suivant :

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

La fonctionnalité pages de la bibliothèque TeamsJS prend en charge la navigation entre les onglets au sein d’une application. Plus précisément, l’espace pages.currentApp de noms offre une fonction navigateTo(NavigateWithinAppParams) pour permettre la navigation vers un onglet spécifique dans l’application actuelle et une fonction navigateToDefaultPage() pour accéder au premier onglet défini dans le manifeste de l’application. Le code suivant montre comment accéder à un onglet spécifique et par défaut :

Le code suivant montre comment accéder à un onglet spécifique :

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

Remarque

La navigation de l’application par onglet est prise en charge uniquement dans le nouveau client Teams.

Configurer la navigation sur le bouton Précédent

Lorsqu’une application a plusieurs onglets, un utilisateur peut utiliser le bouton Précédent de l’application hôte Microsoft 365 pour revenir en arrière dans l’historique de navigation. Toutefois, l’historique n’inclut pas les actions qu’un utilisateur effectue dans un onglet. Si vous souhaitez améliorer l’expérience du bouton Précédent, vous pouvez gérer votre propre pile de navigation interne et configurer un gestionnaire personnalisé pour les sélections de boutons Précédent. Cela peut être effectué via la registerBackButtonHandler() fonction dans l’espace de pages.backStack noms .

Une fois que vous avez inscrit le gestionnaire, il vous aide à traiter la demande de navigation avant que le système ne prenne des mesures. Si le gestionnaire est en mesure de gérer la demande, elle doit être retournée true afin que le système sache qu’aucune autre action n’est nécessaire. Si la pile interne est vide, elle doit être retournée false afin que le système puisse appeler la fonction à la navigateBack() place et prendre l’action appropriée.

Rétablir le focus sur l’application hôte

Une fois que l’utilisateur a commencé à utiliser des éléments dans un onglet, par défaut, le focus reste sur les éléments de votre iFrame jusqu’à ce que l’utilisateur sélectionne en dehors de celui-ci. Si l’iFrame fait partie de l’utilisateur qui navigue avec des raccourcis clavier (touche Tab ou touche F6), vous pouvez vous concentrer sur l’application hôte. Vous pouvez vous concentrer sur l’application hôte à l’aide de la pages.returnFocus() fonction . La returnFocus() fonction accepte une valeur booléenne indiquant la direction à suivre pour avancer le focus dans l’application hôte ; true pour l’avant et false pour l’arrière. En règle générale, la barre de recherche est mise en surbrillance vers l’avant et la barre de l’application vers l’arrière.

Vous pouvez autoriser les utilisateurs de l’application à accéder à une conversation personnelle avec l’application en configurant manuellement le lien profond.

https://teams.microsoft.com/l/entity/<appId>/conversations?tenantId=<tenantId>

appId est votre ID d’application. Pour plus d’informations, consultez ID d’application pour différents types d’applications.

Vous pouvez partager des liens profonds vers des entités dans les applications Teams pour accéder au contenu et aux informations dans votre application d’onglet. Par exemple, si votre application onglet contient une liste de tâches, les membres de l’équipe peuvent créer et partager des liens vers des tâches individuelles. Lorsque l’utilisateur de l’application sélectionne le lien, il accède à votre onglet qui se concentre sur l’élément spécifique.

Ajoutez une action de lien de copie à chaque élément de la manière qui convient le mieux à votre interface utilisateur. Lorsque l’utilisateur effectue cette action, appelez pages.shareDeepLink() pour afficher une boîte de dialogue contenant un lien que l’utilisateur peut copier dans le Presse-papiers. Lorsque vous effectuez cet appel, transmettez un ID pour votre élément. Vous le récupérez dans le contexte lorsque le lien est suivi et que votre onglet est rechargé.

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

Vous devez remplacer les paramètres suivants par les informations appropriées :

Nom du paramètre Description
subPageId Identificateur unique de l’élément de votre page vers lequel vous établissez un lien profond.
subPageLabel Étiquette pour l’élément à utiliser pour afficher le lien profond.
subPageWebUrl URL de secours à utiliser si le client ne peut pas afficher la page.

Pour plus d’informations, consultez pages.shareDeepLink().

Remarque

  • Ce lien profond est différent des liens fournis par l’élément de menu Copier le lien vers l’onglet , qui génère uniquement un lien profond qui pointe vers cet onglet.
  • shareDeepLink ne fonctionne pas sur les plateformes mobiles Teams.

Les liens profonds pour les onglets SharePoint Framework (SPFx) permettent aux utilisateurs d’accéder directement à des onglets spécifiques au sein d’un site SharePoint ou d’une application Teams. Cela améliore l’expérience utilisateur en fournissant un accès rapide au contenu et aux fonctionnalités pertinents.

Vous pouvez utiliser le format de lien profond suivant dans un bot, un connecteur ou une extension de message carte :

https://teams.microsoft.com/l/entity/<appId>/<EntityId>?webUrl=<entityWebUrl>/<EntityName>.

Remarque

  • Lorsqu’un bot envoie un TextBlock message avec un lien profond, un nouvel onglet de navigateur s’ouvre lorsque les utilisateurs sélectionnent le lien. Cela se produit dans Chrome et l’application de bureau Microsoft Teams s’exécutant sur Linux.
  • Si le bot envoie la même URL de lien profond dans un Action.OpenUrl, l’onglet Teams s’ouvre dans le navigateur actuel lorsque l’utilisateur sélectionne le lien. Aucun nouvel onglet de navigateur n’est ouvert.

Paramètres de requête

Valeur Description
APP_ID VOTRE ID de manifeste.

Exemple : fxxxxxxx-0xxx-4xxx-8xxx-cxxxxxxxxxxx
entityID ID d’élément que vous avez fourni lors de la configuration de l’onglet.

Exemple : tasklist123
entityWebUrl URL de secours à utiliser si le client ne prend pas en charge le rendu de l’onglet.

Exemple : https://tasklist.example.com/123 ou https://tasklist.example.com/list123/task456
entityName Étiquette pour l’élément de votre onglet à utiliser lors de l’affichage du lien profond.

Exemple : Task List 123 ou Task 456

Un lien profond de dialogue est une sérialisation de l’objet TaskInfo avec deux autres détails, le APP_ID et éventuellement le 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

Pour les types de données et les valeurs autorisées pour <TaskInfo.url>, <TaskInfo.card>, <TaskInfo.width><TaskInfo.height>et <TaskInfo.title>, consultez l’objet TaskInfo.

Conseil

Encoder l’URL du lien profond lors de l’utilisation du card paramètre, par exemple, fonction JavaScriptencodeURI().

Le tableau suivant fournit des informations sur APP_ID et BOT_APP_ID :

Valeur Type Requis Description
APP_ID string Oui - Pour les applications tierces, utilisez l’application id à partir du manifeste ou du APP_ID centre d’administration Teams, car elles sont identiques.

- Pour les applications personnalisées ou les applications personnalisées créées pour votre organisation (applications métier), utilisez le APP_ID à partir du Centre d’administration Teams ou utilisez le API Graph.

- Le tableau validDomains dans le manifeste de APP_ID doit contenir le domaine pour url si url est présent dans l’URL de lien profond. L’ID d’application est déjà connu lorsqu’une boîte de dialogue est appelée à partir d’un onglet ou d’un bot, c’est pourquoi il n’est pas inclus dans TaskInfo.
BOT_APP_ID string Non Si une valeur est completionBotId spécifiée, l’objet est envoyé à l’aide result d’un task/submit invoke message au bot spécifié. Spécifiez BOT_APP_ID que doit être spécifié en tant que bot dans le manifeste de l’application, que vous ne pouvez pas envoyer à un bot.

Remarque

APP_ID et BOT_APP_ID peuvent être les mêmes dans de nombreux cas, si une application a un bot recommandé à utiliser comme ID d’application et s’il y en a un.

Lien profond pour partager du contenu dans la phase de réunion

Vous pouvez également générer un lien profond pour partager l’application pour mettre en scène et démarrer ou rejoindre une réunion.

Pour obtenir des liens approfondis permettant de partager du contenu à la phase, consultez lien profond pour partager du contenu à la phase dans les réunions.

Remarque

  • La génération d’un lien profond pour partager du contenu à l’étape des réunions est disponible uniquement dans la préversion publique pour les développeurs.
  • Le lien profond permettant de partager du contenu en phase de réunion est pris en charge uniquement dans le client de bureau Teams.

Vous pouvez générer un lien profond vers le panneau latéral de la réunion dans une réunion.

Utilisez le format suivant pour obtenir un lien profond vers le panneau latéral de la réunion :

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

Par défaut, un lien profond s’ouvre dans le panneau latéral d’une réunion. Pour ouvrir un lien profond directement dans une application plutôt que dans le panneau latéral de la réunion, ajoutez openInMeeting=false comme indiqué dans le format de lien profond suivant :

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

Pour plus d’informations, consultez lien profond vers un onglet.

Un lien profond ne s’ouvre pas dans le panneau latéral de la réunion dans les scénarios suivants :

  • Il n’y a pas de réunion active.
  • L’application n’a sidePanel pas de contexte déclaré dans le manifeste de l’application.
  • openInMeeting est défini sur false dans le lien profond.
  • Le lien profond est sélectionné en dehors de la fenêtre ou du composant de réunion.
  • Le lien profond ne correspond pas à la réunion actuelle, par exemple, si le lien profond est créé à partir d’une autre réunion.

Vous pouvez appeler Stageview via un lien profond à partir de votre onglet en encapsulant l’URL du lien profond dans l’API app.openLink(url) . Le lien profond peut également être transmis par une OpenURLaction dans la carte. La openMode propriété définie dans l’API détermine la réponse Stageview. Pour plus d’informations, consultez Appeler Stageview via un lien profond.

Meilleures pratiques

  • Les liens profonds fonctionnent correctement uniquement si l’onglet a été configuré à l’aide de la bibliothèque v0.4 ou ultérieure, car il a un ID d’entité. Les liens profonds vers des onglets sans ID d’entité continuent d’accéder à l’onglet, mais ne peuvent pas fournir le sub’EntityId à l’onglet.
  • Dans Microsoft Windows, Teams ne peut pas gérer les liens profonds dépassant 2 048 caractères en raison de la limite dans l’API INTERNET_MAX_URL_LENGTH Windows ShellExecuteEx.
  • Lors de la création d’un lien profond, vérifiez que le chemin d’accès au client Teams et d’autres métadonnées respectent cette limite.
  • Si votre lien profond contient des données volumineuses, incluez un identificateur unique dans le lien que votre application peut utiliser pour extraire les données nécessaires à partir de votre service principal.

Exemple de code

Exemple de nom Description .NET Node.js
Consommation de liens profonds subEntityId Cet exemple montre comment utiliser un lien profond à partir d’une conversation de bot vers un onglet utilisant le subEntityId. Il affiche également des liens profonds pour :
- Navigation vers une application
- Navigation vers une conversation
- Ouvrir une boîte de dialogue de profil
- Ouvrir une boîte de dialogue de planification		 View View
Navigation de l’application par onglet Cet exemple montre comment naviguer entre les onglets au sein de l’application. N/A View