Прямая ссылка на приложение
Глубокие ссылки настроены для выполнения различных действий, таких как открытие вкладки, запуск диалогового окна установки приложения или просмотр в приложении. Используйте глубокие ссылки в сообщениях бота и соединителя , чтобы информировать пользователей об изменениях в вкладке или ее элементах.
Вы можете создать подробные ссылки для пользовательского приложения. Однако если приложение в Microsoft Teams Store использует тот же идентификатор приложения, что и идентификатор пользовательского приложения, прямая ссылка открывает приложение из Магазина Teams, а не из пользовательского приложения. Вы также можете создать прямую ссылку на приложение для мобильных устройств после утверждения приложения для мобильной платформы Teams. Чтобы прямая ссылка работала в Teams iOS, вам потребуется идентификатор команды Apple App Store Connect. Дополнительные сведения см. в статье Обновление Идентификатора команды Apple App Store Connect.
Подробные ссылки позволяют пользователям узнать больше о приложении и установить его в разных областях. Вы также можете создать глубокие ссылки, чтобы пользователи приложения могли переходить на определенные страницы приложения. Из этой статьи вы узнаете, как создать прямую ссылку:
- Открытие диалогового окна установки приложения
- Просмотр в приложении
- Переход в чат с приложением
- Предоставление общего доступа к глубокой ссылке для вкладки
- Открытие диалогового окна (называется модулем задач в TeamsJS версии 1.x)
- Вызов Stageview
Примечание.
В этом разделе представлена версия 2.0.x клиентской библиотеки JavaScript (TeamsJS) Microsoft Teams. Если вы используете более раннюю версию, ознакомьтесь с обзором библиотеки TeamsJS , чтобы узнать о различиях между последней версией TeamsJS и более ранними версиями.
Прямая ссылка для открытия диалогового окна установки приложения
Подробные ссылки позволяют пользователям приложения открывать диалоговое окно установки приложения, чтобы узнать больше о приложении или установить его в разных контекстах. Прямую ссылку на приложение можно создать следующими способами:
- Настройка прямой связи вручную с помощью идентификатора приложения
- Настройка прямой ссылки на вкладку с помощью TeamsJS
Настройка прямой связи вручную с помощью идентификатора приложения
Ниже приведен формат глубокой ссылки, необходимый для открытия диалогового окна установки приложения из клиента Teams с помощью идентификатора приложения:
https://teams.microsoft.com/l/app/<your-app-id>?tenantId=<tenantId>
Где <your-app-id>
— идентификатор приложения (f46ad259-0fe5-4f12-872d-c737b174bcb4).
Идентификатор приложения для различных типов приложений
В следующей таблице перечислены различные типы идентификаторов приложений, используемых для разных типов приложений для глубоких ссылок.
Тип приложения | Тип идентификатора приложения |
---|---|
Пользовательское приложение, отправленное в Teams | Идентификатор манифеста |
Приложения, отправленные в каталог организации | Идентификатор каталога организации |
Приложения, отправленные в Магазин 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
разделе модуль appInstallDialog.
Прямая ссылка для просмотра в приложении
Пользователи приложений могут просматривать содержимое в Teams с вашей вкладки с помощью TeamsJS. Вы можете использовать прямую ссылку для просмотра в приложении, если вкладка должна подключать пользователей к другому содержимому в Teams, например каналу, сообщению, другой вкладке или открыть диалоговое окно планирования. В некоторых случаях навигацию также можно выполнить с помощью TeamsJS, и мы рекомендуем использовать типизированные возможности TeamsJS везде, где это возможно.
TeamsJS позволяет приложениям Teams, расширенным в Outlook и Microsoft 365, проверка если узел поддерживает возможности, которые вы пытаетесь использовать. Чтобы проверить поддержку возможности для узла, можно использовать функцию isSupported()
, связанную с пространством имен API. TeamsJS упорядочивает API-интерфейсы по возможностям с помощью пространств имен. Например, перед использованием API в pages
пространстве имен можно проверка возвращаемое логическое значение из pages.isSupported()
и выполнить соответствующее действие в контексте приложения и пользовательского интерфейса приложения.
Дополнительные сведения о возможностях и API-интерфейсах в TeamsJS см. в статье Создание вкладок и другие размещенные интерфейсы с библиотекой TeamsJS.
Вы можете настроить подробные ссылки для просмотра в приложении следующими способами:
- Настройка прямой ссылки для просмотра в приложении вручную
- Настройка прямой ссылки на вкладку с помощью TeamsJS
- Настройка прямой связи для перехода между вкладками
Настройка прямой ссылки для просмотра в приложении вручную
Примечание.
В Microsoft Windows Teams не может обрабатывать глубокие ссылки, превышающие 2048 символов, из-за INTERNET_MAX_URL_LENGTH
ограничения в API Windows ShellExecuteEx. При создании прямой ссылки убедитесь, что путь к клиенту Teams и другим метаданным соответствует этому пределу. Если прямая ссылка содержит большие объемы данных, добавьте уникальный идентификатор в ссылку, которую приложение может использовать для получения необходимых данных из серверной службы.
Используйте следующий формат для глубокой ссылки в боте, соединителе или расширении сообщения карта:
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-адресе. При настройке вкладки объект контекста ссылается на entityId page.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-адресе. При настройке вкладки объект контекста ссылается на subEntityId page.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 |
Примечание.
- Личные вкладки имеют область
personal
, а вкладки каналов и групп используют областиteam
илиgroup
. Два типа вкладок имеют немного разный синтаксис, поскольку только настраиваемая вкладка имеет свойствоchannel
, связанное с ее объектом контекста. Дополнительные сведения о областях табуляции см. в манифесте приложения. - Глубокие ссылки работают правильно, только если вкладка была настроена с помощью библиотеки версии 0.4 или более поздней, так как она имеет идентификатор сущности. Глубокие ссылки на вкладки без идентификаторов сущностей по-прежнему переходят на вкладку, но не могут предоставить идентификатор подчиненности для вкладки.
Примеры:
Ссылка на статическую (личную) вкладку:
https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123&label=Task List 123
Ссылка на элемент задачи на статической (личной) вкладке:
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"}
Ссылка на настраиваемую вкладку:
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"}
Ссылка на элемент задачи на настраиваемой вкладке:
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"}
Ссылка на приложение вкладки, добавленное в чат собрания или групповой чат:
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"}
Важно!
Убедитесь, что все параметры запроса и пробелы правильно закодированы 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
Вы можете настроить глубокие ссылки в приложении с помощью 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 */ }
Дополнительные сведения об использовании возможностей страниц см. в pages.navigateToApp() и пространстве имен страниц для других параметров навигации. При необходимости откройте прямую ссылку с помощью функции app.openLink().
Поведение навигации в приложении Teams, расширенном в Microsoft 365 Office, зависит от двух факторов:
- Целевой объект, на который указывает прямая ссылка.
- Узел, в котором запущено приложение Teams.
Если приложение Teams выполняется на узле, где нацелена прямая ссылка, приложение открывается непосредственно в узле. Однако если приложение Teams работает на узле, отличном от того, где используется прямая ссылка, приложение сначала откроется в браузере.
Настройка прямой связи для перехода между вкладками
Возможности страниц библиотеки 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
Вы можете использовать следующий формат глубокой ссылки в боте, соединителе или расширении сообщения карта: https://teams.microsoft.com/l/entity/<appId>/<EntityId>?webUrl=<entityWebUrl>/<EntityName>
.
Примечание.
- Когда бот отправляет
TextBlock
сообщение с глубокой ссылкой, откроется новая вкладка браузера, когда пользователи выбирают ссылку. Это происходит в настольных приложениях Chrome и Microsoft Teams, работающих в Linux. - Если бот отправляет тот же URL-адрес прямой ссылки в
Action.OpenUrl
, вкладка Teams открывается в текущем браузере, когда пользователь выбирает ссылку. Новая вкладка браузера не открывается.
Параметры запроса:
appID
: ваш манифест, напримерfe4a8eba-2a31-4737-8e33-e5fae6fee194
.entityID
: идентификатор элемента, предоставленный при настройке вкладки. Например,tasklist123
.entityWebUrl
: необязательный параметр с резервным URL-адресом, используемый, если клиент не поддерживает отрисовку вкладки -https://tasklist.example.com/123
илиhttps://tasklist.example.com/list123/task456
.entityName
: метка для элемента на вкладке, используемая при отображении глубокой ссылки, напримерTask List 123
илиTask 456
.
Пример: https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123&TaskList
Прямая ссылка для открытия диалогового окна
Прямая ссылка диалогового 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>
.
Пример:
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"}
По умолчанию прямая ссылка открывается на боковой панели собрания. Чтобы открыть прямую ссылку непосредственно в приложении, а не на боковой панели собрания, добавьте openInMeeting=false
в формате прямой ссылки:
https://teams.microsoft.com/l/entity/<appId>/<entityId>?webUrl=<entityWebUrl>&label=<entityLabel>&context=<context>&openInMeeting=false
Дополнительные сведения см. в разделе Прямая ссылка на вкладку.
Прямая ссылка не открывается на боковой панели собрания в следующих сценариях:
- Активное собрание отсутствует.
- В манифесте приложения нет
sidePanel
объявленного контекста. -
openInMeeting
в прямой ссылке задано значениеfalse
. - Прямая ссылка выбирается за пределами окна собрания или компонента.
- Прямая ссылка не соответствует текущему собранию, например, если прямая ссылка создана из другого собрания.
Прямая ссылка для вызова Stageview
Вы можете вызвать Stageview через прямую ссылку из вкладки, завернув URL-адрес глубокой app.openLink(url)
ссылки в API. Прямую ссылку также можно передать через действие OpenURL
в карточке. Свойство openMode
, определенное в API, определяет ответ Stageview. Дополнительные сведения см. в статье Вызов Stageview через прямую ссылку.
Пример кода
Название примера | Описание | .NET | Node.js |
---|---|---|---|
Прямая ссылка, используюющая идентификатор subentity | В этом примере показано, как использовать прямую ссылку из чата бота на вкладку, используюющую идентификатор subentity. Здесь также показаны подробные ссылки для: — Переход к приложению — Переход к чату — Открытие диалогового окна профиля — Открытие диалогового окна планирования |
Просмотр | Просмотр |
Навигация по приложению tab | В этом примере показано, как перемещаться между вкладками в приложении. | Н/Д | Просмотр |
Platform Docs