アプリケーションへのディープ リンク
Microsoft Teamsのディープ リンクは、ユーザーがアプリ内の特定のコンテンツやアクションに直接移動できる強力なツールです。 ディープ リンクは、タブを開く、アプリのインストール ダイアログを開始する、アプリ内で参照するなど、さまざまなアクションを実行するように構成されています。
注:
このトピックでは、Microsoft Teams JavaScript クライアント ライブラリ (TeamsJS) のバージョン 2.0.x を反映しています。 以前のバージョンを使用している場合は、 最新の TeamsJS と以前のバージョンの違いに関するガイダンスについては、TeamsJS ライブラリの概要を参照してください。
ディープ リンクのシナリオ
ディープ リンクを使用できるシナリオの一部を次に示します。
- アプリのインストール: ディープ リンクを使用すると、ユーザーがアプリの詳細を把握し、さまざまなスコープでインストールできます。
- ボットとコネクタ: ボット と コネクタ メッセージのディープ リンクを使用して、タブまたはその項目の変更についてユーザーに通知できます。
- 特定のページに移動する: ユーザーがアプリ内の特定のページに移動できるようにするディープ リンクを作成できます。
- カスタム アプリ: カスタム アプリのディープ リンクを生成できます。 ただし、Microsoft Teams ストア内のアプリがカスタム アプリ ID と同じアプリ ID を共有している場合、ディープ リンクはカスタム アプリではなく Teams ストアからアプリを開きます。
- モバイルの場合: アプリが Teams モバイル クライアントに対して承認された後に、モバイル用アプリへのディープ リンクを作成することもできます。 Teams iOS でディープ リンクを機能させるには、Apple App Store Connect チーム ID が必要です。 詳細については、「Apple App Store Connect チーム ID を更新する方法」を参照してください。
アプリのインストール ダイアログを開くディープ リンク
ディープ リンクを使用すると、アプリ ユーザーはアプリのインストール ダイアログを開いて、アプリに関する情報を知ったり、さまざまなコンテキストでインストールしたりできます。 アプリへのディープ リンクは、次の方法で作成できます。
アプリ ID を使用してディープ リンクを手動で構成する
ディープ リンクを使用すると、アプリ ID を使用して、Teams クライアントから直接アプリのインストール ダイアログを開くことができます。
https://teams.microsoft.com/l/app/<your-app-id>?tenantId=<tenantId>
<your-app-id> はアプリケーション ID (fxxxxxxx-0xxx-4xxx-8xxx-cxxxxxxxxxxx) です。
さまざまな種類のアプリのアプリ ID
次の表に、ディープ リンク用のさまざまな種類のアプリに使用されるさまざまな種類のアプリ ID を示します。
| アプリの種類 | アプリ ID の種類 |
|---|---|
| Teams でアップロードされたカスタム アプリ | マニフェスト ID |
| 組織カタログに送信されたアプリ | 組織カタログ ID |
| Teams ストアに送信されたアプリ | ストア ID |
詳細については、 アプリ マニフェスト ID に基づいて ID を検索する方法に関するページを参照してください。
TeamsJS を使用してディープ リンクを構成する
アプリでは、Microsoft Teams JavaScript クライアント ライブラリ (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を参照してください。
アプリ内で参照するためのディープ リンク
アプリ ユーザーは、TeamsJS を使用して、タブから Teams のコンテンツを参照できます。 タブが Teams の他のコンテンツ (チャネル、メッセージ、別のタブなど) とユーザーを接続する必要がある場合、またはスケジュール ダイアログを開く必要がある場合は、アプリ内でディープ リンクを使用して参照できます。 いくつかの例では、TeamsJS を使用してナビゲーションを実行することもできます。可能な限り、TeamsJS の型指定された機能を使用することをお勧めします。
アプリ内で参照するディープ リンクは、次の方法で構成できます。
アプリ内で手動で参照するようにディープ リンクを構成する
個人用タブには personal スコープがあり、チャネル タブとグループ タブには team または group スコープが使用されます。 構成可能なタブにのみコンテキスト オブジェクトに関連付けられている channel プロパティがあるため、2 つのタブの種類の構文は若干異なります。 タブ スコープの詳細については、「 アプリ マニフェスト」を参照してください。
ボット、コネクタ、またはメッセージ拡張機能のカードにディープ リンクを作成するには、次の形式を使用します。
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 |
重要
すべてのクエリ パラメーターと空白が適切に 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 を使用してアプリ内のディープ リンクを構成して、ユーザーがアプリ内のさまざまなページを閲覧できるようにします。 Microsoft 365 Office 全体に拡張された Teams アプリのナビゲーション動作は、次の 2 つの要因に依存します。
- ディープ リンクが指すターゲット。
- Teams アプリが実行されているホスト。
Teams アプリがディープ リンクの対象となるホスト内で実行されている場合、アプリはホスト内で直接開きます。 ただし、Teams アプリがディープ リンクをターゲットとする別のホストで実行されている場合、アプリは最初にブラウザーで開きます。
TeamsJS でのディープ リンクのサポート
TeamsJS を使用すると、Outlook と Microsoft 365 の間で拡張された Teams アプリは、ホストが使用しようとしている機能をサポートしている場合にチェックできます。 ホストによる機能のサポートを確認するには、API の名前空間に関連付けられている isSupported() 関数を使用できます。 TeamsJS は、名前空間を使用して API を機能に整理します。 たとえば、pages名前空間で API を使用する前に、pages.isSupported()から返されたブール値をチェックし、アプリとアプリの UI のコンテキスト内で適切なアクションを実行できます。 詳細については、「 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 機能の詳細については、他のナビゲーション オプションについては、 pages.navigateToApp() と pages 名前空間に関する ページ を参照してください。
- app.openLink() を使用してディープ リンクを直接開くには、 app.openLink() 関数に関するページを参照してください。
タブ間を移動するためのディープ リンクの構成
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) を受け取ります。前方と後方のfalsetrue。 一般に、前方には検索バーが強調表示され、後方にはアプリ バーが強調表示されます。
アプリケーションとのチャットへのディープ リンク
ディープ リンクを手動で構成することで、アプリ ユーザーがアプリケーションとの個人用チャットを参照できるようにします。
https://teams.microsoft.com/l/entity/<appId>/conversations?tenantId=<tenantId>
appId はアプリケーション ID です。 詳細については、「 さまざまな種類のアプリのアプリ ID」を参照してください。
タブのディープ リンクを共有する
Teams アプリ内のエンティティへのディープ リンクを共有して、タブ アプリ内のコンテンツと情報に移動できます。 たとえば、タブ アプリにタスク リストが含まれている場合、チーム メンバーは個々のタスクへのリンクを作成して共有できます。 アプリ ユーザーがリンクを選択すると、特定の項目に焦点を当てたタブに移動します。
UI に最適な方法で、各項目に コピー リンク アクションを追加します。 ユーザーがこのアクションを実行すると、 pages.shareDeepLink() を呼び出して、ユーザーがクリップボードにコピーできるリンクを含むダイアログを表示します。 この呼び出しを行うときは、アイテムの ID を渡します。 リンクに従うと コンテキスト に戻り、タブが再読み込みされます。
pages.shareDeepLink({ subPageId: <subPageId>, subPageLabel: <subPageLabel>, subPageWebUrl: <subPageWebUrl> })
次のパラメーターを適切な情報に置き換える必要があります。
| パラメーター名 | 説明 |
|---|---|
subPageId |
ディープ リンクするページ内のアイテムの一意識別子。 |
subPageLabel |
ディープ リンクの表示に使用するアイテムのラベル。 |
subPageWebUrl |
クライアントがページをレンダリングできない場合に使用するフォールバック URL。 |
詳細については、「 pages.shareDeepLink()」を参照してください。
注:
- このディープ リンクは、[ リンクをタブにコピー ] メニュー項目によって提供されるリンクとは異なります。このリンクは、このタブを指すディープ リンクのみを生成します。
-
shareDeepLinkは Teams モバイル プラットフォームでは機能しません。
SharePoint Framework タブのディープ リンク
SharePoint Framework (SPFx) タブのディープ リンクを使用すると、ユーザーは SharePoint サイトまたは Teams アプリ内の特定のタブに直接移動できます。 これにより、関連するコンテンツと機能にすばやくアクセスできるため、ユーザー エクスペリエンスが向上します。
ボット、コネクタ、またはメッセージ拡張機能のカードでは、次のディープ リンク形式を使用できます。
https://teams.microsoft.com/l/entity/<appId>/<EntityId>?webUrl=<entityWebUrl>/<EntityName>.
注:
- ボットがディープ リンクを含む
TextBlockメッセージを送信すると、ユーザーがリンクを選択すると新しいブラウザー タブが開きます。 これは、Linuxで 実行されている Chrome および Microsoft Teams デスクトップ アプリで発生します。 - ボットが
Action.OpenUrlで同じディープ リンク URL を送信する場合、ユーザーがリンクを選択すると、現在のブラウザーで [Teams] タブが開きます。 新しいブラウザー タブは開きません。
クエリ パラメーター
| 値 | 説明 |
|---|---|
APP_ID |
マニフェスト ID。 例: fxxxxxxx-0xxx-4xxx-8xxx-cxxxxxxxxxxx |
entityID |
タブの構成時に指定した項目 ID。 例: tasklist123 |
entityWebUrl |
クライアントがタブのレンダリングをサポートしていない場合に使用するフォールバック URL。 例: https://tasklist.example.com/123 または https://tasklist.example.com/list123/task456 |
entityName |
ディープ リンクを表示するときに使用するタブ内の項目のラベル。 例: Task List 123 または Task 456 |
ダイアログを開くディープ リンク
ダイアログ ディープ リンクは、 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_IDhttps://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>.
既定では、会議のサイド パネルにディープ リンクが開きます。 会議のサイド パネルではなくアプリで直接ディープ リンクを開くには、次のディープ リンク形式で示すように 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 を呼び出す」を参照してください。
ベスト プラクティス
- ディープ リンクは、タブがエンティティ ID を持つライブラリ v0.4 以降を使用して構成されている場合にのみ正しく機能します。 エンティティ ID を持たないタブへのディープ リンクは引き続きタブに移動しますが、タブに sub'EntityId を指定することはできません。
- Microsoft Windows では、Windows ShellExecuteEx API の
INTERNET_MAX_URL_LENGTH制限のため、Teams は 2048 文字を超えるディープ リンクを処理できません。 - ディープ リンクを作成するときは、Teams クライアントとその他のメタデータへのパスがこの制限内に収まるようにします。
- ディープ リンクに大きなデータが含まれている場合は、アプリがバックエンド サービスから必要なデータをフェッチするために使用できる一意の識別子をリンクに含めます。
コード サンプル
| サンプルの名前 | 説明 | .NET | Node.js |
|---|---|---|---|
ディープ リンクの使用 subEntityId |
このサンプルでは、ボット チャットからタブへのディープ リンクを使用して、 subEntityIdを使用する方法を示します。 また、次のディープ リンクも表示されます。- アプリへの移動 - チャットへの移動 - プロファイル ダイアログを開く - スケジュール 設定ダイアログを開く |
表示 | 表示 |
| タブ アプリのナビゲーション | このサンプルでは、アプリ内のタブ間を移動する方法を示します。 | 該当なし | 表示 |
Platform Docs