Compartir vía

Vínculo profundo a una aplicación

  • Artículo

Los vínculos profundos están configurados para realizar varias acciones, como abrir una pestaña, iniciar un cuadro de diálogo de instalación de la aplicación o examinar dentro de la aplicación. Use vínculos profundos en los mensajes de bot y conector para informar a los usuarios sobre los cambios en la pestaña o sus elementos.

Puede crear vínculos profundos para una aplicación personalizada. Sin embargo, si una aplicación de la Tienda Microsoft Teams comparte el mismo identificador de aplicación que el identificador de aplicación personalizado, el vínculo profundo abre la aplicación desde la Tienda Teams en lugar de la aplicación personalizada. También puede crear un vínculo profundo a la aplicación para dispositivos móviles, una vez aprobada la aplicación para la plataforma móvil de Teams. Para que el vínculo profundo funcione en Teams iOS, necesita el id. de equipo de Apple App Store Connect. Para obtener más información, consulte cómo actualizar el id. de equipo de Apple App Store Connect.

Los vínculos profundos permiten a los usuarios obtener más información sobre una aplicación e instalarla en distintos ámbitos. También puede crear vínculos profundos para que los usuarios de la aplicación vayan a páginas específicas dentro de la aplicación. En este artículo, aprenderá a crear un vínculo profundo:

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.

Los vínculos profundos permiten a los usuarios de la aplicación abrir un cuadro de diálogo de instalación de la aplicación para obtener más información sobre la aplicación o instalarla en contextos diferentes. Puede crear un vínculo profundo a la aplicación de las siguientes maneras:

Este es el formato de vínculo profundo que necesita para abrir un cuadro de diálogo de instalación de aplicaciones desde el cliente de Teams mediante el identificador de aplicación:

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

Dónde <your-app-id> está el identificador de la aplicación (f46ad259-0fe5-4f12-872d-c737b174bcb4).

Id. de aplicación para diferentes tipos de aplicaciones

En la tabla siguiente se enumeran los distintos tipos de identificadores de aplicación usados para diferentes tipos de aplicaciones para vínculos profundos:

Tipo de aplicación Tipo de identificador de aplicación
Aplicación personalizada cargada en Teams Identificador de manifiesto
Aplicaciones enviadas al catálogo de la organización Id. de catálogo de la organización
Aplicaciones enviadas a la Tienda Teams Id. de tienda

Para obtener más información, consulte cómo buscar el identificador en función del identificador de manifiesto de la aplicación.

Las aplicaciones pueden usar la biblioteca TeamsJS para iniciar el cuadro de diálogo de instalación de la aplicación, lo que elimina la necesidad de generación manual de vínculos profundos. Este es un ejemplo de cómo desencadenar el cuadro de diálogo de instalación de la aplicación mediante TeamsJS dentro de la aplicación:

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

Para obtener más información sobre el appInstallDialog módulo, vea módulo appInstallDialog.

Los usuarios de la aplicación pueden examinar el contenido de Teams desde la pestaña mediante TeamsJS. Puede usar un vínculo profundo para examinar dentro de la aplicación 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. En pocos casos, la navegación también se puede realizar con TeamsJS y se recomienda usar funcionalidades con tipo de TeamsJS siempre que sea posible.

TeamsJS permite que las aplicaciones de Teams extendidas en Outlook y Microsoft 365 comprueben 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. 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 aplicación y la interfaz de usuario de la aplicación.

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

Puede configurar vínculos profundos para examinar dentro de la aplicación de las siguientes maneras:

Nota:

En Microsoft Windows, Teams no puede controlar vínculos profundos que superen los 2048 caracteres debido al INTERNET_MAX_URL_LENGTH límite de Windows ShellExecuteEx API. Al crear un vínculo profundo, asegúrese de que la ruta de acceso al cliente de Teams y otros metadatos caben dentro de este límite. Si el vínculo profundo contiene grandes cantidades de datos, incluya un identificador único en el vínculo que la aplicación puede usar para capturar los datos necesarios del servicio back-end.

Use el siguiente formato para un vínculo profundo en un bot, conector o tarjeta de extensión de mensaje:

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

  • 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, cuando se ejecutan 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 Microsoft Teams. fe4a8eba-2a31-4737-8e33-e5fae6fee194
entityId  Identificador 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 tareas 123
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 a subEntityId como page.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 tiene 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 compatible con contextType reuniones. chat
openInMeeting Use openInMeeting para controlar la experiencia del usuario cuando la pestaña de destino está asociada a una reunión. Si el usuario interactúa con el vínculo profundo en una experiencia de reunión en curso, Teams abre la aplicación en el panel del lado de la reunión. Establezca este valor false en para abrir siempre la aplicación en la pestaña de chat de reunión en lugar del panel lateral, independientemente del estado de la reunión. Teams omite cualquier valor distinto de false. false

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 el manifiesto de la aplicación.
  • 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.

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. A continuación se muestra un ejemplo de parámetros de consulta codificados por 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;

  • El vínculo profundo a una aplicación de Teams con URI codificado no se admite en Outlook.

Puede configurar vínculos profundos en la aplicación a través de TeamsJS para permitir que los usuarios de la aplicación examinen diferentes páginas dentro de la aplicación. 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, abra 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 de Teams se ejecuta dentro del host donde se dirige el vínculo profundo, la aplicación se abre directamente dentro del host. Sin embargo, si la aplicación de Teams se ejecuta en un host diferente desde el que se dirige el vínculo profundo, la aplicación se abre primero en el explorador.

La funcionalidad de páginas de la biblioteca TeamsJS proporciona compatibilidad para la navegación entre pestañas dentro de una aplicación. En concreto, el pages.currentApp espacio de nombres ofrece una función navigateTo(NavigateWithinAppParams) para permitir la navegación a una pestaña específica dentro de la aplicación actual y una función navigateToDefaultPage() para navegar a la primera pestaña definida en el manifiesto de la aplicación. En el código siguiente se muestra cómo navegar a una pestaña específica y predeterminada:

En el código siguiente se muestra cómo navegar a una pestaña específica:

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

Nota:

La navegación de la aplicación de pestaña solo se admite en el nuevo cliente de Teams.

Configuración de la navegación del botón Atrás

Cuando una aplicación tiene varias pestañas, un usuario puede usar el botón Atrás de la aplicación host de Microsoft 365 para retroceder en el historial de navegación. Sin embargo, el historial no incluye las acciones que un usuario realiza dentro de una pestaña. Si desea mejorar la experiencia del botón Atrás, puede mantener su propia pila de navegación interna y configurar un controlador personalizado para las selecciones de botón atrás. Esto se puede realizar a través de la registerBackButtonHandler() función en el espacio de pages.backStack nombres.

Después de registrar el controlador, le ayuda a abordar la solicitud de navegación antes de que el sistema tome medidas. Si el controlador puede administrar la solicitud, debe devolverse true para que el sistema sepa que no es necesario realizar ninguna acción adicional. Si la pila interna está vacía, debe devolverse false para que el sistema pueda llamar a la navigateBack() función en su lugar y realizar la acción adecuada.

Devolver el foco a la aplicación host

Una vez que el usuario comienza a usar elementos dentro de una pestaña, de forma predeterminada, el foco permanece con los elementos del iFrame hasta que el usuario selecciona fuera de ella. Si el iFrame forma parte del usuario que navega con métodos abreviados de teclado (la tecla Tab o la tecla F6), puede centrarse en la aplicación host. Puede centrarse en la aplicación host mediante la pages.returnFocus() función . La returnFocus() función acepta un valor booleano que indica la dirección para avanzar el foco dentro de la aplicación host; true para adelante y false hacia atrás. Por lo general, forward resalta la barra de búsqueda y hacia atrás resalta la barra de la aplicación.

Puede permitir que los usuarios de la aplicación naveguen a un chat personal con la aplicación configurando el vínculo profundo manualmente con el siguiente formato:

https://teams.microsoft.com/l/entity/<appId>/conversations?tenantId=<tenantId>, donde appId es el identificador de la aplicación. Para obtener información sobre los diferentes identificadores de aplicación usados, consulte Id. de aplicación para diferentes tipos de aplicaciones.

Puede compartir vínculos profundos a entidades en aplicaciones de Teams para navegar al contenido y la información de la aplicación de pestaña. Por ejemplo, si la aplicación de pestaña contiene una lista de tareas, los miembros del equipo pueden crear y compartir vínculos a tareas individuales. Cuando el usuario de la aplicación selecciona el vínculo, se desplaza a la pestaña que se centra en el elemento específico.

Agregue una acción de vínculo de copia a cada elemento de la manera que mejor se adapte a la 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> })

Debe reemplazar los parámetros siguientes 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().

Nota:

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

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 TextBlock mensaje 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: parámetro opcional con una dirección URL de reserva que se usará si el cliente no admite la representación de la pestaña o https://tasklist.example.com/123https://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, como 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 de diálogo 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í Para aplicaciones de terceros, use la aplicación id desde el manifiesto o desde el APP_ID Centro de administración de Teams, ya que son idénticas. Para aplicaciones personalizadas o aplicaciones personalizadas creadas para su organización (aplicaciones LOB), use desde el APP_ID Centro de administración de Teams o use el Graph API. La matriz validDomains del manifiesto de APP_ID debe contener el dominio para url si url está presente en la dirección URL de vínculo profundo. El identificador de aplicación ya se conoce cuando se invoca un cuadro de diálogo 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. Debe BOT_APP_ID especificarse como bot en el manifiesto de la aplicación, que 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.

Generación de un vínculo profundo para compartir contenido para realizar una fase en las reuniones

También puede generar un vínculo profundo para compartir la aplicación para realizar la fase e iniciar o unirse a una reunión.

Para obtener vínculos profundos para compartir contenido para realizar la fase, consulte vínculo profundo para compartir contenido en la fase de las reuniones.

Nota:

  • La generación de un vínculo profundo para compartir contenido para la fase de las reuniones solo está disponible en la versión preliminar del desarrollador público.
  • El vínculo profundo para compartir contenido para la fase de reunión solo se admite en el cliente de escritorio de Teams.

Puede generar un vínculo profundo al panel lateral de la reunión en una reunión. Use el siguiente formato para un vínculo profundo al panel lateral de la reunión:

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

Ejemplo:

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

De forma predeterminada, se abre un vínculo profundo en un panel lateral de la reunión. Para abrir un vínculo profundo directamente en una aplicación en lugar del panel lateral de la reunión, agregue openInMeeting=false el formato de vínculo profundo:

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

Para obtener más información, consulte vínculo profundo a una pestaña.

Un vínculo profundo no se abre en el panel lateral de la reunión en los siguientes escenarios:

  • No hay ninguna reunión activa.
  • La aplicación no tiene sidePanel el contexto declarado en el manifiesto de la aplicación.
  • openInMeeting se establece false en en el vínculo profundo.
  • El vínculo profundo se selecciona fuera de la ventana o componente de la reunión.
  • El vínculo profundo no coincide con la reunión actual, por ejemplo, si el vínculo profundo se crea a partir de otra reunión.

Puede invocar Stageview a través de un vínculo profundo desde la pestaña ajustando la dirección URL del vínculo profundo en la app.openLink(url) API. El vínculo profundo también se puede pasar a través de una acción OpenURL en la tarjeta. La openMode propiedad definida en la API determina la respuesta de Stageview. Para obtener más información, consulte invocación de Stageview a través de un vínculo profundo.

Ejemplo de código

Ejemplo de nombre Descripción .NET Node.js
Identificador de subentidad de consumo de vínculos profundos En este ejemplo se muestra cómo usar un vínculo profundo desde un chat de bot a una pestaña que consume el identificador de subentidad. También muestra vínculos profundos para:
- Navegar a una aplicación
- Navegar a un chat
- Abrir un cuadro de diálogo de perfil
- Abrir un cuadro de diálogo de programación		 View View
Navegación de la aplicación de tabulación En este ejemplo se muestra cómo navegar entre pestañas dentro de la aplicación. ND View