アプリケーションへのディープ リンク
ディープ リンクは、タブを開く、アプリのインストール ダイアログを開始する、アプリ内で参照するなど、さまざまなアクションを実行するように構成されています。 ボットとコネクタ メッセージのディープ リンクを使用して、タブまたはその項目の変更についてユーザーに通知します。
カスタム アプリのディープ リンクを作成できます。 ただし、Microsoft Teams ストア内のアプリがカスタム アプリ ID と同じアプリ ID を共有している場合、ディープ リンクはカスタム アプリではなく Teams ストアからアプリを開きます。 アプリが Teams モバイル プラットフォームに対して承認された後に、モバイル用アプリへのディープ リンクを作成することもできます。 Teams iOS でディープ リンクを機能させるには、Apple App Store Connect チーム ID が必要です。 詳細については、「Apple App Store Connect チーム ID を更新する方法」を参照してください。
ディープ リンクを使用すると、ユーザーはアプリの詳細を把握し、さまざまなスコープでインストールできます。 アプリ ユーザーがアプリ内の特定のページに移動するためのディープ リンクを作成することもできます。 この記事では、ディープ リンクを作成する方法について説明します。
- アプリケーションのインストール ダイアログを開くには
- アプリ内で参照するには
- アプリケーションとのチャットに移動するには
- タブのディープ リンクを共有するには
- ダイアログを開くには (TeamsJS v1.x でタスク モジュールと呼ばれます)
- Stageview を呼び出すには
注:
このトピックでは、Microsoft Teams JavaScript クライアント ライブラリ (TeamsJS) のバージョン 2.0.x を反映しています。 以前のバージョンを使用している場合は、 最新の TeamsJS と以前のバージョンの違いに関するガイダンスについては、TeamsJS ライブラリの概要を参照してください。
アプリケーションのインストール ダイアログを開くディープ リンク
ディープ リンクを使用すると、アプリ ユーザーはアプリケーションのインストール ダイアログを開いて、アプリに関する詳細情報を知ったり、さまざまなコンテキストでインストールしたりできます。 アプリケーションへのディープ リンクは、次の方法で作成できます。
アプリ ID を使用してディープ リンクを手動で構成する
アプリ ID を使用して Teams クライアントからアプリのインストール ダイアログを開くために必要なディープ リンク形式を次に示します。
https://teams.microsoft.com/l/app/<your-app-id>?tenantId=<tenantId>
ここで、 <your-app-id>
はアプリケーション ID (f46ad259-0fe5-4f12-872d-c737b174bcb4) です。
さまざまな種類のアプリのアプリ ID
次の表に、ディープ リンク用のさまざまな種類のアプリに使用されるさまざまな種類のアプリ ID を示します。
アプリの種類 | アプリ ID の種類 |
---|---|
Teams でアップロードされたカスタム アプリ | マニフェスト ID |
組織カタログに送信されたアプリ | 組織カタログ ID |
Teams ストアに送信されたアプリ | ストア ID |
詳細については、 アプリ マニフェスト ID に基づいて ID を検索する方法に関するページを参照してください。
アプリケーションでは 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 モジュール」を参照してください。
アプリ内で参照するためのディープ リンク
アプリ ユーザーは、TeamsJS を使用して、タブから Teams のコンテンツを参照できます。 チャネル、メッセージ、別のタブなど、Teams 内の他のコンテンツとユーザーを接続する必要がある場合、またはスケジュール ダイアログを開く場合は、アプリ内でディープ リンクを使用して参照できます。 場合によっては、TeamsJS を使用してナビゲーションを実行することもできます。可能な限り、TeamsJS の型指定された機能を使用することをお勧めします。
TeamsJS を使用すると、Outlook と Microsoft 365 の間で拡張された Teams アプリは、ホストが使用しようとしている機能をサポートしている場合にチェックできます。 ホストによる機能のサポートを確認するには、API の名前空間に関連付けられている isSupported()
関数を使用できます。 TeamsJS は、名前空間を使用して API を機能に整理します。 たとえば、pages
名前空間で API を使用する前に、pages.isSupported()
から返されたブール値をチェックし、アプリとアプリの UI のコンテキスト内で適切なアクションを実行できます。
TeamsJS の機能と API の詳細については、「TeamsJS ライブラリでのタブとその他のホストされたエクスペリエンスの構築」を参照してください。
アプリ内で参照するディープ リンクは、次の方法で構成できます。
アプリ内で手動で参照するようにディープ リンクを構成する
注:
Microsoft Windows では、Windows ShellExecuteEx API の INTERNET_MAX_URL_LENGTH
制限のため、Teams は 2048 文字を超えるディープ リンクを処理できません。 ディープ リンクを作成するときは、Teams クライアントとその他のメタデータへのパスがこの制限内に収まるようにします。 ディープ リンクに大量のデータが含まれている場合は、アプリがバックエンド サービスから必要なデータをフェッチするために使用できる一意の識別子をリンクに含めます。
ボット、コネクタ、またはメッセージ拡張機能カードのディープ リンクには、次の形式を使用します。
https://teams.microsoft.com/l/entity/<appId>/<entityId>?tenantId=<tenantId>&webUrl=<entityWebUrl>&label=<entityLabel>&context=<context>&openInMeeting=false
ボットがディープ リンクを使用して
TextBlock
を含むメッセージを送信する場合、ユーザーがリンクを選択すると、新しいブラウザー タブが開きます。 これは、Linux で実行されている Chrome と Teams デスクトップ アプリで発生します。ボットが同じディープ リンク URL を
Action.OpenUrl
に送信する場合、ユーザーがリンクを選択すると、現在のブラウザー タブで [Teams] タブが開きます。
クエリ パラメーターは次のとおりです。
パラメーター名 | 説明 | 例 |
---|---|---|
appId |
管理センターからの ID Microsoft Teams。 | fe4a8eba-2a31-4737-8e33-e5fae6fee194 |
entityId |
タブを構成するときに指定した タブの ID。ディープ リンク用の URL を生成する場合は、引き続き URL のパラメーター名としてエンティティ ID を使用します。 タブを構成する場合、コンテキスト オブジェクトはpage.id としてentityId を参照します。 |
タスクリスト 123 |
entityWebUrl または subEntityWebUrl |
クライアントがタブのレンダリングをサポートしていない場合に使用するフォールバック URL を含むオプションのフィールド。 |
https://tasklist.example.com/123 または https://tasklist.example.com/list123/task456 |
entityLabel または subEntityLabel |
ディープ リンクを表示するときに使用するタブ内の項目のラベル。 | タスク リスト 123 またはタスク 456 |
context.subEntityId |
タブ内の項目の ID。ディープ リンク用の URL を生成する場合は、引き続き subEntityId を URL のパラメーター名として使用します。 タブを構成する場合、コンテキスト オブジェクトはpage.subPageId としてsubEntityId を参照します。 |
タスク 456 |
context.channelId |
タブコンテキストから使用可能な Microsoft Teams チャネル ID。 このプロパティは、 チームのスコープを持つ構成可能なタブでのみ使用できます。 個人用スコープを持つ静的タブでは使用できません。 | 19:cbe3683f25094106b826c9cada3afbe0@thread.skype |
context.chatId |
グループ チャットと会議チャットのタブ コンテキスト から使用できるチャット ID。 | 17:b42de192376346a7906a7dd5cb84b673@thread.v2 |
context.contextType |
チャットは、会議でサポートされている唯一の contextType です。 |
チャット |
openInMeeting |
openInMeeting を使用して、ターゲット タブが会議に関連付けられている場合のユーザー エクスペリエンスを制御します。 ユーザーが進行中の会議エクスペリエンスのディープ リンクと対話する場合、Teams は会議内のサイド パネルでアプリを開きます。 この値を false に設定すると、会議の状態に関係なく、サイド パネルではなく会議チャット タブでアプリが常に開きます。 Teams では、 false 以外の値は無視されます。 |
false |
注:
- 個人用タブには
personal
スコープがあり、チャネル タブとグループ タブにはteam
またはgroup
スコープが使用されます。 構成可能なタブだけがコンテキスト オブジェクトに関連付けられているchannel
プロパティを持つため、2 つのタブの種類の構文はわずかに異なります。 タブ スコープの詳細については、 アプリ マニフェストに関するページを参照してください。 - ディープ リンクは、タブがエンティティ ID を持つライブラリ v0.4 以降を使用して構成されている場合にのみ正しく機能します。 エンティティ ID のないタブへのディープ リンクは引き続きタブに移動しますが、サブエンティティ ID をタブに指定することはできません。
例:
静的 (個人用) タブ自体へのリンク:
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;
エンコードされた URI を持つ Teams アプリケーションへのディープ リンクは、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() とその他のナビゲーション オプションのための pages 名前空間」を参照してください。 必要に応じて、 app.openLink() 関数を使用してディープ リンクを直接開きます。
Microsoft 365 Office 全体に拡張された Teams アプリのナビゲーション動作は、次の 2 つの要因に依存します。
- ディープ リンクが指すターゲット。
- Teams アプリが実行されているホスト。
Teams アプリがディープ リンクの対象となるホスト内で実行されている場合、アプリはホスト内で直接開きます。 ただし、Teams アプリがディープ リンクをターゲットとする別のホストで実行されている場合、アプリは最初にブラウザーで開きます。
タブ間を移動するためのディープ リンクの構成
TeamsJS ライブラリの ページ 機能は、アプリ内のタブ間のナビゲーションをサポートします。 具体的には、 pages.currentApp
名前空間には、現在のアプリ内の特定のタブへのナビゲーションを許可する関数 navigateTo(NavigateWithinAppParams)
と、アプリのマニフェストで定義されている最初のタブに移動するための関数 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 ホスト アプリの [戻る] ボタンを使用して、ナビゲーション履歴を後方に移動できます。 ただし、履歴には、ユーザーがタブ内で実行するアクションは含まれません。戻るボタンのエクスペリエンスを強化する場合は、独自の内部ナビゲーション スタックを維持し、戻るボタンの選択用にカスタム ハンドラーを構成できます。 これは、pages.backStack
名前空間の registerBackButtonHandler()
関数を使用して実行できます。
ハンドラーを登録すると、システムがアクションを実行する前にナビゲーション要求に対処するのに役立ちます。 ハンドラーが要求を管理できる場合は、それ以上のアクションが必要ないことをシステムが認識できるように、 true
を返す必要があります。 内部スタックが空の場合は、 false
を返して、代わりに navigateBack()
関数を呼び出して適切なアクションを実行できるようにします。
ホスト アプリにフォーカスを戻す
ユーザーがタブ内の要素の使用を開始した後、既定では、ユーザーが外部から選択するまで、フォーカスは iFrame の要素に残ります。 iFrame がキーボード ショートカット (Tab キーまたは F6 キー) を使用して移動するユーザーの一部である場合は、ホスト アプリに集中できます。
pages.returnFocus()
関数を使用して、ホスト アプリに集中できます。
returnFocus()
関数は、ホスト アプリ内でフォーカスを進める方向を示すブール型 (Boolean) を受け取ります。前方と後方のfalse
true
。 一般に、前方には検索バーが強調表示され、後方にはアプリ バーが強調表示されます。
アプリケーションとのチャットへのディープ リンク
次の形式を使用してディープ リンクを手動で構成することで、アプリ ユーザーがアプリケーションとの個人用チャットを参照できるようにします。
https://teams.microsoft.com/l/entity/<appId>/conversations?tenantId=<tenantId>
では、 appId
はアプリケーション ID です。 使用されるさまざまなアプリ ID については、「さまざまな 種類のアプリのアプリ ID」を参照してください。
タブのディープ リンクを共有する
Teams アプリ内のエンティティへのディープ リンクを共有して、タブ アプリ内のコンテンツと情報に移動できます。 たとえば、タブ アプリにタスク リストが含まれている場合、チーム メンバーは個々のタスクへのリンクを作成して共有できます。 アプリ ユーザーがリンクを選択すると、特定の項目に焦点を当てたタブに移動します。
UI に最適な方法で、各項目に コピー リンク アクションを追加します。 ユーザーがこのアクションを実行すると、 pages.shareDeepLink()
を呼び出して、ユーザーがクリップボードにコピーできるリンクを含むダイアログを表示します。 この呼び出しを行うときは、アイテムの ID を渡します。 リンクがフォローされ、タブが再読み込みされると、コンテキストに戻されます。
pages.shareDeepLink({ subPageId: <subPageId>, subPageLabel: <subPageLabel>, subPageWebUrl: <subPageWebUrl> })
次のパラメーターを適切な情報に置き換える必要があります。
-
subPageId
: ディープ リンク先であるページ内のアイテムの一意の ID。 -
subPageLabel
: ディープ リンクの表示に使用するアイテムのラベル。 -
subPageWebUrl
: クライアントがページをレンダリングできない場合に使用するフォールバック URL。
詳細については、「 pages.shareDeepLink()」を参照してください。
注:
- このディープ リンクは、[ リンクをタブにコピー ] メニュー項目によって提供されるリンクとは異なります。このリンクは、このタブを指すディープ リンクのみを生成します。
-
shareDeepLink
は Teams モバイル プラットフォームでは機能しません。
SharePoint Framework タブのディープ リンク
ボット、コネクタ、またはメッセージ拡張機能のカードでは、次のディープ リンク形式を使用できます: https://teams.microsoft.com/l/entity/<appId>/<EntityId>?webUrl=<entityWebUrl>/<EntityName>
。
注:
- ボットがディープ リンクを含む
TextBlock
メッセージを送信すると、ユーザーがリンクを選択すると新しいブラウザー タブが開きます。 これは、Linuxで 実行されている Chrome および Microsoft Teams デスクトップ アプリで発生します。 - ボットが
Action.OpenUrl
で同じディープ リンク URL を送信する場合、ユーザーがリンクを選択すると、現在のブラウザーで [Teams] タブが開きます。 新しいブラウザー タブは開きません。
クエリ パラメーターは次のとおりです。
appID
: マニフェスト ID、たとえばfe4a8eba-2a31-4737-8e33-e5fae6fee194
。entityID
: タブを構成するときに提供したアイテム ID。 たとえば、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
オブジェクトのシリアル化であり、他の 2 つの詳細 ( 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 オブジェクト」を参照してください。
ヒント
card
パラメーター (JavaScript encodeURI()
関数など) を使用する場合は、ディープ リンク URL をエンコードします。
次の表に、APP_ID
と BOT_APP_ID
に関する情報を示します:
値 | 型 | 必須 | 説明 |
---|---|---|---|
APP_ID |
string | はい | サード パーティ製アプリの場合は、マニフェストからアプリ id を使用するか、Teams 管理センターの APP_ID を使用します。 組織 (LOB アプリ) 用に構築されたカスタム アプリまたはカスタム アプリの場合は、Teams 管理センターのAPP_ID を使用するか、Graph APIを使用します。
APP_ID のマニフェストの validDomains 配列には、ディープ リンク URL にurl が存在する場合、url のドメインが含まれている必要があります。 アプリ ID は、ダイアログがタブまたはボットから呼び出されたときに既に認識されているため、 TaskInfo に含まれていない理由です。 |
BOT_APP_ID |
文字列 | いいえ |
completionBotId の値を指定した場合、オブジェクト result はメッセージ task/submit invoke を使用して指定したボットに送信されます。
BOT_APP_ID をアプリのマニフェストでボットとして指定する必要があり、ボットに送信することはできません。 |
注:
APP_ID
BOT_APP_ID
は、多くの場合、アプリにアプリの 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 を呼び出すためのディープ リンク
app.openLink(url)
API でディープ リンク URL をラップすることで、タブからディープ リンクを介して Stageview を呼び出すことができます。 ディープ リンクは、カード内の OpenURL
アクションを介して渡すこともできます。 API で定義されている openMode
プロパティによって、Stageview 応答が決まります。 詳細については、「 ディープ リンクを使用して Stageview を呼び出す」を参照してください。
コード サンプル
サンプルの名前 | 説明 | .NET | Node.js |
---|---|---|---|
ディープ リンクを使用するサブエンティティ ID | このサンプルでは、ボット チャットからサブエンティティ ID を使用するタブへのディープ リンクを使用する方法を示します。 また、次のディープ リンクも表示されます。 - アプリへの移動 - チャットへの移動 - プロファイル ダイアログを開く - スケジュール 設定ダイアログを開く |
表示 | 表示 |
タブ アプリのナビゲーション | このサンプルでは、アプリ内のタブ間を移動する方法を示します。 | 該当なし | 表示 |
Platform Docs