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

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

  • Статья

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

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

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

Примечание.

В этом разделе представлена версия 2.0.x клиентской библиотеки JavaScript (TeamsJS) Microsoft Teams. Если вы используете более раннюю версию, ознакомьтесь с обзором библиотеки 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.

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

Примечание.

В 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-адресе. При настройке вкладки объект контекста ссылается на 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

Примечание.

  • Личные вкладки имеют область 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, чтобы позволить пользователям приложения просматривать различные страницы в приложении. В следующем коде показано, как перейти к определенной сущности в приложении 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, зависит от двух факторов:

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

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

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

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.

В боте, соединителе или карточке расширения сообщения можно использовать следующий формат глубокой ссылки: 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 через прямую ссылку из вкладки, завернув URL-адрес глубокой app.openLink(url) ссылки в API. Прямую ссылку также можно передать через действие OpenURL в карточке. Свойство openMode , определенное в API, определяет ответ Stageview. Дополнительные сведения см. в статье Вызов Stageview через прямую ссылку.

Пример кода

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