Obtenir un contexte Teams pour votre onglet

Votre onglet requiert des informations contextuelles pour afficher du contenu pertinent :

  • Informations de base sur l’utilisateur, l’équipe ou la société.
  • Informations sur les paramètres régionaux et le thème.
  • Les page.id et page.subPageId identifient ce qui se trouve dans cet onglet (appelé entityId et subEntityId avant TeamsJS v2.0.0).

Contexte utilisateur

Le contexte sur l’utilisateur, l’équipe ou la société peut être particulièrement utile dans les cas suivants :

  • Vous créez ou associez des ressources dans votre application à l’utilisateur ou à l’équipe spécifié.
  • Vous lancez un flux d’authentification à partir de Microsoft Entra ID ou d’un autre fournisseur d’identité, et vous n’avez pas besoin que l’utilisateur entre à nouveau son nom d’utilisateur.

Pour plus d’informations, consultez Authentifier un utilisateur dans votre Microsoft Teams.

Importante

Bien que ces informations utilisateur puissent aider à fournir une expérience utilisateur fluide, vous ne devez pas les utiliser comme preuve d’identité. Par exemple, une personne malveillante peut charger votre page dans un navigateur et afficher des informations ou des requêtes nuisibles.

Accéder aux informations de contexte

Vous pouvez accéder aux informations de contexte de deux façons :

Obtenir du contexte en insérant des valeurs d’espace réservé d’URL

Utilisez des espaces réservés dans vos URL de configuration ou de contenu. Microsoft Teams remplace les espaces réservés par les valeurs appropriées lorsqu’il détermine l’URL de configuration ou de contenu. Les espaces réservés disponibles incluent tous les champs de l’objet de contexte . Les espaces réservés courants incluent les propriétés suivantes :

  • {page.id} : ID unique défini par le développeur pour la page lors de la première configuration de la page. (Connu comme {entityId} avant TeamsJS v2.0.0).
  • {page.subPageId} : ID unique défini par le développeur pour la sous-page que ce contenu pointe lors de la génération d’un lien profond pour un élément spécifique de la page. (Connu comme {subEntityId} avant TeamsJS v2.0.0).
  • {user.loginHint} : valeur appropriée comme indicateur de connexion pour Microsoft Entra ID. Il s’agit généralement du nom de connexion de l’utilisateur actuel dans son locataire d’origine. (Connu comme {loginHint} avant TeamsJS v2.0.0).
  • {user.userPrincipalName} : nom d’utilisateur principal de l’utilisateur actuel dans le client actuel. (Connu comme {userPrincipalName} avant TeamsJS v2.0.0).
  • {user.id} : ID d’objet Microsoft Entra de l’utilisateur actuel dans le client actuel. (Connu comme {userObjectId} avant TeamsJS v2.0.0).
  • {app.theme} : thème actuel de l’interface utilisateur (UI), tel que default, darkou glass, contrast. (Connu comme {theme} avant TeamsJS v2.0.0).
  • {team.groupId} : ID du groupe Microsoft 365 dans lequel réside l’onglet. (Connu comme {groupId} avant TeamsJS v2.0.0)
  • {user.tenant.id} : ID de locataire Microsoft Entra de l’utilisateur actuel. (Connu comme {tid} avant TeamsJS v2.0.0).
  • {app.locale} : les paramètres régionaux actuels de l’utilisateur au format languageId-countryId, par exemple en-us. (Connu comme {locale} avant TeamsJS v2.0.0).

Remarque

  • L’espace réservé {upn}précédent est désormais supprimé. Pour des raisons de compatibilité descendante, c’est un synonyme de {user.loginHint}.
  • Les versions mobiles (Android et iOS) de Microsoft Teams prennent en charge uniquement les espaces réservés TeamsJS v1.x.x.

Par exemple, dans le manifeste de votre application, si vous définissez votre attribut d’onglet configurationUrl sur "https://www.contoso.com/config?name={user.loginHint}&tenant={user.tenant.id}&group={team.groupId}&theme={app.theme}" et que l’utilisateur connecté a les attributs suivants :

  • Leur nom d’utilisateur est user@example.com.
  • L’ID de locataire de leur entreprise est e2653c-etc.
  • Il s’agit d’un membre du groupe Microsoft 365 avec l’ID 00209384-etc.
  • L’utilisateur a défini son thème Teams sur Sombre.

Teams appelle l’URL suivante lors de la configuration de l’onglet :

https://www.contoso.com/config?name=user@example.com&tenant=e2653c-etc&group=00209384-etc&theme=dark

Obtenir du contexte à l’aide de la bibliothèque JavaScript de Microsoft Teams

Vous pouvez également récupérer les informations de contexte à l’aide de la bibliothèque cliente JavaScript de Microsoft Teams.

Vous pouvez récupérer l’information en appelant microsoftTeams.app.getContext().then((context) => {/*...*/});.

Le code suivant fournit un exemple de variable de contexte :

{
 "app": {
   "host": {
     "clientType": "The type of host client. Possible values are android, ios, web, desktop, surfaceHub, teamsRoomsAndroid, teamsPhones, teamsDisplays rigel (deprecated, use teamsRoomsWindows instead)",
     "name": "",
     "ringId": "The current ring ID",
     "sessionId": "The unique ID for the current Teams session for use in correlating telemetry data"    },
   "iconPositionVertical": "",
   "locale": "The current locale of the user formatted as languageId-countryId (for example, en-us)",
   "osLocaleInfo": "",
   "parentMessageId": "The parent message ID from which this dialog is launched",
   "sessionId": "The unique ID for the current session used for correlating telemetry data",
   "theme": "The current UI theme: default | dark | glass | contrast",
   "userClickTime": "",
   "userFileOpenPreference": ""  },
 "channel": {
   "defaultOneNoteSectionId": "The OneNote section ID that is linked to the channel",
   "displayName": "The name of the current channel",
   "id": "The channel ID in the format 19:[id]@thread.skype",
   "membershipType": "",
   "ownerGroupId": "",
   "ownerTenantId": "",
   "relativeUrl": "The relative path to the SharePoint folder associated with the channel"  },
 "chat": { "id": "The chat ID in the format 19:[id]@thread.skype" },
 "meeting": {
   "id": "The meeting ID used by tab when running in meeting context"  },
 "page": {
   "frameContext": "The context where tab URL is loaded (for example, content, task, setting, remove, sidePanel)",
   "id": "The developer-defined unique ID for the entity this content points to",
   "isFullScreen": "Indicates if the tab is in full-screen",
   "isMultiWindow": "The indication whether the tab is in a pop out window",
   "sourceOrigin": "",
   "subPageId": "The developer-defined unique ID for the sub-entity this content points to"  },
 "sharepoint": "The SharePoint context is available only when hosted in SharePoint",
 "sharepointSite": {
   "teamSiteDomain": "The domain of the root SharePoint site associated with the team",
   "teamSitePath": "The relative path to the SharePoint site associated with the team",
   "teamSiteUrl": "The root SharePoint site associated with the team"  },
 "team": {
   "displayName": "The name of the current team",
   "groupId": "Guid identifying the current Office 365 Group ID",
   "internalId": "The Microsoft Teams ID in the format 19:[id]@thread.skype",
   "isArchived": "Indicates if team is archived",
   "templateId": "",
   "type": "The type of team",
   "userRole": "The user's role in the team"  },
 "user": {
   "displayName": "",
   "id": "The Azure AD object id of the current user, in the current tenant",
   "isCallingAllowed": "Indicates if calling is allowed for the current logged in user",
   "isPSTNCallingAllowed": "Indicates if PSTN calling is allowed for the current logged in user",
   "licenseType": "The license type for the current user. Possible values are E1, E3, and E5 enterprise plans",
   "loginHint": "A value suitable as a login hint for Azure AD. This is usually the login name of the current user, in their home tenant",
   "tenant": {
     "id": "The Azure AD tenant ID of the current user",
     "teamsSku": "The license type for the current user tenant. Possible values are enterprise, free, edu, unknown"    },
   "userPrincipalName": "The principal name of the current user, in the current tenant"  }
}

TypeScript

import { app, Context } from "@microsoft/teams-js";

app.getContext().then((context: Context) => {
    /*...*/
});

Modèle équivalent async/await :

import { app, Context } from "@microsoft/teams-js";

async function example() {
  const context: Context = await app.getContext();
  /*...*/
}

JavaScript

import { app, Context } from "@microsoft/teams-js";

app.getContext().then((context) => {
    /*...*/
});

Modèle équivalent async/await :

import { app, Context } from "@microsoft/teams-js";

async function example() {
  const context = await app.getContext();
  /*...*/
}

Le tableau suivant répertorie les propriétés de contexte couramment utilisées de l’objet de contexte :

Nom TeamsJS v2 Nom TeamsJS v1
team.internalId teamId
team.displayName teamName
channel.id channelId
channel.displayName channelName
chat.id chatId
app.locale local
page.id entityId
page.subPageId subEntityId
user.loginHint loginHint
user.userPrincipalName UPN
user.id userObjectId
user.tenant.id tid
team.groupId groupId
app.theme thème
page.isFullScreen IsFullScreen
team.type teamType
sharepointSite.teamSiteUrl teamSiteUrl
sharepointSite.teamSiteDomain teamSiteDomain
sharepointSite.teamSitePath teamSitePath
channel.relativeUrl channelRelativeUrl
app.host.sessionId sessionId
team.userRole userTeamRole
team.isArchived isTeamArchived
app.host.clientType hostClientType
page.frameContext frameContext
sharepoint sharepoint
user.tenant.teamsSku tenantSKU
user.licenseType userLicenseType
app.parentMessageId parentMessageId
app.host.ringId ringId
app.sessionId id de session d’application
user.isCallingAllowed isCallingAllowed
user.isPSTNCallingAllowed isPSTNCallingAllowed
meeting.id meetingId
channel.defaultOneNoteSectionId defaultOneNoteSectionId
page.isMultiWindow isMultiWindow

Pour plus d’informations, consultez Mises à jour sur l’interface contextuelle et la référence de l’API d’interfacecontextuelle.

Récupérer le contexte dans les canaux privés

Remarque

Les canaux privés sont en préversion privée pour les développeurs uniquement.

Lorsque votre page de contenu est chargée dans un canal privé, les données que vous recevez de l’appel getContext sont obscurcies pour protéger la confidentialité du canal.

Les champs suivants sont modifiés lorsque votre page de contenu se trouve dans un canal privé :

  • team.groupId: non défini pour les canaux privés
  • team.internalId: Définir sur le threadId du canal privé
  • team.displayName: Définir le nom du canal privé
  • sharepointSite.teamSiteUrl: définissez l’URL d’un site SharePoint distinct et unique pour le canal privé
  • sharepointSite.teamSitePath: définir le chemin d’accès d’un site SharePoint distinct et unique pour le canal privé
  • sharepointSite.teamSiteDomain: définissez le domaine d’un domaine de site SharePoint distinct et unique pour le canal privé
  • channel.ownerGroupId: Définir sur l’ID de groupe de l’équipe hôte du canal privé

Si votre page utilise l’une de ces valeurs, la valeur du channel.membershipType champ doit être Private pour déterminer si votre page est chargée dans un canal privé et peut répondre de manière appropriée.

Remarque

teamSiteUrl Fonctionne également bien pour les canaux standard. Si votre page utilise l’une de ces valeurs, la valeur du channelType champ doit être Shared pour déterminer si votre page est chargée dans un canal partagé et peut répondre de manière appropriée.

Obtenir du contexte dans des canaux partagés

Lorsque l’expérience utilisateur de contenu est chargée dans un canal partagé, utilisez les données reçues de l’appel pour les modifications de getContext canal partagé. Si tab utilise l’une des valeurs suivantes, vous devez remplir le channelType champ pour déterminer si l’onglet est chargé dans un canal partagé et répondre de manière appropriée. Pour les canaux partagés, la groupId valeur est null, car le groupId de l’équipe hôte ne reflète pas précisément l’appartenance réelle au canal partagé. Pour résoudre ce problème, les hostTeamGroupID propriétés and hostTenantID sont récemment ajoutées et sont utiles pour effectuer des appels d’API Graph Microsoft afin de récupérer l’appartenance. hostTeam fait référence à l’équipe qui a créé le canal partagé. currentTeam fait référence à l’équipe à partir de laquelle l’utilisateur actuel accède au canal partagé.

Pour plus d’informations sur ces concepts et les canaux partagés, voir Canaux partagés.

Utilisez les propriétés suivantes dans les getContext canaux partagés :

Propriété Description
channelId La propriété est définie sur l’ID de thread des canaux partagés.
channelType La propriété est définie sur sharedChannel pour les canaux partagés.
groupId La propriété est null destinée aux canaux partagés.
hostTenantId La propriété vient d’être ajoutée et décrit l’ID de locataire de l’hôte, utile pour comparer avec la propriété ID de locataire de tid l’utilisateur actuel.
hostTeamGroupId La propriété vient d’être ajoutée et décrit l’ID de groupe Microsoft Entra de l’équipe hôte, utile pour effectuer des appels d’API Graph Microsoft afin de récupérer une appartenance à un canal partagé.
teamId La propriété est nouvellement ajoutée et définie sur l’ID de thread de l’équipe partagée actuelle.
teamName La propriété est définie sur current shared team’s teamName.
teamType La propriété est définie sur current shared team’s teamType.
teamSiteUrl La propriété décrit le channelSiteUrlcanal partagé .
teamSitePath La propriété décrit le channelSitePathcanal partagé .
teamSiteDomain La propriété décrit le channelSiteDomaincanal partagé .
tenantSKU La propriété décrit le tenantSKU.
tid La propriété décrit l’ID de locataire de l’utilisateur actuel.
userObjectId La propriété décrit l’ID de l’utilisateur actuel.
userPrincipalName La propriété décrit l’UPN de l’utilisateur actuel.

Pour plus d’informations sur les canaux partagés, voir Canaux partagés.

Gérer le changement de thème

Importante

  • Par défaut, le nouveau client Teams prend en charge le thème clair pour les applications dans les réunions Teams. Lorsque la propriété de l’API app.theme getContext renvoie la valeur, le client Teams est dans le default thème clair.
  • Les versions antérieures des clients Teams prennent uniquement en charge le thème foncé et contrasté pour les applications dans les réunions Teams.

Vous pouvez inscrire votre application pour être informé si le thème change en appelant microsoftTeams.app.registerOnThemeChangeHandler(function(theme) { /* ... */ }).

L’argument theme de la fonction est une chaîne de caractères ayant la valeur default, , dark, glassou contrast. La propriété AppInfo de l’API getContext prend en charge le thème pour les glass équipes exécutées sur des appareils Apple Vision Pro.

L’image suivante montre l’option de thème par défaut dans Teams :

La capture d’écran montre le thème par défaut dans le client de bureau Teams.

Exemple de code

Exemple de nom Description JavaScript
Contexte de canal d’onglet Cet exemple illustre les fonctionnalités d’une application d’onglet qui affiche l’objet de contexte d’onglet spécifiquement pour les canaux privés et partagés dans Microsoft Teams. Les utilisateurs peuvent développer et copier des tranches JSON à partir de l’objet contextuel, ce qui fournit des informations précieuses en fonction du type de canal. View

Voir aussi

  • Dernière mise à jour :