Partage via

Lien profond vers une application

  • Article

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. Utilisez des liens profonds dans les messages de bot et de connecteur pour informer les utilisateurs des modifications apportées à votre onglet ou à ses éléments.

Vous pouvez créer 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. Vous pouvez également créer un lien profond vers l’application pour mobile, une fois votre application approuvée pour la plateforme 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 d’en savoir plus sur une application et de l’installer dans différentes étendues. Vous pouvez également créer des liens profonds pour que les utilisateurs de votre application accèdent à des pages spécifiques au sein de votre application. Dans cet article, découvrez comment créer un lien profond :

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.

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

Voici le format de lien profond dont vous avez besoin pour ouvrir une boîte de dialogue d’installation d’application à partir de votre client Teams à l’aide de l’ID d’application :

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

Où <your-app-id> est votre ID d’application (f46ad259-0fe5-4f12-872d-c737b174bcb4).

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 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 de déclenchement de 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 sur le appInstallDialog module, consultez appInstallDialog module.

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 a besoin de connecter les utilisateurs à d’autres contenus dans Teams, par exemple à un canal, un message, un autre onglet ou pour ouvrir une boîte de dialogue de planification. Dans de rares 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.

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 sur les fonctionnalités et les API dans TeamsJS, consultez Génération d’onglets et d’autres expériences hébergées avec la bibliothèque TeamsJS.

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

Remarque

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 de grandes quantités de données, incluez un identificateur unique dans le lien que votre application peut utiliser pour extraire les données nécessaires à partir de votre service principal.

Utilisez le format suivant pour un lien profond dans un bot, un connecteur ou une extension de message carte :

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.

Les paramètres de requête sont les suivants :

Nom du paramètre Description Exemple
appId  ID du Centre d’administration Microsoft Teams. 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 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. 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. 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 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 . 19:cbe3683f25094106b826c9cada3afbe0@thread.skype
context.chatId  ID de conversation disponible à partir du contexte d’onglet pour la conversation de groupe et de réunion. 17:b42de192376346a7906a7dd5cb84b673@thread.v2
context.contextType  La conversation est la seule prise en charge contextType pour les réunions. 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. false

Remarque

  • 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 un channelpropriété associé à son objet de contexte. Pour plus d’informations sur les étendues d’onglets, consultez le manifeste de l’application.
  • 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 l’ID de sous-entité à l’onglet.

Exemples :

  • Lien vers un onglet statique (personnel) lui-même :

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

  • Lien vers un élément de tâche dans l’onglet statique (personnel) :

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

  • Lier à un onglet configurable lui-même :

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

  • Lien vers un élément de tâche sous l’onglet configurable :

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

  • Lien vers une application onglet ajoutée à une réunion ou une conversation de groupe :

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

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 l’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 l’application de parcourir différentes pages au sein de votre application. 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 */ }

Pour plus d’informations sur l’utilisation de la fonctionnalité pages, consultez pages.navigateToApp() et l’espace de noms pages pour d’autres options de navigation. Si nécessaire, ouvrez directement un lien profond à l’aide de la fonction app.openLink().

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.

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 au format suivant :

https://teams.microsoft.com/l/entity/<appId>/conversations?tenantId=<tenantId>, où appId est votre ID d’application. Pour en savoir plus sur les différents ID d’application utilisés, 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 en 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 :

  • subPageId : un identificateur unique de l’élément dans votre onglet auquel vous effectuez un lien profond.
  • subPageLabel : étiquette de l’élément à utiliser pour afficher le lien profond.
  • subPageWebUrl: une 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.

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.

Les paramètres de requête sont les suivants :

  • appID: votre ID de manifeste, par exemple fe4a8eba-2a31-4737-8e33-e5fae6fee194.

  • entityID: ID d’élément que vous avez fourni lors de la configuration de l’onglet. Par exemple, tasklist123.

  • entityWebUrl: paramètre facultatif avec une URL de secours à utiliser si le client ne prend pas en charge le rendu de l’onglet ou https://tasklist.example.com/123https://tasklist.example.com/list123/task456.

  • entityName: étiquette pour l’élément de votre onglet à utiliser lors de l’affichage du lien profond, par Task List 123 exemple ou Task 456.

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

Un lien profond de dialogue est une sérialisation de l’objet TaskInfo avec deux autres détails, et APP_ID éventuellement :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 conçues pour votre organisation (applications métier), utilisez le à partir du APP_ID 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.

Générer un lien profond pour partager du contenu à l’étape des réunions

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

Exemple :

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

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 le format de lien profond :

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.

Exemple de code

Exemple de nom Description .NET Node.js
ID de sous-entité consommatrice de lien profond Cet exemple montre comment utiliser un lien profond à partir d’une conversation de bot vers un onglet utilisant l’ID de sous-entité. 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