Поделиться через

Прямая ссылка на приложение

  • Статья

Глубокие ссылки в Microsoft Teams — это мощные инструменты, позволяющие пользователям напрямую переходить к определенному содержимому или действиям в приложении. Глубокие ссылки настроены для выполнения различных действий, таких как открытие вкладки, запуск диалогового окна установки приложения или просмотр в приложении.

Примечание.

В этом разделе представлена версия 2.0.x клиентской библиотеки JavaScript (TeamsJS) Microsoft Teams. Если вы используете более раннюю версию, ознакомьтесь с обзором библиотеки TeamsJS , чтобы узнать о различиях между последней версией TeamsJS и более ранними версиями.

Ниже приведены некоторые сценарии, в которых можно использовать прямую ссылку:

  • Установка приложения. Вы можете использовать подробные ссылки, позволяющие пользователям узнать больше о приложении и установить его в разных областях.
  • Боты и соединители. Вы можете использовать глубокие ссылки в сообщениях ботов и соединителей , чтобы информировать пользователей об изменениях вкладки или ее элементов.
  • Перейдите на определенную страницу. Вы можете создать глубокие ссылки, позволяющие пользователям переходить на определенные страницы в приложении.
  • Пользовательское приложение. Вы можете создавать глубокие ссылки для пользовательского приложения. Однако если приложение в Microsoft Teams Store использует тот же идентификатор приложения, что и идентификатор пользовательского приложения, прямая ссылка открывает приложение из Магазина Teams, а не из пользовательского приложения.
  • Для мобильных устройств. Вы также можете создать прямую ссылку на приложение для мобильных устройств после утверждения приложения для мобильного клиента Teams. Чтобы прямая ссылка работала в Teams iOS, вам потребуется идентификатор команды Apple App Store Connect. Дополнительные сведения см. в статье Обновление Идентификатора команды Apple App Store Connect.

Подробные ссылки позволяют пользователям приложения открывать диалоговое окно установки приложения, чтобы узнать любую информацию о приложении или установить его в разных контекстах. Прямую ссылку на приложение можно создать следующими способами:

С помощью прямой ссылки можно открыть диалоговое окно установки приложения непосредственно из клиента Teams, используя идентификатор приложения.

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

<your-app-id> — это идентификатор приложения (fxxxx-0xxx-4xxx-8xxx-cxxxxxx

Идентификатор приложения для различных типов приложений

В следующей таблице перечислены различные типы идентификаторов приложений, используемых для разных типов приложений для глубоких ссылок.

Тип приложения Тип идентификатора приложения
Пользовательское приложение, отправленное в Teams Идентификатор манифеста
Приложения, отправленные в каталог организации Идентификатор каталога организации
Приложения, отправленные в Магазин Teams Идентификатор магазина

Дополнительные сведения см. в статье Поиск идентификатора на основе идентификатора манифеста приложения.

Приложения могут использовать клиентскую библиотеку JavaScript Microsoft Teams (TeamsJS) для запуска диалогового окна установки приложения, устраняя необходимость создания глубоких ссылок вручную. Ниже приведен пример запуска диалогового окна установки приложения с помощью TeamsJS в приложении.

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

Дополнительные сведения см. в статье appInstallDialog.

Пользователи приложений могут просматривать содержимое в Teams с вкладки с помощью TeamsJS. Вы можете использовать прямую ссылку для просмотра в приложении, если вкладка должна подключать пользователей к другому содержимому в Teams, например каналу, сообщению, другой вкладке или открыть диалоговое окно планирования. В некоторых случаях навигация также может осуществляться с помощью TeamsJS, и мы рекомендуем по возможности использовать типизированные возможности TeamsJS.

Вы можете настроить подробные ссылки для просмотра в приложении следующими способами:

Личные вкладки имеют область personal, а вкладки каналов и групп используют области team или group. Синтаксис двух типов вкладок немного отличается, так как только настраиваемая вкладка имеет свойство, channel связанное с объектом контекста. Дополнительные сведения об областях табуляции см. в разделе Манифест приложения.

Для создания глубокой ссылки в карта бота, соединителя или расширения сообщений используйте следующий формат:

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

  • Если бот отправляет сообщение, содержащее TextBlock с прямой ссылкой, то при выборе пользователем ссылки открывается новая вкладка браузера. Это происходит в Chrome и в классическом приложении Teams, когда они работают в Linux.

  • Если бот отправляет тот же URL-адрес прямой ссылки в Action.OpenUrl, то вкладка Teams откроется на текущей вкладке браузера, когда пользователь выбирает ссылку.

Параметры запроса

Имя параметра Описание
appId  Идентификатор из Центра администрирования Microsoft Teams.

Пример: fe4a8eba-2a31-4737-8e33-e5fae6fee194
entityId  Идентификатор вкладки, указанный при настройке вкладки. При создании URL-адреса для глубокой компоновки продолжайте использовать идентификатор сущности в качестве имени параметра в URL-адресе. При настройке вкладки объект контекста ссылается на entityIdpage.id.

Пример: список задач 123
entityWebUrl или subEntityWebUrl  Необязательное поле с резервным URL-адресом для использования, если клиент не поддерживает отрисовку вкладки.

Пример: https://tasklist.example.com/123.
или
https://tasklist.example.com/list123/task456
entityLabel или subEntityLabel  Метка для элемента на вкладке, используемая при отображении прямой ссылки.

Пример: список задач 123 или задача 456
context.subEntityId  Идентификатор элемента на вкладке. При создании URL-адреса для глубокой компоновки продолжайте использовать subEntityId в качестве имени параметра в URL-адресе. При настройке вкладки объект контекста ссылается на subEntityIdpage.subPageId.

Пример: задача 456
context.channelId  Идентификатор канала Microsoft Teams, доступный в контексте вкладки. Это свойство доступно только на настраиваемых вкладках с область команды. Он недоступен на статических вкладках с личным область.

Пример: 19:cbe3683f25094106b826c9cada3afbe0@thread.skype
context.chatId  Идентификатор чата, доступный в контексте вкладки для группового и собраний чата.

Пример: 17:b42de192376346a7906a7dd5cb84b673@thread.v2
context.contextType  Чат поддерживается только contextType для собраний.

Пример: чат
openInMeeting Используйте openInMeeting для управления взаимодействием с пользователем, когда целевая вкладка связана с собранием. Если пользователь взаимодействует с глубокой ссылкой в ходе текущего собрания, Teams открывает приложение на боковой панели собрания. Задайте для этого значения значение , false чтобы всегда открывать приложение на вкладке чата собрания, а не на боковой панели, независимо от состояния собрания. Teams игнорирует любое значение, отличное от false.

Пример: false.

Важно!

  • Убедитесь, что все параметры запроса и пробелы правильно закодированы URI. Ниже приведен пример параметров запроса в кодировке 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;

  • Прямая ссылка на приложение Teams с закодированным URI не поддерживается в Outlook.

Вы можете настроить глубокие ссылки в приложении с помощью TeamsJS, чтобы разрешить пользователям просматривать различные страницы в приложении. Поведение навигации в приложении Teams, расширенном в Microsoft 365 Office, зависит от двух факторов:

  1. Целевой объект, на который указывает прямая ссылка.
  2. Узел, в котором запущено приложение Teams.

Если приложение Teams выполняется на узле, где нацелена прямая ссылка, приложение открывается непосредственно в узле. Однако если приложение Teams работает на узле, отличном от того, где используется прямая ссылка, приложение сначала откроется в браузере.


Поддержка глубоких ссылок в TeamsJS

TeamsJS позволяет приложениям Teams, расширенным в Outlook и Microsoft 365, проверка если узел поддерживает возможности, которые вы пытаетесь использовать. Чтобы проверить поддержку возможности для узла, можно использовать функцию isSupported(), связанную с пространством имен API. TeamsJS упорядочивает API-интерфейсы по возможностям с помощью пространств имен. Например, перед использованием API в pages пространстве имен можно проверка возвращаемое логическое значение из pages.isSupported() и выполнить соответствующее действие в контексте приложения и пользовательского интерфейса приложения. Дополнительные сведения см. в статье Создание вкладок и другие размещенные интерфейсы с библиотекой TeamsJS.

В следующем коде показано, как перейти к определенной сущности в приложении Teams:

Вы можете активировать навигацию со своей вкладки с помощью функции pages.navigateToApp(), как показано в следующем коде:

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

Возможности страниц библиотеки TeamsJS обеспечивают поддержку навигации между вкладками в приложении. В частности, пространство имен предлагает функциюnavigateTo(NavigateWithinAppParams), pages.currentApp разрешающая переход к определенной вкладке в текущем приложении, и функцию navigateToDefaultPage() для перехода к первой вкладке, определенной в манифесте приложения. В следующем коде показано, как перейти на определенную вкладку по умолчанию.

В следующем коде показано, как перейти на определенную вкладку:

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

Примечание.

Навигация по приложениям-вкладкам поддерживается только в новом клиенте Teams.

Настройка навигации по кнопке "Назад"

Если приложение имеет несколько вкладок, пользователь может использовать кнопку "Назад" ведущего приложения Microsoft 365, чтобы перейти к журналу навигации. Однако журнал не включает действия, выполняемые пользователем на вкладке. Если вы хотите улучшить работу кнопки "Назад", вы можете поддерживать собственный внутренний стек навигации и настроить настраиваемый обработчик для выбора кнопки "Назад". Это можно сделать с помощью registerBackButtonHandler() функции в pages.backStack пространстве имен.

После регистрации обработчика он помогает выполнить навигационный запрос до того, как система примет меры. Если обработчик может управлять запросом, он должен вернуться true , чтобы система знала, что никаких дальнейших действий не требуется. Если внутренний стек пуст, он должен вернуться false , чтобы система могла вместо этого вызвать функцию navigateBack() и выполнить соответствующее действие.

Возвращение фокуса в ведущее приложение

После того как пользователь начнет использовать элементы на вкладке, по умолчанию фокус остается с элементами iFrame, пока пользователь не выберет его. Если iFrame является частью пользователя, перемещающегося с помощью сочетаний клавиш (клавиша TAB или клавиша F6), вы можете сосредоточиться на ведущем приложении. Вы можете сосредоточиться на ведущем приложении с помощью pages.returnFocus() функции . Функция returnFocus() принимает логическое значение, указывающее направление для продвижения фокуса в ведущем приложении; true для вперед и false для обратного. Как правило, вперед выделяет панель поиска, а назад — панель приложения.

Вы можете разрешить пользователям приложения переходить в личный чат с приложением, настроив прямую ссылку вручную.

https://teams.microsoft.com/l/entity/<appId>/conversations?tenantId=<tenantId>

appId — это идентификатор приложения. Дополнительные сведения см. в разделе Идентификатор приложения для различных типов приложений.

Вы можете поделиться глубокими ссылками на сущности в приложениях Teams, чтобы перейти к содержимому и сведениям в приложении вкладки. Например, если приложение вкладки содержит список задач, участники команды могут создавать ссылки на отдельные задачи и обмениваться ими. Когда пользователь приложения выбирает ссылку, он переходит на вкладку, которая фокусируется на конкретном элементе.

Добавьте действие копирования ссылки на каждый элемент любым способом, наилучшим образом подходящим для пользовательского интерфейса. Когда пользователь выполняет это действие, вызовите pages.shareDeepLink() диалоговое окно, содержащее ссылку, которую пользователь может скопировать в буфер обмена. При выполнении этого вызова передайте идентификатор элемента. Вы получите его в контексте при переходе по ссылке и перезагрузке вкладки.

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

Следующие параметры необходимо заменить соответствующими сведениями:

Имя параметра Описание
subPageId Уникальный идентификатор элемента на странице, с которым выполняется прямая привязка.
subPageLabel Метка для элемента, используемого для отображения глубокой ссылки.
subPageWebUrl Резервный URL-адрес, используемый, если клиенту не удается отобразить страницу.

Дополнительные сведения см. в разделе pages.shareDeepLink().

Примечание.

  • Эта прямая ссылка отличается от ссылок, предоставляемых элементом меню Копировать ссылку на вкладку , что создает только прямую ссылку, указывающую на эту вкладку.
  • shareDeepLink не работает на мобильных платформах Teams.

Подробные ссылки на вкладки SharePoint Framework (SPFx) позволяют пользователям переходить непосредственно на определенные вкладки на сайте SharePoint или в приложении Teams. Это улучшает взаимодействие с пользователем, предоставляя быстрый доступ к соответствующему содержимому и функциям.

В карта бота, соединителя или расширения сообщений можно использовать следующий формат глубокой ссылки:

https://teams.microsoft.com/l/entity/<appId>/<EntityId>?webUrl=<entityWebUrl>/<EntityName>.

Примечание.

  • Когда бот отправляет TextBlock сообщение с глубокой ссылкой, откроется новая вкладка браузера, когда пользователи выбирают ссылку. Это происходит в настольных приложениях Chrome и Microsoft Teams, работающих в Linux.
  • Если бот отправляет тот же URL-адрес прямой ссылки в Action.OpenUrl, вкладка Teams открывается в текущем браузере, когда пользователь выбирает ссылку. Новая вкладка браузера не открывается.

Параметры запроса

Значение Описание
APP_ID Идентификатор манифеста.

Пример: fxxxxxxx-0xxx-4xxx-8xxx-cxxxxxxxxxxx.
entityID Идентификатор элемента, указанный при настройке вкладки.

Пример: tasklist123.
entityWebUrl Резервный URL-адрес, используемый, если клиент не поддерживает отрисовку вкладки.

Пример: https://tasklist.example.com/123 или https://tasklist.example.com/list123/task456
entityName Метка для элемента на вкладке, используемая при отображении прямой ссылки.

Пример: Task List 123 или Task 456

Прямая ссылка диалогового TaskInfo окна — это сериализация объекта с двумя другими сведениями: APP_ID и при необходимости 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

Типы данных и допустимые значения для <TaskInfo.url>, <TaskInfo.card>, <TaskInfo.height>, <TaskInfo.width> и <TaskInfo.title> см. в разделе об объекте TaskInfo.

Совет

Кодируйте URL-адрес прямой ссылки при использовании card параметра, например функции JavaScriptencodeURI().

В следующей таблице приведены сведения об APP_ID и BOT_APP_ID:

Значение Тип Обязательный Описание
APP_ID string Да — Для сторонних приложений используйте приложение id из манифеста APP_ID или из Центра администрирования Teams, так как они идентичны.

— Для пользовательских или пользовательских приложений, созданных для вашей организации (бизнес-приложений), используйте APP_ID из Центра администрирования Teams или API Graph.

— Массив validDomains в манифесте для APP_ID должен содержать домен для , url если url он присутствует в URL-адресе прямой ссылки. Идентификатор приложения уже известен при вызове диалогового окна из вкладки или бота, поэтому он не включен в TaskInfo.
BOT_APP_ID string Нет Если задано значение completionBotId, объект result отправляется с помощью сообщения task/submit invoke указанному боту. В BOT_APP_ID манифесте приложения необходимо указать в качестве бота, который нельзя отправить ни одному боту.

Примечание.

APP_ID и BOT_APP_ID может быть одинаковым во многих случаях, если в приложении есть рекомендуемый бот для использования в качестве идентификатора приложения и если он есть.

Прямая ссылка для предоставления общего доступа к содержимому на этапе собрания

Вы также можете создать прямую ссылку для предоставления общего доступа к приложению, чтобы выполнить этап и начать собрание или присоединиться к нему.

Подробные ссылки для предоставления общего доступа к содержимому на стадии см. в разделе Прямая ссылка для предоставления общего доступа к содержимому на этапе собраний.

Примечание.

  • Создание прямой ссылки для предоставления общего доступа к содержимому на этапе собраний доступно только в общедоступной предварительной версии для разработчиков.
  • Прямая ссылка для предоставления общего доступа к содержимому для этапа собрания поддерживается только в классическом клиенте Teams.

Вы можете создать прямую ссылку на боковую панель собрания в собрании.

Используйте следующий формат для прямой ссылки на боковую панель собрания:

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

По умолчанию прямая ссылка открывается на боковой панели собрания. Чтобы открыть прямую ссылку непосредственно в приложении, а не на боковой панели собрания, добавьте openInMeeting=false , как показано в следующем формате глубокой ссылки:

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

Дополнительные сведения см. в разделе Прямая ссылка на вкладку.

Прямая ссылка не открывается на боковой панели собрания в следующих сценариях:

  • Активное собрание отсутствует.
  • В манифесте приложения нет sidePanel объявленного контекста.
  • openInMeeting в прямой ссылке задано значение false .
  • Прямая ссылка выбирается за пределами окна собрания или компонента.
  • Прямая ссылка не соответствует текущему собранию, например, если прямая ссылка создана из другого собрания.

Вы можете вызвать Stageview через прямую ссылку с вкладки, завернув URL-адрес глубокой app.openLink(url) ссылки в API. Прямую ссылку также можно передать через действие OpenURL в карточке. Свойство openMode , определенное в API, определяет ответ Stageview. Дополнительные сведения см. в статье Вызов Stageview через прямую ссылку.

Лучшие методики

  • Прямые ссылки работают правильно, только если вкладка была настроена с помощью библиотеки версии 0.4 или более поздней, так как она имеет идентификатор сущности. Глубокие ссылки на вкладки без идентификаторов сущностей по-прежнему переходят на вкладку, но не могут предоставить sub'EntityId для вкладки.
  • В Microsoft Windows Teams не может обрабатывать глубокие ссылки, превышающие 2048 символов, из-за INTERNET_MAX_URL_LENGTH ограничения в API Windows ShellExecuteEx.
  • При создании прямой ссылки убедитесь, что путь к клиенту Teams и другим метаданным соответствует этому пределу.
  • Если прямая ссылка содержит большие данные, добавьте уникальный идентификатор в ссылку, которую приложение может использовать для получения необходимых данных из серверной службы.

Пример кода

Название примера Описание .NET Node.js TypeScript
Использование глубоких ссылок subEntityId В этом примере показано, как использовать прямую ссылку из чата бота на вкладку, используюющую subEntityId. Здесь также показаны подробные ссылки для:
— Переход к приложению
— Переход к чату
— Открытие диалогового окна профиля
— Открытие диалогового окна планирования		 Просмотр Просмотр Н/Д
Навигация по приложению tab В этом примере показано, как перемещаться между вкладками в приложении. Н/Д Просмотр Н/Д
Значения передачи прямой ссылки tab В этом примере показано, как использовать динамические глубокие ссылки для передачи значений как в вкладки, так и в автономные веб-приложения. Недоступно Недоступно Просмотр