Application Homepage
Samples
|
Applications can display their user interface in Space using inline frames (iframes). For this purpose, the application's page contains a special Homepage tab.
Add a homepage tab for the application
To add the Homepage tab to its page, the application must make the setUiExtensions
API call. For example, this is how you can do it on the server side using Kotlin Space SDK:
Prepare the homepage content
The application must respond with the HTML content on the <main-app-endpoint>/iframe/app-homepage
endpoint.
For example, if you use Ktor:
Communication between Space and iframe
The communication between the application's iframe and Space is implemented by combining two mechanisms: Window.postMessage API and Channel Messaging API.
To send a message, the iframe must:
Create a
MessageChannel
.Subscribe to responses in the
MessageChannel
.Make a
Window.postMessage
call, passingchannel.port2
in thetransfer
parameter.
For example, to get a user token from Space:
The first parameter of postMessage
is a data object with message contents. The object parameters depend on the object type
:
GetUserTokenRequest. Get a Space user token
A GetUserTokenRequest
call requests a user token from Space. The application can use this token to:
Make requests to Space on behalf of a user.
Extract information from the JWT token claims: get a user identifier, a clientId of the installed application, and the Space URL (the URL is also returned explicitly in a response to
GetUserTokenRequest
).
A data object example:
- Input parameters
permissionScope
(Required) A space-separated string with permissions that must be granted to the token. For example:
global:Profile.View global:Profile.Memberships.View
– view profiles and team memberships.project:key:MY-PROJECT-KEY:Project.Issues.View
– view issues in the MY-PROJECT-KEY project.channel:42P9E54DAkJW:Channel.ViewMessages
– view messages in the channel with the42P9E54DAkJW
ID.
askForConsent
(Required) Possible values:
true
– Space shows the user a dialog asking to permit the application to act on behalf of the user. The dialog lists the permissions passed in thepermissionScope
that are not yet granted by the user. If the user grants the permissions, Space generates a token and returns it to the iframe.false
– Space doesn't show a dialog. Space will generate a token and return it to the iframe only if the current Space user has previously granted the application all permissions from thepermissionScope
.
The
askForConsent
parameter lets you implement the following logic: The application silently asks Space for a token; if the token is not returned, Space shows the user an authorization dialog. See an example in our sample application.- Response
An object or
null
. If a user token is generated successfully, Space returns an object containing two fields:token
– an access token for bearer authorization in Space HTTP API calls. See an example in our sample application.serverUrl
– the URL of the current Space organization.
GetThemePropertiesRequest. Apply the Space UI theme in the homepage
Using the corresponding colors and fonts, you can make the application homepage look according to the current Space UI theme. This will provide a more seamless experience for the users of your application.
Currently, there's no convenient automatic way to get the Space CSS styles (though, it may be added in the future). By making a GetThemePropertiesRequest
call, you can get only color and font variables. So, this mechanism can't be used to mimic the Space UI completely.
A data object example:
- Input parameters
subscribeForUpdates
(Optional) Possible values:
true
– The application iframe is subscribed for the changes in the currently selected theme. When the user changes the theme (light/dark), the iframe will receive a message with the updated CSS variables so that it can update its UI on the fly. See an example in our sample application.false
– Default.
- Response
An object containing two fields:
properties
– an array of objects. Each object has two properties:name
– the name of the CSS variable.value
– a variable value.
To use the variables in your application, go through the array and set the variables for the iframe document. See an example in our sample application.
isDark
–true
orfalse
. Designates whether the currently selected UI theme is dark.
RedirectWithConfirmationRequest. Redirect the user to a different webpage
In some cases, you may need to redirect a user from the application homepage to another URL, e.g., to authorize the user in a third-party service. For security reasons, the iframe is not allowed to perform redirects on its own. To make this work, make a RedirectWithConfirmationRequest
call – Space will show a confirmation dialog and redirect the top-level window to the specified webpage.
A data object example:
- Input parameters
redirectUrl
(Required) The URL where the top-level window must be redirected to.
newTab
(Optional) Specifies whether to open the webpage in a new tab.
okButtonText
(Optional) The caption text of the 'OK' button in the confirmation dialog. By default,
Proceed
.- Response
No response is sent. The code in the iframe must
await
for it.
ShowConfirmDialogRequest. Show a confirmation dialog
Instead of implementing a confirmation dialog in your application, you can use a dialog provided by Space. To show the dialog, make a ShowConfirmDialogRequest
call.
A data object example:
- Input parameters
question
(Required) A dialog header text.
okButtonKind
(Optional) A default style of the 'OK' button. Possible values:
NORMAL
,SECONDARY
,DANGER
,SUCCESS
,WARNING
,PRIMARY
,PRIMARY_SUCCESS
,PRIMARY_WARNING
,ALTERNATIVE
,ALTERNATIVE_DANGER
,ALTERNATIVE_SUCCESS
,ALTERNATIVE_WARNING
.okButtonText
(Optional) The caption text of the 'OK' button.
description
(Optional) An additional text shown in the confirmation dialog.