Stageview でコンテンツを開く

[アーティクル]
04/08/2024

Microsoft Teams には、イマーシブキャンバスエクスペリエンスでアプリコンテンツを開く複数の方法が用意されています。 Stageview を使用すると、ユーザーは Teams 内でマルチタスクを採用できます。たとえば、サイドパネルに特定のチャットがある新しい Teams ウィンドウでアプリコンテンツを開くことができます。 Stageview は、次の目的で設計されています。

Teams 内でのマルチタスクを容易にする。
Teams マルチウィンドウでのコラボレーションをサポートします。
大規模なモーダルエクスペリエンスで特定のタスクに焦点を当てます。

注:

この記事は、Teams JavaScript クライアントライブラリ (TeamsJS) バージョン 2.0.x に基づいています。以前のバージョンを使用している場合は、最新バージョンと以前のバージョンの間のガイダンスについては、「 TeamsJS 」を参照してください。

Stageview の種類

Stageview には、UI と機能に基づいて、アプリコンテンツを開く 3 つの方法が用意されています。

Collaborative Stageview
Stageview Multi-window
Stageview モーダル

Collaborative Stageview

Collaborative Stageview を使用すると、Teams のアプリコンテンツのマルチタスクシナリオが可能になります。ユーザーは、サイドパネルの会話を伴いながら、新しい Teams ウィンドウ内でアプリコンテンツを開いて表示できます。このビューを使用すると、同じウィンドウ内から有意義なコンテンツエンゲージメントとコラボレーションが可能になります。

最適な使用方法: チャット、チャネル、チャネルタブなどの会話からコンテンツを開くとき。

スクリーンショットは、Teams の Collaborative Stageview を示しています。

Stageview Multi-window

Stageview Multi-window は、ユーザーがコラボレーションを必要とせずに Teams でマルチタスクを行う必要があるシナリオに役立ちます。このビューでは、ユーザーがタスクに集中できるサイドパネルの会話なしで、新しい Teams ウィンドウでアプリコンテンツが開きます。

最適な使用方法: 個人用アプリなどの非会議サーフェスからコンテンツを開くとき。

スクリーンショットは、Teams の Stageview マルチウィンドウを示しています。

Stageview Modal は、Teams メインウィンドウ内でアプリコンテンツをレンダリングするために使用される全画面表示 UI コンポーネントです。このビューを使用すると、ユーザーはアプリコンテンツと連携するための集中したエクスペリエンスが提供されます。 Stageview モーダルは、ユーザーがマルチタスクを行う必要のないリッチコンテンツを表示する場合に便利です。これは、Collaborative Stageview と Stageview Multi-window がサポートされていない場合の既定のビューです。

注:

Teams Web クライアントでは、Stageview モーダルのみがサポートされます。

スクリーンショットは、Teams の Stageview モーダルを示しています。

Stageview の呼び出し

次のいずれかの方法で Teams で Stageview を呼び出し、期待される Stageview 応答を構成できます。次の表に、各 Stageview 呼び出しメソッドの既定の応答と定義された応答を示します。

Invoke メソッド	既定の応答	定義された応答
アダプティブカード	Collaborative Stageview で開きます。	Collaborative Stageview または Stageview Multi-window がサポートされていない場合は、Stageview モーダルで開きます。
stageView API	Collaborative Stageview で開きます。	定義されたに基づいて、それぞれの Stageview で`openMode`開きます。
ディープリンク	Collaborative Stageview で開きます。	定義されたに基づいて、それぞれの Stageview で`openMode`開きます。

openMode プロパティ

openMode は StageViewParams インターフェイスのプロパティです。プロパティは openMode 省略可能であり、 stageView API またはディープリンクで定義して、Stageview 応答の種類を決定できます。プロパティには openMode 、次の 3 つの値があります。

popoutWithChat
popout
modal

次の表に、値の Stageview 応答を openMode 示します。

Input	応答
`openMode` として定義されます `popoutWithChat`	関連するサイドパネルの会話を含む Collaborative Stageview で開きます。
`openMode` として定義されます `popout`	サイドパネルの会話を行わずに Stageview マルチウィンドウで開きます。
`openMode` として定義されます `modal`	Stageview モーダルで開きます。

が定義されていない場合 openMode 、コンテンツは、関連付けられたサイドパネルの会話を含む Collaborative Stageview で既定で開きます。 Stageview 応答のフォールバック階層はですpopoutWithChatmodal>popout>。

注:

値では openMode 大文字と小文字が区別されます。正しい大文字と小文字を使用しない場合、コンテンツは Stageview Modal で開きます。
Teams Web クライアントなど、ポップアウトエクスペリエンスがサポートされていない場合、プロパティが定義されている場合 openMode でも、コンテンツは Stageview Modal で開きます。

アダプティブカードから Collaborative Stageview を呼び出す

アダプティブカードからのコラボレーションステージビューを使用すると、ユーザーは会話フローを続行しながらコンテンツに参加できます。 Teams Web クライアントのアダプティブカード JSON から Collaborative Stageview が呼び出されると、Stageview モーダルで開きます。

次の手順は、アダプティブカードから Collaborative Stageview がどのように呼び出されるかを理解するのに役立ちます。

ユーザーが Teams チャットでアプリコンテンツの URL を共有すると、ボットは呼び出し要求を composeExtensions/queryLink 受け取ります。ボットは、型を持つアダプティブカードを返します tab/tabInfoAction。
ユーザーがアダプティブカードのアクションボタンを選択すると、アダプティブカードのコンテンツに基づいて Collaborative Stageview が開きます。

グラフィカルな表現は、アダプティブカードからの Collaborative Stageview 応答を示しています。

次の JSON コードは、アダプティブカードにアクションボタンを作成する例です。

{
  "type": "Action.Submit",
  "title": "Open",
  "data": {
    "msteams": {
      "type": "invoke",
      "value": {
        "type": "tab/tabInfoAction",
        "tabInfo": {
          "contentUrl": "contentUrl",
          "websiteUrl": "websiteUrl",
          "name": "Sales Report",
          "entityId": "entityId"
        }
      }
    }
  }
}

アダプティブカードを作成するためのベストプラクティス

コンテンツ URL は、アプリマニフェストのの validDomains 一覧内にある必要があります。
呼び出し要求の種類はである composeExtensions/queryLink必要があります。
ワークフローは invoke ワークフローに appLinking 似ている必要があります。
は Action.Submit 、整合性を維持するように構成 Open する必要があります。

アプリが Teams モバイルクライアントで動作するように最適化されていない場合は、 Microsoft Teams ストアを介して配布されるアプリの Stageview が既定の Web ブラウザーで開きます。

stageView API から呼び出す

TeamsJS の stageView API を使用すると、定義されたに基づいて Stageview エクスペリエンスで Teams ウィンドウを openMode 開きます。プロパティが openMode 定義されていない場合、既定の応答は、関連付けられたサイドパネルの会話を含む Collaborative Stageview です。 Collaborative Stageview エクスペリエンスでは、サイドパネルの会話は、チャットやグループチャットなど、Stageview が呼び出されたスレッドと同じです。

注:

stageView API では、オプションの threadId パラメーターがサポートされています。これにより、特定の会話を Collaborative Stageview サイドパネルに移動できます。へのマッピング contentUrl を threadId 使用すると、コンテンツと共に会話を保持できます。

次のコードは、stageView API の各 openMode 値のサンプルです。

プロパティはopenMode、Collaborative Stageview で開く StageViewParams でと定義popoutWithChatされます。

  {
    "appId": "2c19df50-1c3c-11ea-9327-cd28e4b6f7ba",
    "contentUrl": "https://teams-test-tab.azurewebsites.net",
    "title": "Test tab ordering",
    "websiteUrl": "https://teams-test-tab.azurewebsites.net",
    "openMode": "popoutWithChat"
  }

プロパティはopenMode、StageViewParams でとしてpopout定義され、Stageview Multi-window で開きます。

  {
    "appId": "2c19df50-1c3c-11ea-9327-cd28e4b6f7ba",
    "contentUrl": "https://teams-test-tab.azurewebsites.net",
    "title": "Test tab ordering",
    "websiteUrl": "https://teams-test-tab.azurewebsites.net",
    "openMode": "popout"
  }

プロパティはopenMode、StageViewParams で Stageview モーダルで開くとしてmodal定義されます。

  {
    "appId": "2c19df50-1c3c-11ea-9327-cd28e4b6f7ba",
    "contentUrl": "https://teams-test-tab.azurewebsites.net",
    "title": "Test tab ordering",
    "websiteUrl": "https://teams-test-tab.azurewebsites.net",
    "openMode": "modal"
  }

が StageViewParams で定義されていない場合openMode、既定の応答は Collaborative Stageview です。

  {
    "appId": "2c19df50-1c3c-11ea-9327-cd28e4b6f7ba",
    "contentUrl": "https://teams-test-tab.azurewebsites.net",
    "title": "Test tab ordering",
    "websiteUrl": "https://teams-test-tab.azurewebsites.net"
  }

stageView API の詳細については、「 stageView モジュール」を参照してください。

stageView API パラメーター

プロパティ名	種類	文字数制限	必須	説明
entityId	String	64	省略可能	タブに表示されるエンティティの一意の ID。
appId	String	64	はい	開く Teams アプリの ID。
name	String	128	省略可能	チャネルインターフェイスのタブの表示名。値が指定されていない場合は、アプリ名が表示されます。
contentUrl	String	2048	はい	Teams に表示するエンティティ UI を指す https:// URL。
websiteUrl	String	2048	はい	ユーザーがブラウザーで表示を選択した場合にポイントする https:// URL。
Threadid	String	2048	省略可能	ID は、Collaborative Stageview サイドパネルに表示される会話を定義します。値が渡されない場合は、 `threadId` Collaborative Stageview が開かれたコンテキストから継承されます。注: 省略可能な `threadId` パラメーターは、チャットスレッドのみをサポートします。チャネル `threadId` が使用されている場合、サイドパネルは表示されません。
openMode	String	2048	省略可能	プロパティは、デスクトップクライアントのステージコンテンツの開いている動作を定義します。

ディープリンクから呼び出す

タブまたは個人用アプリからディープリンクを使用して Stageview を呼び出すには、 app.openLink(url) API でディープリンク URL をラップし、チャットコンテンツを openMode 開くプロパティを定義します。 openMode プロパティが指定されていない場合、ディープリンクからの Stageview 応答は既定で Collaborative Stageview になります。

サイドパネルに特定のチャットを表示するには、を threadId指定する必要があります。それ以外の場合は、サイドパネルの会話によって、ディープリンクが呼び出されるグループチャットまたはチャネルスレッドが表示されます。

注:

URL を貼り付ける前に、すべてのディープリンクをエンコードする必要があります。エンコードされていない URL はサポートされていません。
特定のコンテキストから Stageview を呼び出すときは、アプリがそのコンテキストで動作することを確認します。
threadId を追加するときは、渡された threadId のコンテキストでアプリが動作することを確認します。コンテキストが失敗した場合、エクスペリエンスは個人用コンテキストにフォールバックします。

構文

Collaborative Stageview のディープリンク構文:

https://teams.microsoft.com/l/stage/{appId}/0?context={"contentUrl":"contentUrl","websiteUrl":"websiteUrl","name":"Contoso","openMode":"popoutWithChat","threadId":"threadId"}

Collaborative Stageview のエンコードされたディープリンク構文:

https://teams.microsoft.com/l/stage/%7BappId%7D/0?context=%7B%22contentUrl%22:%22contentUrl%22,%22websiteUrl%22:%22websiteUrl%22,%22name%22:%22Contoso%22,%22openMode%22:%22popoutWithChat%22,%22threadId%22:%22threadId%22%7D

例

Collaborative Stageview を呼び出すためのエンコードされたディープリンク URL:

https://teams.microsoft.com/l/stage/6d621545-9c65-493c-b069-2b978b37c117/0?context=%7B%22appId%22%3A%226d621545-9c65-493c-b069-2b978b37c117%22%2C%22contentUrl%22%3A%22https%3A%2F%2F3282-115-111-228-84.ngrok-free.app%22%2C%22websiteUrl%22%3A%22https%3A%2F%2F3282-115-111-228-84.ngrok-free.app%22%2C%22name%22%3A%22DemoStageView%22%2C%22openMode%22%3A%22popoutWithChat%22%2C%22threadId%22%3A%2219%3Abe817b823c204cde8aa174ae146251dd%40thread.v2%22%7D

ディープリンククエリパラメーター

プロパティ名	種類	文字数制限	必須	説明
entityId	String	64	省略可能	タブに表示されるエンティティの一意の ID。
appId	String	64	はい	開く Teams アプリの ID。
name	String	128	省略可能	チャネルインターフェイスのタブの表示名。値が指定されていない場合は、アプリ名が表示されます。
contentUrl	String	2048	はい	Teams に表示するエンティティ UI を指す https:// URL。
websiteUrl	String	2048	はい	ユーザーがブラウザーで表示を選択した場合にポイントする https:// URL。
Threadid	String	2048	省略可能	ID は、Collaborative Stageview サイドパネルに表示される会話を定義します。値が渡されない場合は、 `threadId` Collaborative Stageview が開かれたコンテキストから継承されます。注: 省略可能な `threadId` パラメーターは、チャットスレッドのみをサポートします。チャネル `threadId` が使用されている場合、サイドパネルは表示されません。
openMode	String	2048	省略可能	プロパティは、デスクトップクライアントのステージコンテンツの開いている動作を定義します。

マルチタスクを容易にしたり、コラボレーションを強化したり、集中したユーザーエクスペリエンスを提供したりする場合でも、Stageview には要件に合ったモードがあります。

FAQ

どのステージビューを使用する必要がありますか?

Collaborative Stageview を使用すると、ユーザーは Teams ウィンドウでサイドパネルの会話と共にコンテンツを開きます。このビューは、ほとんどのコラボレーションシナリオに最適です。

Stageview モーダルとダイアログの違いは何ですか?

Stageview モーダルは、ページ、ダッシュボード、ファイルなどのリッチコンテンツをユーザーに表示するのに役立ちます。
ダイアログ (TeamsJS v1.x のタスクモジュールと呼ばれます) は、ユーザーの注意を必要とするメッセージを表示したり、次の手順に進むのに必要な情報を収集したりするのに役立ちます。

Stageview が呼び出されると、コンテンツは Collaborative Stageview で開きますが、新しいウィンドウではなくメイン Teams ウィンドウに読み込まれます。新しいウィンドウでコンテンツを開く方法

ドメインが contentUrl マニフェスト validDomains プロパティに正確に反映されていることを確認します。詳細については、「アプリマニフェストスキーマ」を参照してください。

'contentUrl' が 'validDomains' と一致する場合でも、新しい Teams ウィンドウにコンテンツが表示されないのはなぜですか?

すべての iframe ベースのコンテンツを呼び出 app.notifySuccess() して、アプリが正常に読み込まれたことを Teams に通知します。該当する場合、Teams は読み込みインジケーターを非表示にします。が 30 秒以内に呼び出されない場合 notifySuccess 、Teams はアプリがタイムアウトであると想定し、再試行オプションを含むエラー画面を表示します。アプリの更新の場合、この手順は既に構成されているタブに適用されます。この手順を実行しない場合は、既存のユーザーのエラー画面が表示されます。

'contentUrl' にディープリンクを含めることができますか?

いいえ。ディープリンクはでは contentUrlサポートされていません。

操作方法コンテンツと共に特定のスレッドを表示したままにしますか?

ディープリンクまたは stageView API からの共同ステージビューには、追加 threadId のパラメーターが付属しています。特定 contentUrlののサイドパネルに表示されるチャットスレッドを明示的に定義できます。の取得の詳細については、「会話スレッドをthreadId取得する」を参照してください。

Stageview でコンテンツを開く

Stageview の種類

Collaborative Stageview

Stageview Multi-window

Stageview の呼び出し

アダプティブカードから Collaborative Stageview を呼び出す

stageView API から呼び出す

stageView API パラメーター

ディープリンクから呼び出す

構文

ディープリンククエリパラメーター

FAQ

関連項目

フィードバック

その他のリソース

Stageview でコンテンツを開く

Stageview の種類

Collaborative Stageview

Stageview Multi-window

Stageview モーダル

Stageview の呼び出し

アダプティブ カードから Collaborative Stageview を呼び出す

stageView API から呼び出す

stageView API パラメーター

ディープ リンクから呼び出す

構文

ディープ リンク クエリ パラメーター

FAQ

関連項目

フィードバック

その他のリソース

アダプティブカードから Collaborative Stageview を呼び出す

ディープリンクから呼び出す

ディープリンククエリパラメーター