SessionAPI to SpaceAPI migration

The core API enabling collaboration in instant3Dhub has been thoroughly reworked in instant3Dhub 3.12 and 3.13. This article explains what has changed and how it affects the Unreal Plugin.

Terminology and Conceptual Changes

The SessionAPI has been deprecated in favor of the SpaceAPI and, as such, sessions are replaced by 3D spaces.

Conceptually, 3D spaces are quite similar to sessions, but the terminology has been changed. One difference is that the default state in webvis is now an empty (anonymous) 3D space, which was previously “not connected to a session” (this distinction is not very relevant in the context of the Unreal Plugin).

The SessionStorageAPI, which is used for storing and restoring the entire state of a 3D space, is currently not affected by this change and continues to work as is.

WebVis

The following table shows which versions of webvis support which API.

instant3Dhub Version	SessionAPI	SpaceAPI	SessionStorageAPI
3.11	✅	❌	✅
3.12	✅	✅ (experimental)	✅
3.13	❌	✅	✅

In 3.12 the implementations of the SessionAPI and the SpaceAPI are compatible with each other and can be used interchangeably (i.e. a SessionID can be used as a SpaceID).

Unreal Plugin

As per the Version & Compatibility table, version 1.3.0 and before are only compatible up to instant3Dhub version 3.12 and exclusively use the SessionAPI.

Starting with version 1.4.0 the Unreal Plugin is compatible with instant3Dhub 3.13 as well and will transparently select between the SessionAPI and the SpaceAPI depending on which version of instant3Dhub you connect to.

Importantly, unlike webvis, the ConnectToHub API is backwards-compatible with earlier plugin versions and remains the preferred API to use.

However, since the SpaceAPI is the way going forward, we decided to update the terminology used in the Unreal Plugin’s API as well. Therefore, some elements have been deprecated in favor of new equivalent elements using the SpaceAPI terminology, including:

• I3DHConnectOptions::SessionId -> I3DHConnectOptions::SpaceId

• I3DHConnector::GetSessionId -> I3DHConnector::GetSpaceId

Both old and new elements work identical (and irrespective of which API is supported by webvis). We reserve the right to remove the deprecated elements as early as version 1.5.0 of the Unreal Plugin (again, this is a pure rename in the Unreal Plugin’s API and has no effect on functionality or compatibility).

Additionally, in version 1.4.0, we introduce new connection related APIs:

• I3DHConnector::ConnectToHubWithLink and I3DHConnector::ParseConnectLink allow connecting via a single URL. This is a simple, versatile and future-proof connection method.

• The new FI3DHSpaceAPI provides access to new SpaceAPI functionality that did not exist in the old SessionAPI (requires instant3Dhub 3.12+).

Summary and migration advice

• In Unreal code SessionId and SpaceId are interchangeable.

• If your C++ code uses now deprecated session-related names, migrate to the new space-related names (functionality is identical).

• Your Blueprint code should have been updated automatically via redirectors.

• Check out the new connection related APIs in the Unreal Plugin described above.