Space & Session Guide

Space is Webfuse’s metaphor for your specific web proxy confgurations. A Space comprises certain access configurations, installed Apps, and installed Extensions. Alltogether, it renders virtual web Sessions that apply the web augmentations and load infrastructural enhancements.

1. Create a Space

When you open Webfuse Studio, you will be presented with a bunch of Space tiles to create a specific type of Space from. Choose Solo Space, which is a virtual resemblence of an ordinary web browser. Choose a Name and a Slug to later identify the Space and access it on the web.

2. Start a Session

To see the Space in action, start a Session from the Space page in Studio. Sessions can be started in various ways: Studio, but also via REST API, or Widget API to build seamless user experiences. Space access can be configured in Studio through the Space Settings page. Space related web augmentation can be configured within a Session, using the Session Editor. The Session Editor shows only to Admins of the Space.

3. Install an App & Extension

There are two ways to achieve web augmentations with Webfuse: via App, or via Extension. Apps bring functionality that goes beyond page scope – touching the fundamental infrastructure. Extensions are modeled after browser extensions and allow fully customized augmentations loaded for every user that joins a Session by opening the related Space URL.

Open the Session Editor in the top bar and select Apps. In the App tab, you can browse available Apps. Choose one and install it. Now, open the Extensions tab and upload an Extension. If you do not yet have developed an Extension, skip this step or reuse an existing one, such as the Assistant Agent Extension Example.

4. Configure Session Appearance

Within the Session, you will immediately see the effects of installed Apps and Extensions. For a seamless experience, you can configure a Session’s behavior further through the Session Settings. Open it from the top bar. Go to Interface -> Hide Session UI and enable the toggle. Save the changes and close the Settings modal.

5. Export Space

You can export Spaces using the REST API or through the Studio. This is useful for cloning Spaces, migrating Spaces between companies or for backup purposes. Space export contains all the data needed to recreate the Space, including name, type of the Space, access control settings, settings, etc.

Currently we support the following data to be exported/imported:

Space Name
Space Type
Space Visibility
Space Identification
Space Access Control
Space Host Rights
Space Settings
Space Apps (installed)
Space Extensions (installed)
Space Landing Page (if applicable)

Exporting via Studio

Spaces can be easily exported via Studio, you need to follow the steps:

Open the Space you want to export.
Click on the Share button.
Click on the Export Template button.
If you have Extensions in the Space. You will need to add the repository URL and branch name.
Click on the Export Space button to view the export options.

There are 3 options to export your Space:

Shareable link – Click on the Shareable Link button to copy the shareable link. Opening the shareable link will redirect to the Studio and show the Space import dialog.
Download JSON – Click on the “Download JSON” button to download a JSON file which can be uploaded by clicking on the Import Space button in the studio homepage.
Embeddable Widget – Click on the Embeddable Widget button to display the snippet which can be copied and embedded in your own app or web page. Clicking on the Widget will redirect to the Studio and show the Space import dialog.

Exporting via REST API

To export a Space via REST API, you need to use the GET /spaces/{space_id}/export endpoint. This will return a base64 encoded JSON object that you can use to import the Space.

You can use either the company token or the Space token to export the Space.

Storage apps and references to them in the applications are not exported. Instead, you can use the overrides field to specify the storage app to use for the Space while importing. The format is the same as the one used in the GET /Spaces/{Space_id}/storages/ endpoint.

Exporting Extensions

To export extensions, you need to modify the extensions field in the resulting JSON object.

Each extension is represented as a JSON object with the following fields:

manifest: The manifest of the extension.
branch: The branch of the GitHub repository that contains the extension.

The manifest field is the same as the one used in the GET /Spaces/{Space_id}/extensions/ endpoint.

To specify the repository URL, you need to modify the homepage_url field in the manifest object.

Exporting custom landing page

To export the custom landing page, you need to modify the custom_landing_page field in the resulting JSON object.

Custom landing page is represented as a JSON object with the following fields:

repo_url: The URL of the GitHub repository that contains the custom landing page.
branch: The branch of the GitHub repository that contains the custom landing page.

If you don’t specify the branch field, it will default to main.

6. Import Space

Importing via Studio

To import a Space in Studio, you need to follow the steps:

Importing through Shareable Link and Embeddable widget – When opening a shareable link or clicking on the embedded widget, the link should redirect you to the studio homepage and it should open the Space Import dialog automatically.
Importing through JSON – When importing a Space via the exported JSON file, you can visit the Studio home page and click on the Import Space button, then upload the JSON file to open the Space import dialog.

Importing via REST API

To import a Space via REST API, you need to use the POST /Spaces/import endpoint. This will import the Space and all related objects. The name of the Space will be the same as the original Space, but the slug will be a random string. You can change the slug any time in the Space settings.

Default storage

When importing Extensions or Custom Landing Pages, the Space requires a storage. You can use the default company storage if available when importing the Space. However, if you want to use your own storage for importing the Space, you need to define the overrides.default_storage field in the exported JSON.

For importing a Space via REST API, you need to use the overrides.default_storage field in the request body. The format is the same as the one used in the GET /spaces/{space_id}/storages/ endpoint.

Example

Here is an example of how to export and import a Space using Python.

import requests

BASE_URL = "https://webfuse.com/api/Spaces"
HEADERS = {
    "Authorization": "Token ck_<YOUR_COMPANY_TOKEN>",
    "Content-Type": "application/json",
}


def export_Space(Space_id):
    url = f"{BASE_URL}/{Space_id}/export"
    response = requests.get(url, headers=HEADERS)
    response.raise_for_status()
    return response.json()


def import_Space(Space_data):
    url = f"{BASE_URL}/import/"
    response = requests.post(url, headers=HEADERS, json=Space_data)
    response.raise_for_status()
    return response.json()


def add_admin(Space_id, user_id):
    url = f"{BASE_URL}/{Space_id}/members/"
    response = requests.post(
        url,
        headers=HEADERS,
        json={"member": user_id, "Space": Space_id, "role": "admin"},
    )
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    # Export Space with id 31
    Space_id = 31
    Space_data = export_Space(Space_id)
    print("Exported Space", Space_data)  # `{"Space_data": "...", "overrides": {}}`

    # Check the resulting file and fill in the missing fields if needed
    Space_data["Space_data"]["extensions"] = [
        {
            "manifest": {
                "homepage_url": "https://github.com/owner/extension",
            },
            "branch": "main",
        }
    ]

    Space_data["Space_data"]["custom_landing_page"] = {
        "repo_url": "https://github.com/owner/landing-page",
        "branch": "main",
    }

    # Now import Space using the hash generated above and add a default storage
    Space_data["overrides"] = {
        "default_storage": {
            "provider": "s3",
            "name": "a valid s3 storage",
            "config": {
                "endpoint_url": "https://s3.amazonaws.com",
                "bucket_name": "test",
                "region_name": "us-east-1",
                "access_key": "test",
                "secret_key": "test",
            },
        }
    }
    imported_Space = import_Space(Space_data)
    print(imported_Space)  # {"id": 123, "name": "..."}

    # Add admin, since new Space has no admins by default
    admin_id = 1
    add_admin(imported_Space["id"], admin_id)