SpaceAPI

Interface SpaceAPIExperimental

Space API

The Space API provides methods to interact with a 3D space.

Overview

To work with 3D spaces, you can use the Space API to open existing spaces, create new ones, and obtain shareable space handles.

Quick Start

// User A: Gets a shareable handle for the current space
const spaceHandle = await webvis.getContext().requestSpaceHandle();

// User B: Opens an existing space using the handle of user A
await webvis.getContext().openSpace(spaceHandle); // You're now in the existing space

// You can also create a new, empty space
await webvis.getContext().openSpace(); // You're now in a new, empty space

Space Handles

A space handle is a URL that can be used to open a specific 3D space. It contains the space ID and an optional access token for a specific member role. You can obtain a space handle for the current space using the requestSpaceHandle method.

// Get the webvis context
const context = await webvis.getContext();

// Get a space handle for the current space with the default role (Viewer)
const viewerHandle = await context.requestSpaceHandle();

// Get a space handle for the current space with a certain role
const editorHandle = await context.requestSpaceHandle(MemberRole.EDITOR);

Cloning Spaces

You can create a new 3D space by cloning the current space using the cloneIntoNewSpace method. This creates a new space with the same content as the current one, allowing you to make changes without affecting the original space.

// Clone the current space into a new space
await context.cloneIntoNewSpace(); // You're now in the cloned space

Events

The Space API emits the following events:

interface SpaceAPI {
    cloneIntoNewSpace(): Promise<void>;
    openSpace(spaceHandle?: string): Promise<void>;
    requestSpaceHandle(role?: MemberRole): Promise<string>;
}

Hierarchy (View Summary)

Methods

cloneIntoNewSpace openSpace requestSpaceHandle

Methods

cloneIntoNewSpace

  • cloneIntoNewSpace(): Promise<void>
  • Experimental

    Opens a new 3D space by cloning the current space.

    Returns Promise<void>

    A promise that resolves when the new space has been opened.

openSpace

  • openSpace(spaceHandle?: string): Promise<void>
  • Experimental

    Opens a 3D space.

    If a space handle is specified and it exists, switches to the 3D space referenced by the handle. If a space handle is specified and it does not exist, throws an error. If no space handle is specified, creates a new 3D space and clears the content.

    Parameters

    • OptionalspaceHandle: string

      The handle of the space to open. If undefined, a new space is created.

    Returns Promise<void>

    A promise that resolves when the space has been opened.

    See

    requestSpaceHandle to get a space handle.

requestSpaceHandle

  • requestSpaceHandle(role?: MemberRole): Promise<string>
  • Experimental

    Requests a shareable space handle for the current 3D space.

    A space handle is a URL that can be used to open the current 3D space. It has the following format:

    • <HUB_URL>/api/space/v2/<SPACE_ID> if no role is specified.
    • <HUB_URL>/api/space/v2/<SPACE_ID>?token=<TOKEN> if a role is specified. where <HUB_URL> is the URL of the hub, <SPACE_ID> is the ID of the current space, and <TOKEN> is the access token for the specified role.

    Parameters

    • Optionalrole: MemberRole

      The role to assign when the space is opened via the handle. If undefined, the MemberRole.VIEWER role will be assigned when opening the space via the handle.

    Returns Promise<string>

    A promise that resolves to the space handle.