Vínculo profundo a una aplicación

  • Artículo
  • Tiempo de lectura: 12 minutos

La aplicación puede abrir el cuadro de diálogo de perfil a través de vínculos profundos y ayudar a los usuarios a obtener más información sobre la aplicación, los permisos y mucho más. Puede crear un vínculo profundo para la aplicación después de que la aplicación aparezca en la tienda de Teams. Para crear un vínculo para iniciar Teams, anexe el identificador de la aplicación a la dirección URL, https://teams.microsoft.com/l/app/<your-app-id>. Aparece un cuadro de diálogo para instalar o abrir la aplicación.

Si la aplicación está aprobada para la plataforma móvil, puede vincularla en profundidad a una aplicación en el móvil. Además, se requiere el id. de equipo de Apple App Store Connect para que el vínculo profundo funcione en Teams-iOS. Para obtener más información, consulte cómo actualizar el id. de equipo de Apple App Store Connect.

No se admite el vínculo profundo a una aplicación para aplicaciones personalizadas.

Nota:

En este tema se refleja la versión 2.0.x de la biblioteca cliente JavaScript de Microsoft Teams (TeamsJS). Si usa una versión anterior, consulte la introducción a la biblioteca TeamsJS para obtener instrucciones sobre las diferencias entre la versión más reciente de TeamsJS y las versiones anteriores.

Abrir el cuadro de diálogo del perfil de aplicación

Puede abrir un cuadro de diálogo de instalación de aplicaciones desde la aplicación de Teams y también puede instalar la aplicación en otros contextos. Use el siguiente formato de vínculo profundo para abrir un cuadro de diálogo de instalación de aplicaciones desde Teams:

https://teams.microsoft.com/l/app/<your-app-id>, donde <your-app-id> es el identificador de la aplicación(f46ad259-0fe5-4f12-872d-c737b174bcb4).

Las aplicaciones pueden usar la biblioteca TeamsJS para abrir el cuadro de diálogo sin generar manualmente el vínculo profundo. A continuación se muestra un ejemplo para abrir el cuadro de diálogo de instalación de la aplicación mediante TeamsJS:

// Open an app install dialog from your tab
if(appInstallDialog.isSupported()) {
    const dialogPromise = appInstallDialog.openAppInstallDialog({ appId: "f46ad259-0fe5-4f12-872d-c737b174bcb4" });
    dialogPromise.
      then((result) => {/*Successful operation*/}).
      catch((error) => {/*Unsuccessful operation*/});
}
else { /* handle case where capability isn't supported */ }

Para obtener más información sobre el cuadro de diálogo de instalación, consulte la función appInstallDialog.openAppInstallDialog() en la documentación de referencia de la API.

Es posible navegar dentro de una aplicación mediante TeamsJS. En el código siguiente se muestra cómo navegar a una entidad específica dentro de la aplicación de Teams.

Puede desencadenar una navegación desde la pestaña mediante la función pages.navigateToApp() como se muestra en el código siguiente:

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

Para obtener más información sobre el uso de la funcionalidad páginas, consulte pages.navigateToApp() y el espacio de nombres páginas para ver otras opciones de navegación. Si es necesario, también es posible abrir directamente un vínculo profundo mediante la función app.openLink().

El comportamiento de navegación de una aplicación de Teams extendida en Microsoft 365 Office depende de dos factores:

  1. Destino al que apunta el vínculo profundo.
  2. Host en el que se ejecuta la aplicación de Teams.

Si la aplicación Teams se ejecuta dentro del host donde se dirige el vínculo profundo, la aplicación se abrirá directamente dentro del host. Sin embargo, si la aplicación de Teams se ejecuta en un host diferente del destino del vínculo profundo, la aplicación se abrirá primero en el explorador.

Puede navegar a un usuario a un chat personal con la aplicación mediante la preparación manual del vínculo con el siguiente formato:

https://teams.microsoft.com/l/entity/<appId>/conversations, donde appId es el identificador de la aplicación y las siguientes listas appId para diferentes aplicaciones:

  • Aplicaciones cargadas en paralelo: id. de manifiesto
  • Aplicaciones enviadas al catálogo de la organización: Id. de catálogo de organización
  • Aplicaciones enviadas a la tienda de aplicaciones de Teams: Id. de la Tienda

Puede crear vínculos profundos a entidades en las aplicaciones de Teams. Se usa para crear vínculos que naveguen al contenido y a la información dentro de la pestaña. Por ejemplo, si la pestaña contiene una lista de tareas, los miembros del equipo pueden crear y compartir vínculos a tareas individuales. Al seleccionar el vínculo, navega a la pestaña que se centra en el elemento específico.

Para implementar, agregue una acción copiar vínculo a cada elemento, de la manera que mejor se adapte a su interfaz de usuario. Cuando el usuario realice esta acción, llame pages.shareDeepLink() a para mostrar un cuadro de diálogo que contiene un vínculo que el usuario puede copiar en el Portapapeles. Cuando realice esta llamada, pase un id. para el elemento. Se devuelve en contexto cuando se sigue el vínculo y se vuelve a cargar la pestaña.

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

Tendrá que reemplazar los campos por la información adecuada:

  • subPageId: identificador único del elemento de la pestaña al que está vinculando en profundidad.
  • subPageLabel: etiqueta del elemento que se va a usar para mostrar el vínculo profundo.
  • subPageWebUrl: dirección URL de reserva que se usará si el cliente no puede representar la página.

Para obtener más información, vea pages.shareDeepLink().

Como alternativa, también puede generar vínculos profundos mediante programación con el formato especificado más adelante en este artículo. Puede usar vínculos profundos en mensajes de bot y conector que informan a los usuarios sobre los cambios en la pestaña o en los elementos que contiene.

Nota:

  • Este vínculo profundo es diferente de los vínculos proporcionados por el elemento de menú Copiar vínculo a la pestaña, que solo genera un vínculo profundo que apunta a esta pestaña.
  • Actualmente, shareDeepLink no funciona en plataformas móviles.

Aunque se recomienda usar shareDeepLink() para generar un vínculo profundo a la pestaña, también es posible crear uno manualmente.

Nota:

  • Las pestañas personales tienen un ámbito personal, mientras que las pestañas de canal y grupo usan ámbitos team o group. Los dos tipos de pestaña tienen una sintaxis ligeramente diferente, ya que solo la pestaña configurable tiene una propiedad channel asociada a su objeto de contexto. Para obtener más información sobre los ámbitos de pestaña, consulte la referencia del manifiesto .
  • Los vínculos profundos solo funcionan correctamente si la pestaña se configuró mediante la biblioteca v0.4 o posterior, ya que tiene un identificador de entidad. Los vínculos profundos a pestañas sin identificadores de entidad siguen a la pestaña, pero no pueden proporcionar el identificador de subentidad a la pestaña.

Use el formato siguiente para un vínculo profundo que puede usar en un bot, conector o tarjeta de extensión de mensajería:

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

Nota:

  • Si el bot envía un mensaje que contiene un TextBlock con un vínculo profundo, se abre una nueva pestaña del explorador cuando el usuario selecciona el vínculo. Esto sucede en Chrome y en la aplicación de escritorio de Teams, ejecutados en Linux.
  • Si el bot envía la misma dirección URL de vínculo profundo a , Action.OpenUrlla pestaña Teams se abre en la pestaña del explorador actual cuando el usuario selecciona el vínculo.

Los parámetros de consulta son:

Nombre del parámetro Descripción Ejemplo
appId  Identificador del Centro de administración de Teams. fe4a8eba-2a31-4737-8e33-e5fae6fee194
entityId  Identificador del elemento de la pestaña, que proporcionó al configurar la pestaña. Al generar una dirección URL para la vinculación profunda, siga usando el identificador de entidad como nombre de parámetro en la dirección URL. Al configurar la pestaña, el objeto de contexto hace referencia a entityID como {page.id}. Lista de tareas123
entityWebUrl o subEntityWebUrl  Un campo opcional con una dirección URL de reserva que se usará si el cliente no admite la representación de la pestaña. https://tasklist.example.com/123 o https://tasklist.example.com/list123/task456
entityLabel o subEntityLabel  Etiqueta para el elemento de la pestaña que se va a usar al mostrar el vínculo profundo. Lista de tareas 123 o Tarea 456
context.subEntityId  Un identificador para el elemento dentro de la pestaña. Al generar una dirección URL para la vinculación profunda, siga usando subEntityId como nombre de parámetro en la dirección URL. Al configurar la pestaña, el objeto de contexto hace referencia al subEntityID como subPageID. Tarea 456
context.channelId  Id. de canal de Microsoft Teams que está disponible en la pestaña contexto. Esta propiedad solo está disponible en pestañas configurables con un ámbito de equipo. No está disponible en pestañas estáticas, que tienen un ámbito personal. 19:cbe3683f25094106b826c9cada3afbe0@thread.skype
context.chatId  Identificador de chat que está disponible en el contexto de pestaña para el chat de grupo y reunión. 17:b42de192376346a7906a7dd5cb84b673@thread.v2
context.contextType  Chat es el único contextType admitido para las reuniones. chat

Ejemplos:

  • Vínculo a una pestaña estática (personal):

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

  • Vínculo a un elemento de tarea dentro de la pestaña estática (personal):

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

  • Vínculo a una pestaña configurable:

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

  • Vínculo a un elemento de tarea en la pestaña 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"}

  • Vínculo a una aplicación de pestaña agregada a una reunión o chat grupal:

    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

Asegúrese de que todos los parámetros de consulta y los espacios en blanco estén correctamente codificados mediante URI. Debe seguir los ejemplos anteriores con el último ejemplo:

var encodedWebUrl = encodeURIComponent(JSON.stringify('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;

Puede navegar hasta el contenido de Teams desde la pestaña mediante TeamsJS o vínculos profundos. Esto resulta útil si la pestaña necesita conectar usuarios con otro contenido de Teams, como un canal, un mensaje, otra pestaña o abrir un cuadro de diálogo de programación. Anteriormente, la navegación podría haber requerido un vínculo profundo, pero ahora se puede realizar en muchos casos mediante la biblioteca TeamsJS. Sin embargo, siempre que sea posible, se recomienda el uso de las funcionalidades con tipo de la biblioteca TeamsJS.

Una de las ventajas de usar TeamsJS, especialmente para la aplicación de Teams que se puede ejecutar en otros hosts (Outlook y Office), es que es posible comprobar si el host admite la funcionalidad que intenta usar. Para comprobar la compatibilidad de un host con una funcionalidad, puede usar la función isSupported() asociada al espacio de nombres de la API. La biblioteca TeamsJS organiza las API en funcionalidades mediante espacios de nombres. Por ejemplo, antes de usar una API en el pages espacio de nombres, puede comprobar el valor booleano devuelto desde pages.isSupported() y realizar la acción adecuada en el contexto de la interfaz de usuario de aplicaciones y aplicaciones.

Para obtener más información sobre las funcionalidades y las API de la biblioteca TeamsJS, consulte Creación de pestañas y otras experiencias hospedadas con la biblioteca TeamsJS.

Puede usar el siguiente formato de vínculo profundo en un bot, conector o tarjeta de extensión de mensaje: https://teams.microsoft.com/l/entity/<AppId>/<EntityId>?webUrl=<entityWebUrl>/<EntityName>.

Nota:

  • Cuando un bot envía un mensaje de TextBlock con un vínculo profundo, se abre una nueva pestaña del explorador cuando los usuarios seleccionan el vínculo. Esto sucede en Chrome y en la aplicación de escritorio de Microsoft Teams, ejecutados en Linux.
  • Si el bot envía la misma dirección URL de vínculo profundo en un Action.OpenUrl, la pestaña Teams se abre en el explorador actual cuando el usuario selecciona el vínculo. No se abre una nueva pestaña del explorador.

Los parámetros de consulta son:

  • appID: el identificador del manifiesto, por ejemplo, fe4a8eba-2a31-4737-8e33-e5fae6fee194.

  • entityID: el identificador de elemento que proporcionó al configurar la pestaña. Por ejemplo, tasklist123.

  • entityWebUrl: campo opcional con una dirección URL de reserva que se usará si el cliente no admite la representación de la pestaña (https://tasklist.example.com/123 o https://tasklist.example.com/list123/task456).

  • entityName: etiqueta para el elemento de la pestaña que se va a usar al mostrar el vínculo profundo, Task List 123 o Task 456.

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

Un vínculo profundo del módulo de tareas es una serialización del TaskInfo objeto con otros dos detalles, APP_ID y opcionalmente :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

Para conocer los tipos de datos y los valores permitidos para <TaskInfo.url>, <TaskInfo.card>, <TaskInfo.height>, <TaskInfo.width> y <TaskInfo.title>, consulte Objeto TaskInfo.

Sugerencia

Codifique la dirección URL del vínculo profundo al usar el card parámetro , por ejemplo, la función de JavaScriptencodeURI().

En la siguiente tabla se proporciona información sobre APP_ID y BOT_APP_ID:

Valor Tipo Obligatorio Descripción
APP_ID string Sí El identificador de la aplicación que invoca el módulo de tareas. La matriz validDomains del manifiesto de APP_ID debe contener el dominio para url si url está en la dirección URL. El identificador de la aplicación ya se conoce cuando se invoca un módulo de tareas desde una pestaña o un bot, por lo que no se incluye en TaskInfo.
BOT_APP_ID string No Si se especifica un valor para completionBotId, el objeto result se envía mediante un mensaje task/submit invoke al bot especificado. BOT_APP_ID debe especificarse como un bot en el manifiesto de la aplicación, es decir, no se puede enviar a ningún bot.

Nota:

APP_ID y BOT_APP_ID puede ser el mismo en muchos casos, si una aplicación tiene un bot recomendado para usarlo como identificador de una aplicación y si hay uno.

Ejemplo de código

Ejemplo de nombre Descripción .NET Node.js
Identificador de subentidad que consume vínculo profundo En este ejemplo se muestra cómo usar vínculos profundos desde el chat del bot hasta el identificador de subentidad de consumo de pestañas. También muestra vínculos profundos para navegar a la aplicación, navegar al chat, abrir el cuadro de diálogo de perfil y abrir el cuadro de diálogo de programación. View View