次の方法で共有


アプリケーションへのディープ リンク

ディープ リンクは、タブを開く、アプリのインストール ダイアログを開始する、アプリ内で参照するなど、さまざまなアクションを実行するように構成されています。 ボットコネクタ メッセージのディープ リンクを使用して、タブまたはその項目の変更についてユーザーに通知します。

カスタム アプリのディープ リンクを作成できます。 ただし、Microsoft Teams ストア内のアプリがカスタム アプリ ID と同じアプリ ID を共有している場合、ディープ リンクはカスタム アプリではなく Teams ストアからアプリを開きます。 アプリが Teams モバイル プラットフォームに対して承認された後に、モバイル用アプリへのディープ リンクを作成することもできます。 Teams iOS でディープ リンクを機能させるには、Apple App Store Connect チーム ID が必要です。 詳細については、「Apple App Store Connect チーム ID を更新する方法」を参照してください。

ディープ リンクを使用すると、ユーザーはアプリの詳細を把握し、さまざまなスコープでインストールできます。 アプリ ユーザーがアプリ内の特定のページに移動するためのディープ リンクを作成することもできます。 この記事では、ディープ リンクを作成する方法について説明します。

注:

このトピックでは、Microsoft Teams JavaScript クライアント ライブラリ (TeamsJS) のバージョン 2.0.x を反映しています。 以前のバージョンを使用している場合は、 最新の TeamsJS と以前のバージョンの違いに関するガイダンスについては、TeamsJS ライブラリの概要を参照してください。

ディープ リンクを使用すると、アプリ ユーザーはアプリケーションのインストール ダイアログを開いて、アプリに関する詳細情報を知ったり、さまざまなコンテキストでインストールしたりできます。 アプリケーションへのディープ リンクは、次の方法で作成できます。

アプリ 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 を使用してアプリ内のディープ リンクを構成できます。 次のコードは、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 つの要因に依存します。

  1. ディープ リンクが指すターゲット。
  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) を受け取ります。前方と後方のfalsetrue。 一般に、前方には検索バーが強調表示され、後方にはアプリ バーが強調表示されます。

次の形式を使用してディープ リンクを手動で構成することで、アプリ ユーザーがアプリケーションとの個人用チャットを参照できるようにします。

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 モバイル プラットフォームでは機能しません。

ボット、コネクタ、またはメッセージ拡張機能のカードでは、次のディープ リンク形式を使用できます: 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 123Task 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_IDBOT_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 に設定されます。
  • ディープ リンクは、会議ウィンドウまたはコンポーネントの外部で選択されます。
  • ディープ リンクが現在の会議と一致しません。たとえば、ディープ リンクが別の会議から作成された場合などです。

app.openLink(url) API でディープ リンク URL をラップすることで、タブからディープ リンクを介して Stageview を呼び出すことができます。 ディープ リンクは、カード内の OpenURL アクションを介して渡すこともできます。 API で定義されている openMode プロパティによって、Stageview 応答が決まります。 詳細については、「 ディープ リンクを使用して Stageview を呼び出す」を参照してください。

コード サンプル

サンプルの名前 説明 .NET Node.js
ディープ リンクを使用するサブエンティティ ID このサンプルでは、ボット チャットからサブエンティティ ID を使用するタブへのディープ リンクを使用する方法を示します。 また、次のディープ リンクも表示されます。
- アプリへの移動
- チャットへの移動
- プロファイル ダイアログを開く
- スケジュール 設定ダイアログを開く
表示 表示
タブ アプリのナビゲーション このサンプルでは、アプリ内のタブ間を移動する方法を示します。 該当なし 表示