Obtención del contexto de Teams para la pestaña

  • Artículo

La pestaña requiere información contextual para mostrar el contenido pertinente:

  • Información básica sobre el usuario, el equipo o la empresa.
  • Configuración regional e información del tema.
  • page.id y page.subPageId que identifican lo que hay en esta pestaña (conocido como entityId y subEntityId antes de TeamsJS v2.0.0).

Contexto del usuario

El contexto sobre el usuario, el equipo o la empresa puede ser especialmente útil cuando:

  • Crea o asocia recursos en la aplicación con el usuario o equipo especificados.
  • Se inicia un flujo de autenticación desde Microsoft Entra ID u otro proveedor de identidades y no es necesario que el usuario vuelva a escribir su nombre de usuario.

Para obtener más información, consulte Autenticación de un usuario en Microsoft Teams.

Importante

Aunque esta información de usuario puede ayudar a proporcionar una experiencia de usuario fluida, no debe usarla como prueba de identidad. Por ejemplo, un atacante puede cargar la página en un explorador y representar información o solicitudes dañinas.

Acceso a la información de contexto

Puede acceder a la información contextual de dos formas:

Obtener contexto insertando valores de marcador de posición de dirección URL

Use marcadores de posición en la configuración o en las direcciones URL de contenido. Microsoft Teams reemplaza los marcadores de posición por valores pertinentes al determinar la configuración o la dirección URL real del contenido. Los marcadores de posición disponibles incluyen todos los campos del objeto de contexto . Los marcadores de posición comunes incluyen las siguientes propiedades:

  • {page.id}: identificador único definido por el desarrollador para la página definida al configurar la página por primera vez. (Conocido como {entityId} antes de TeamsJS v2.0.0).
  • {page.subPageId}: el identificador único definido por el desarrollador para la subpágina que estos puntos de contenido definen al generar un vínculo profundo para un elemento específico dentro de la página. (Conocido como {subEntityId} antes de TeamsJS v2.0.0).
  • {user.loginHint}: valor adecuado como sugerencia de inicio de sesión para Microsoft Entra ID. Este suele ser el nombre de inicio de sesión del usuario actual en su inquilino principal. (Conocido como {loginHint} antes de TeamsJS v2.0.0).
  • {user.userPrincipalName}: el nombre principal de usuario del usuario actual en el inquilino actual. (Conocido como {userPrincipalName} antes de TeamsJS v2.0.0).
  • {user.id}: el identificador de objeto Microsoft Entra del usuario actual en el inquilino actual. (Conocido como {userObjectId} antes de TeamsJS v2.0.0).
  • {app.theme}: tema de la interfaz de usuario (UI) actual, como default, darko contrast. (Conocido como {theme} antes de TeamsJS v2.0.0).
  • {team.groupId}: el identificador del grupo de Microsoft 365 en el que reside la pestaña. (Conocido como {groupId} antes de TeamsJS v2.0.0)
  • {user.tenant.id}: el identificador de inquilino Microsoft Entra del usuario actual. (Conocido como {tid} antes de TeamsJS v2.0.0).
  • {app.locale}: la configuración regional actual del usuario con formato languageId-countryId, por ejemplo en-us. (Conocido como {locale} antes de TeamsJS v2.0.0).

Nota:

  • El marcador de posición {upn} anterior está en desuso. Para la compatibilidad con versiones anteriores, actualmente es un sinónimo de {user.loginHint}.
  • Las versiones móviles (Android e iOS) de Microsoft Teams solo admiten actualmente marcadores de posición TeamsJS v1.x.x.

Por ejemplo, en el manifiesto de la aplicación si establece el atributo "https://www.contoso.com/config?name={user.loginHint}&tenant={user.tenant.id}&group={team.groupId}&theme={app.theme}" tab configurationUrl en y el usuario que ha iniciado sesión tiene los siguientes atributos:

  • Su nombre de usuario es user@example.com.
  • Su identificador de inquilino de empresa es e2653c-etc.
  • Son miembros del grupo de Microsoft 365 con el identificador 00209384, etc.
  • El usuario ha establecido su tema de Teams en oscuro.

Teams llama a la siguiente dirección URL al configurar la pestaña:

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

Obtener contexto mediante la biblioteca JavaScript de Microsoft Teams

También puede recuperar la información de contexto mediante la biblioteca cliente javascript de Microsoft Teams.

La información se puede recuperar llamando a microsoftTeams.app.getContext().then((context) => {/*...*/});.

El código siguiente proporciona un ejemplo de variable de contexto:

{
 "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 | 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": {
   "domain": "The domain of the root SharePoint site associated with the team",
   "path": "The relative path to the SharePoint site associated with the team",
   "url": "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) => {
    /*...*/
});

Patrón equivalente 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) => {
    /*...*/
});

Patrón equivalente async/await :

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

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

En la tabla siguiente se enumeran las propiedades de contexto usadas habitualmente del objeto de contexto :

Nombre de TeamsJS v2 Nombre de TeamsJS v1
team.internalId teamId
team.displayName teamName
channel.id channelId
channel.displayName channelName
chat.id chatId
app.locale configuración regional
page.id entityId
page.subPageId subEntityId
user.loginHint loginHint
user.userPrincipalName Upn
user.id userObjectId
user.tenant.id Tid
team.groupId groupId
app.theme theme
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 appSessionId
user.isCallingAllowed isCallingAllowed
user.isPSTNCallingAllowed isPSTNCallingAllowed
meeting.id Id. de la reunión
channel.defaultOneNoteSectionId defaultOneNoteSectionId
page.isMultiWindow isMultiWindow

Para obtener más información, consulte Novedades a la interfaz context y la referencia de la API de interfaz de contexto.

Recuperar contexto en canales privados

Nota:

Actualmente, los canales privados solo están en versión preliminar para desarrolladores privados.

Cuando la página de contenido se carga en un canal privado, los datos que recibe de la getContext llamada se ofuscan para proteger la privacidad del canal.

Los campos siguientes se cambian cuando la página de contenido está en un canal privado:

  • team.groupId: no definido para canales privados
  • team.internalId: se establece en el threadId del canal privado.
  • team.displayName: se establece en el nombre del canal privado.
  • sharepointSite.url: se establece en la dirección URL de un sitio de SharePoint único y distinto para el canal privado.
  • sharepointSite.path: se establece en la ruta de acceso de un sitio de SharePoint único y distinto para el canal privado.
  • sharepointSite.domain: se establece en el dominio de un dominio de sitio de SharePoint único y distinto para el canal privado.
  • channel.ownerGroupId: se establece en el groupId del equipo host del canal privado.

Si la página usa cualquiera de estos valores, el valor del channel.membershipType campo debe ser Private determinar si la página se carga en un canal privado y puede responder correctamente.

Nota:

teamSiteUrl también funciona bien para los canales estándar. Si la página usa cualquiera de estos valores, el valor del channelType campo debe ser Shared determinar si la página se carga en un canal compartido y puede responder correctamente.

Obtener contexto en canales compartidos

Cuando la experiencia de usuario de contenido se cargue en un canal compartido, use los datos recibidos de getContext la llamada para los cambios de canal compartido. Si tab usa cualquiera de los valores siguientes, debe rellenar el channelType campo para determinar si la pestaña se carga en un canal compartido y responder correctamente. En el caso de los canales compartidos, el groupId valor es null, ya que el groupId del equipo host no refleja con precisión la pertenencia verdadera del canal compartido. Para solucionar este problema, las hostTeamGroupID propiedades y hostTenantID se agregan recientemente y son útiles para realizar llamadas de Microsoft Graph API para recuperar la pertenencia. hostTeam hace referencia al equipo que creó el canal compartido. currentTeam hace referencia al equipo desde el que el usuario actual tiene acceso al canal compartido.

Para obtener más información sobre estos conceptos y canales compartidos, consulte Canales compartidos.

Use las siguientes getContext propiedades en canales compartidos:

Propiedad Descripción
channelId La propiedad se establece en el identificador de subproceso de canales compartidos.
channelType La propiedad se establece en sharedChannel para canales compartidos.
groupId La propiedad es null para canales compartidos.
hostTenantId La propiedad se ha agregado recientemente y describe el identificador de inquilino del host, útil para compararla con la propiedad de identificador de inquilino del tid usuario actual.
hostTeamGroupId La propiedad se ha agregado recientemente y describe el identificador de grupo Microsoft Entra del equipo host, útil para realizar llamadas de Microsoft Graph API para recuperar la pertenencia a canales compartidos.
teamId La propiedad se agrega recientemente y se establece en el identificador de subproceso del equipo compartido actual.
teamName La propiedad se establece en el equipo teamNamecompartido actual.
teamType La propiedad se establece en el equipo teamTypecompartido actual.
teamSiteUrl La propiedad describe la propiedad del channelSiteUrlcanal compartido.
teamSitePath La propiedad describe la propiedad del channelSitePathcanal compartido.
teamSiteDomain La propiedad describe la propiedad del channelSiteDomaincanal compartido.
tenantSKU La propiedad describe la propiedad del tenantSKUequipo host.
tid La propiedad describe el identificador de inquilino del usuario actual.
userObjectId La propiedad describe el identificador del usuario actual.
userPrincipalName La propiedad describe el UPN del usuario actual.

Para obtener más información sobre los canales compartidos, consulte canales compartidos.

Controlar el cambio de tema

Importante

  • De forma predeterminada, el nuevo cliente de Teams admite el tema claro para las aplicaciones en reuniones de Teams. Cuando la propiedad de getContext app.theme API devuelve el valor, el default cliente de Teams está en un tema claro.
  • La versión anterior de los clientes de Teams solo admite el tema Oscuro y Contraste para las aplicaciones de las reuniones de Teams.

Puede registrar la aplicación para que se le informe si el tema cambia llamando a microsoftTeams.app.registerOnThemeChangeHandler(function(theme) { /* ... */ }).

El theme argumento de la función es una cadena con un valor de default, darko contrast.

En la imagen siguiente se muestra la opción de tema predeterminada en Teams:

Captura de pantalla que muestra el tema predeterminado en el cliente de escritorio de Teams.

Ejemplo de código

Ejemplo de nombre Descripción JavaScript
Contexto de canal de tabulación En este ejemplo se muestra cómo usar el contenido del objeto de contexto de tabulación en un canal privado y compartido. View

Paso siguiente

Compilar pestañas con tarjetas adaptables

Consulte también