アプリケーションのホームページ
サンプル
|
アプリケーションは、インラインフレーム (iframe) を使用して Space にユーザーインターフェースを表示できます。この目的のために、アプリケーションのページには特別なホームページタブが含まれています。
アプリケーションのホームページタブを追加する
ホームページタブをそのページに追加するには、アプリケーションは setUiExtensions
API 呼び出しを行う必要があります。例: Kotlin Space SDK を使用してサーバー側でこれを行う方法は次のとおりです。
ホームページのコンテンツを準備する
アプリケーションは、<main-app-endpoint>/iframe/app-homepage
エンドポイント上の HTML コンテンツで応答する必要があります。
例: Ktor を使用する場合:
Space と iframe の間の通信
アプリケーションの iframe と Space 間の通信は、Window.postMessage API とチャネルメッセージング API の 2 つのメカニズムを組み合わせて実装されます。
メッセージを送信するには、iframe は次のことを行う必要があります。
MessageChannel
を作成します。MessageChannel
で応答を購読します。Window.postMessage
呼び出しを実行し、transfer
パラメーターにchannel.port2
を渡します。
例: Space からユーザートークンを取得するには:
postMessage
の最初のパラメーターは、メッセージ内容を含むデータオブジェクトです。オブジェクトパラメーターは、オブジェクト type
に依存します。
GetUserTokenRequest: Space ユーザートークンを取得する
GetUserTokenRequest
呼び出しは、Space からのユーザートークンを要求します。アプリケーションはこのトークンを次の目的で使用できます。
ユーザーに代わって Space にリクエストを送信します。
JWT トークンクレームから情報を抽出します。ユーザー ID、インストールされているアプリケーションの clientId、および Space URL を取得します (URL は
GetUserTokenRequest
への応答でも明示的に返されます)。
データオブジェクトの例:
- 入力パラメーター
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 を完全に模倣することはできません。
データオブジェクトの例:
- 入力パラメーター
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 ページにリダイレクトします。
データオブジェクトの例:
- 入力パラメーター
redirectUrl
(必須) トップレベルウィンドウのリダイレクト先となる URL。
newTab
(オプション) 新しいタブで Web ページを開くかどうかを指定します。
okButtonText
(オプション) 確認ダイアログの「OK」ボタンのキャプションテキスト。デフォルトでは、
Proceed
- レスポンス
応答は送信されません。iframe 内のコードは
await
である必要があります。
ShowConfirmDialogRequest: 確認を表示するダイアログ
アプリケーションに確認ダイアログを実装する代わりに、Space が提供するダイアログを使用できます。ダイアログを表示するには、ShowConfirmDialogRequest
呼び出しを行います。
データオブジェクトの例:
- 入力パラメーター
question
(必須) ダイアログのヘッダーテキスト。
okButtonKind
(オプション) 「OK」ボタンのデフォルトのスタイル。可能な値:
NORMAL
、SECONDARY
、DANGER
、SUCCESS
、WARNING
、PRIMARY
、PRIMARY_SUCCESS
、PRIMARY_WARNING
、ALTERNATIVE
、ALTERNATIVE_DANGER
、ALTERNATIVE_SUCCESS
、ALTERNATIVE_WARNING
okButtonText
(オプション) 「OK」ボタンのキャプションテキスト。
description
(オプション) 確認ダイアログに表示される追加のテキスト。
関連ページ:

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

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

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