Application Homepage

Samples

Client-side application written in HTML, CSS, and JavaScript.
Client-server application, with the server written in Kotlin and the client side written in React.

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:

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

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:

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

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, passing channel.port2 in the transfer parameter.

For example, to get a user token from 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]);
    });
}

The first parameter of postMessage is a data object with message contents. The object parameters depend on the object type:

GetUserTokenRequest
GetThemePropertiesRequest
RedirectWithConfirmationRequest
ShowConfirmDialogRequest

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:

{
    type: "GetUserTokenRequest",
    permissionScope: "global:Profile.View global:Profile.Memberships.View",
    askForConsent: true
}

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 the 42P9E54DAkJW ID.

Learn more about permissions

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 the permissionScope 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 the permissionScope.

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:

{
    type: "GetThemePropertiesRequest",
    subscribeForUpdates: true
}

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 or false. 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:

{
    type: "RedirectWithConfirmationRequest",
    redirectUrl: "https://example.com/login",
    newTab: true,
    okButtonText: "Authorize"
}

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:

{
    type: "ShowConfirmDialogRequest",
    question: "Are you sure?",
    okButtonText: "Yes"
}

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.

Last modified: 19 July 2023