JetBrains Space ヘルプ

アプリケーションのホームページ

サンプル

アプリケーションは、インラインフレーム (iframe) を使用して Space にユーザーインターフェースを表示できます。この目的のために、アプリケーションのページには特別なホームページタブが含まれています。

アプリケーションのホームページタブを追加する

ホームページタブをそのページに追加するには、アプリケーションは setUiExtensions API 呼び出しを行う必要があります。例: Kotlin Space SDK を使用してサーバー側でこれを行う方法は次のとおりです。

spaceClient.applications.setUiExtensions( contextIdentifier = GlobalPermissionContextIdentifier, extensions = listOf( // requires URL of the homepage iframe ApplicationHomepageUiExtensionIn("https://iframe.url") ) )

ホームページのコンテンツを準備する

アプリケーションは、<main-app-endpoint>/iframe/app-homepage エンドポイント上の HTML コンテンツで応答する必要があります。

例: Ktor を使用する場合:

fun Routing.routes() { get("api/myapp/iframe/app-homepage") { call.respondHtml(HttpStatusCode.OK) { // generate HTML page... } } }

Space と iframe の間の通信

アプリケーションの iframe と Space 間の通信は、Window.postMessage APIチャネルメッセージング API の 2 つのメカニズムを組み合わせて実装されます。

メッセージを送信するには、iframe は次のことを行う必要があります。

  1. MessageChannel を作成します。

  2. MessageChannel で応答を購読します。

  3. Window.postMessage 呼び出しを実行し、transfer パラメーターに channel.port2 を渡します。

例: Space からユーザートークンを取得するには:

function getUserAccessTokenData(askForConsent) { return new Promise((resolve) => { // 1. Create a MessageChannel const channel = new MessageChannel(); // 2. Subscribe to response channel.port1.onmessage = e => resolve(e.data); // 3. Call postMessage window.parent.postMessage({ type: "GetUserTokenRequest", permissionScope: "global:Profile.View global:Profile.Memberships.View", askForConsent: askForConsent }, "*", [channel.port2]); }); }

postMessage の最初のパラメーターは、メッセージ内容を含むデータオブジェクトです。オブジェクトパラメーターは、オブジェクト type に依存します。

GetUserTokenRequest: Space ユーザートークンを取得する

GetUserTokenRequest 呼び出しは、Space からのユーザートークンを要求します。アプリケーションはこのトークンを次の目的で使用できます。

  • ユーザーに代わって Space にリクエストを送信します。

  • JWT トークンクレームから情報を抽出します。ユーザー ID、インストールされているアプリケーションの clientId、および Space URL を取得します (URL は GetUserTokenRequest への応答でも明示的に返されます)。

データオブジェクトの例:

{ type: "GetUserTokenRequest", permissionScope: "global:Profile.View global:Profile.Memberships.View", askForConsent: true }
入力パラメーター

permissionScope

(必須) トークンに付与する必要があるアクセス許可を含む Space 区切りの文字列。例:

  • global:Profile.View global:Profile.Memberships.View – プロファイルとチームメンバーシップを表示します。

  • project:key:MY-PROJECT-KEY:Project.Issues.View – MY-PROJECT-KEY プロジェクトの課題を表示します。

  • channel:42P9E54DAkJW:Channel.ViewMessages42P9E54DAkJW ID を持つチャネル内のメッセージを表示します。

権限について詳しく見る

askForConsent

(必須) 可能な値:

  • true – Space は、アプリケーションがユーザーに代わって動作することを許可するかどうかを確認するダイアログをユーザーに表示します。このダイアログには、permissionScope で渡された、ユーザーによってまだ付与されていないアクセス許可がリストされます。ユーザーがアクセス許可を付与すると、Space はトークンを生成し、それを iframe に返します。

  • false – Space にはダイアログが表示されません。Space は、現在の Space ユーザーが以前にアプリケーションに permissionScope からのすべてのアクセス許可を付与している場合にのみ、トークンを生成して iframe に返します。

askForConsent パラメーターを使用すると、次のロジックを実装できます。アプリケーションは、Space に確認なしでトークンを要求します。トークンが返されない場合、Space はユーザーに認証ダイアログを表示します。サンプルアプリケーション(英語)の例を参照してください。

レスポンス

オブジェクトまたは null ユーザートークンが正常に生成されると、Space は 2 つのフィールドを含むオブジェクトを返します。

  • token – Space HTTP API 呼び出しにおけるベアラー認証用のアクセストークン。サンプルアプリケーション(英語)の例を参照してください。

  • serverUrl – 現在の Space 組織の URL。

GetThemePropertiesRequest: ホームページに Space UI テーマを適用する

対応する色とフォントを使用して、アプリケーションのホームページを現在の Space UI テーマに従って外観にすることができます。これにより、アプリケーションのユーザーに、よりシームレスなエクスペリエンスが提供されます。

現在、Space CSS スタイルを自動的に取得する便利な方法はありません (ただし、将来追加される可能性があります)。GetThemePropertiesRequest 呼び出しを行うと、色とフォントの変数のみを取得できます。このメカニズムを使用して Space UI を完全に模倣することはできません。

データオブジェクトの例:

{ type: "GetThemePropertiesRequest", subscribeForUpdates: true }
入力パラメーター

subscribeForUpdates

(オプション) 可能な値:

  • true – アプリケーション iframe は、現在選択されているテーマの変更をサブスクライブします。ユーザーがテーマ (ライト / ダーク) を変更すると、iframe は更新された CSS 変数を含むメッセージを受信し、その場で UI を更新できるようになります。サンプルアプリケーション(英語)の例を参照してください。

  • false – デフォルト。

レスポンス

2 つのフィールドを含むオブジェクト:

  • properties – オブジェクトの配列。各オブジェクトには次の 2 つのプロパティがあります。

    • name – CSS 変数の名前。

    • value – 変数値。

    アプリケーションで変数を使用するには、配列を調べて iframe ドキュメントの変数を設定します。サンプルアプリケーション(英語)の例を参照してください。

  • isDarktrue または false 現在選択されている UI テーマがダークかどうかを指定します。

RedirectWithConfirmationRequest: ユーザーを別の Web ページにリダイレクトする

場合によっては、たとえばサードパーティのサービスでユーザーを認証するために、ユーザーをアプリケーションのホームページから別の URL にリダイレクトする必要があるかもしれません。セキュリティ上の理由から、iframe が単独でリダイレクトを実行することは許可されていません。これを機能させるには、RedirectWithConfirmationRequest 呼び出しを実行します。Space は確認ダイアログを表示し、トップレベルウィンドウを指定された Web ページにリダイレクトします。

データオブジェクトの例:

{ type: "RedirectWithConfirmationRequest", redirectUrl: "https://example.com/login", newTab: true, okButtonText: "Authorize" }
入力パラメーター

redirectUrl

(必須) トップレベルウィンドウのリダイレクト先となる URL。

newTab

(オプション) 新しいタブで Web ページを開くかどうかを指定します。

okButtonText

(オプション) 確認ダイアログの「OK」ボタンのキャプションテキスト。デフォルトでは、Proceed

レスポンス

応答は送信されません。iframe 内のコードは await である必要があります。

ShowConfirmDialogRequest: 確認を表示するダイアログ

アプリケーションに確認ダイアログを実装する代わりに、Space が提供するダイアログを使用できます。ダイアログを表示するには、ShowConfirmDialogRequest 呼び出しを行います。

データオブジェクトの例:

{ type: "ShowConfirmDialogRequest", question: "Are you sure?", okButtonText: "Yes" }
入力パラメーター

question

(必須) ダイアログのヘッダーテキスト。

okButtonKind

(オプション) 「OK」ボタンのデフォルトのスタイル。可能な値: NORMALSECONDARYDANGERSUCCESSWARNINGPRIMARYPRIMARY_SUCCESSPRIMARY_WARNINGALTERNATIVEALTERNATIVE_DANGERALTERNATIVE_SUCCESSALTERNATIVE_WARNING

okButtonText

(オプション) 「OK」ボタンのキャプションテキスト。

description

(オプション) 確認ダイアログに表示される追加のテキスト。

関連ページ:

権限のリクエスト

特定の Space エンドポイントにアクセスするには、アプリケーションはまず対応するアクセス許可を取得する必要があります。例: アプリケーションがプロジェクトの課題を作成する場合、アプリケーションには課題の作成権限が必要です。課題の詳細を表示するには、課題を表示する権限が必要です。アプリケーションに必要な権限のセット全体は、権限スコープと呼ばれます。アプリケーションがアクセス許可を要求する方法は、アプリケーション自体の代わりに動作するアプリケーションと、Space ユーザーの代わりに動作するアプ...

拡張機能

Space アプリケーションでは、次の拡張機能を使用できます。アプリケーションは、iframe を介して独自のユーザーインターフェースを Space に提供できます。アプリケーションは、インストール後にユーザーを「はじめに」ページにリダイレクトできます。アプリケーションは、カスタムメニュー項目を使用して Space コンテキストメニューを拡張できます。アプリケーションはチャットメッセージを受信し、メッセージ UI コントロールを使用したユーザーの操作に反応できます。アプリケーションは、Space...

はじめにページ

複数組織アプリケーションでは、ユーザーを「はじめに」ページにリダイレクトできます。このページには、アプリケーション、その機能、使用方法に関する情報を含めることができます。アプリケーションのインストール後、ダイアログにはユーザーをオンラインドキュメントページにリダイレクトするボタンが含まれます。アプリケーション開発者は、ボタンのテキストとページの URL をカスタマイズできます。カスタムメニュー項目を追加するには、アプリケーションは API 呼び出しを行う必要があります。例:// The URL o...