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

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

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

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

• Открытие диалогового окна установки приложения
• Просмотр в приложении
• Переход в чат с приложением
• Предоставление общего доступа к глубокой ссылке для вкладки
• Открытие диалогового окна (называется модулем задач в TeamsJS версии 1.x)
• Вызов Stageview

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

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

• Настройка прямой связи вручную с помощью идентификатора приложения
• Настройка прямой ссылки на вкладку с помощью TeamsJS

Настройка прямой связи вручную с помощью идентификатора приложения

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

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

Где <your-app-id> — идентификатор приложения (f46ad259-0fe5-4f12-872d-c737b174bcb4).

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

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

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

Приложения могут использовать библиотеку 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 */ }

// Open an app install dialog from your tab
microsoftTeams.executeDeepLink("https://teams.microsoft.com/l/app/<appId>");

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

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

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

Дополнительные сведения о возможностях и API-интерфейсах в TeamsJS см. в статье Создание вкладок и другие размещенные интерфейсы с библиотекой TeamsJS.

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

• Настройка прямой ссылки для просмотра в приложении вручную
• Настройка прямой ссылки на вкладку с помощью TeamsJS
• Настройка прямой связи для перехода между вкладками

Настройка прямой ссылки для просмотра в приложении вручную

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

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 откроется на текущей вкладке браузера, когда пользователь выбирает ссылку.

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

Примеры:

• Ссылка на статическую (личную) вкладку:

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

Настройка прямой ссылки на вкладку с помощью TeamsJS

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

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

microsoftTeams.executeDeepLink(/*deepLink*/);

Поведение навигации в приложении Teams, расширенном в Microsoft 365 Office, зависит от двух факторов:

1. Целевой объект, на который указывает прямая ссылка.
2. Узел, в котором запущено приложение 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*/});
}

if (pages.currentApp.isSupported()) {
    const navPromise = pages.currentApp.navigateToDefaultPage();
    navPromise.
        then((result) => {/*Successful navigation*/}).
        catch((error) => {/*Failed navigation*/});
}
else {/*Handle situation where capability isn't supported*/}

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

Если приложение имеет несколько вкладок, пользователь может использовать кнопку "Назад" ведущего приложения 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({ subPageId: <subPageId>, subPageLabel: <subPageLabel>, subPageWebUrl: <subPageWebUrl> })

microsoftTeams.shareDeepLink({ subEntityId: <subEntityId>, subEntityLabel: <subEntityLabel>, subEntityWebUrl: <subEntityWebUrl> })

Прямая ссылка на вкладки SharePoint Framework

Вы можете использовать следующий формат глубокой ссылки в боте, соединителе или расширении сообщения карта: https://teams.microsoft.com/l/entity/<appId>/<EntityId>?webUrl=<entityWebUrl>/<EntityName>.

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

• 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.

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

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

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

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

Прямая ссылка на боковую панель собрания

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

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 через прямую ссылку.

Пример кода