3.13.0 Migration Guide

This release includes several API cleanups, refactorings and changes which will be addressed in the following. This document includes general information about the changes necessary for the migration and a detailed list of API changes.

SessionAPI to SpaceAPI Migration

The core API enabling collaboration in instant3Dhub has been thoroughly reworked in versions 3.12 and 3.13. The already deprecated SessionAPI has now been removed in favor of the SpaceAPI and, as such, sessions are replaced by 3DSpaces.

Conceptually, 3DSpaces are quite similar to sessions, but the terminology has been changed. Please note, that not all of the removed SessionAPI entities can be mapped one-to-one to the SpaceAPI. For more details, see the complete list of entity changes below, as well as the interface-level documentation for the SpaceAPI and MemberAPI.

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

XR Members Removal

With the introduction of the MemberAPI in 3.12, this release removes the last remaining XR-specific member concepts in the RealityAPI and streamlines them into the more generic MemberAPI. Members that publish a subscribable XR image stream can now be filtered via the MemberActions they offer (e.g. FOLLOW_XR_VIEW and UNFOLLOW_XR_VIEW). Furthermore, the XR image stream must now be subscribed to via the corresponding MemberAction:

// Filter members that offer the FOLLOW_XR_VIEW or UNFOLLOW_XR_VIEW MemberAction
const members: number[] = webvis.getContext().getMembers();
const xrMembers: number[] = [];
// Start with index 1 to skip the local member
for (let i = 1; i < members.length; i++)
{
    const memberId: number = members[i];
    const memberActions: webvis.MemberAction[] = await webvis.getContext().requestMemberActions(memberId);
    if (memberActions.includes(webvis.MemberAction.FOLLOW_XR_VIEW) || memberActions.includes(webvis.MemberAction.UNFOLLOW_XR_VIEW))
    {
        xrMembers.push(memberId);
    }
}

// Subscribe to the XR image stream of another member
const memberId: number = xrMembers[0];
const memberActions: webvis.MemberAction[] = await webvis.getContext().requestMemberActions(memberId);
if (memberActions.includes(webvis.MemberAction.FOLLOW_XR_VIEW))
{
    await webvis.getContext().useMemberAction(memberId, webvis.MemberAction.FOLLOW_XR_VIEW);
}

QueryAPI Changes

Return Value for Missing Metadata Entries

In previous releases, when a query requested a metadata entry that did not exist for a matching node, then the result would contain the string "undefined" for that node. The same was true for metadata entries of ancestor nodes returned by ancestor selectors. In this release, the query result will contain null to indicate a missing metadata entry. If your code checks the returned metadata values for the string "undefined", then please update it to check for null instead.

const result = await webvis.getContext().query({
    select: ["nodeId", "metadata.someKey"],
    conditions: [
        {nodeType: "structure"},
        {metadata: "label", equals: "SomePrefix*"}
    ]
});

for (const entry of result.data) {
    if (entry[1] === null) {
        console.log(`Node with ID ${entry[0]} does not have metadata entry for someKey`);
    }
}

Numerical Comparison Operators

In this release, query conditions with numerical comparison operators like lessThan or greaterThan no longer accept string values. Previously, when working with the webvis QueryAPI in JavaScript, it was possible to use string values for numerical comparisons, which would be implicitly converted to numbers. If your application relies on this behavior, please update your code so that the corresponding string values are converted to numbers before query construction. For example, a condition of the form

{"metadata": "auxProperties.value", "lessThan": "10"}

should be updated to

{"metadata": "auxProperties.value", "lessThan": 10}

Direct Label Conditions

The reworked QueryAPI does not support label conditions of the form

{label: "value"}

If your application uses such a condition, please change it to

{metadata: "label", equals: "value"}

Subquery Support

In this release, subqueries are only supported in combination with the equals operator and must return a single value. In previous releases, when a subquery returned multiple result entries, these were collected in an array and the operator was implicitly changed to equalsAny. Additionally, certain kinds of subqueries were supported for operators other than equals. If your application depends on the described subquery behavior, please extract the corresponding subqueries from the main query and execute them separately.

API Changes

The following list contain API additions, changes and removals which might be subject for migration efforts. Most alterations were performed to provide a more streamlined experience when working with the API and come only with minimal need for manual intervention from application developers.

ContextAPI

Events

Enums

EventType

ServiceType

SettingStrings

  • SESSION_DEVICE_TAGS
  • SESSION_FORWARD_URL
  • SESSION_INTERACTIONS
  • SESSION_MEMBER_NAME

ViewerSettingStrings



Was this page helpful? Please leave a thumbs up or down.