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

サンプル

クライアント側アプリケーション(英語)は HTML、CSS、JavaScript で書かれています。
クライアントサーバーアプリケーション(英語)。サーバーは Kotlin で記述され、クライアント側は React で記述されます。

アプリケーションは、インラインフレーム (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 は次のことを行う必要があります。

MessageChannel を作成します。
MessageChannel で応答を購読します。
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
GetThemePropertiesRequest
RedirectWithConfirmationRequest
ShowConfirmDialogRequest

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.ViewMessages – 42P9E54DAkJW 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 ドキュメントの変数を設定します。サンプルアプリケーション(英語)の例を参照してください。
isDark – true または 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」ボタンのデフォルトのスタイル。可能な値: `NORMAL`、`SECONDARY`、`DANGER`、`SUCCESS`、`WARNING`、`PRIMARY`、`PRIMARY_SUCCESS`、`PRIMARY_WARNING`、`ALTERNATIVE`、`ALTERNATIVE_DANGER`、`ALTERNATIVE_SUCCESS`、`ALTERNATIVE_WARNING`
`okButtonText`	(オプション) 「OK」ボタンのキャプションテキスト。
`description`	(オプション) 確認ダイアログに表示される追加のテキスト。

最終更新日: 2023 年 7 月 19 日

JetBrains Space ヘルプ

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