Skip to Content
SDKPackagesEmbeddable RCSEmbeddable Engine

Embeddable Engine

API Documentation

The @sdk/embeddable-engine package provides the core functionality for embedding and interacting with a customized instance of Hexagon GeoCloud. This works similar to iFrames, but renders the content directly in the page, allowing for more seamless integration.

Under the hood this package abstracts away a complex set of configurations leveraging Module Federation  to load the Hexagon GeoCloud instance and its dependencies. In order to isolate CSS styling and prevent conflicts with the host application, the Hexagon GeoCloud instance is automatically rendered in a shadow DOM root.

Caveats

This package is currently under development and is not yet ready for production use.
  • As this should work with and JS/TS stack, if React is used, it currently only works with React 18. This is because an internal dependency used by Hexagon GeoCloud currently doesn’t work with React 19. We’re working on removing this dependency. Final React requirements will be version >=18.
  • The programmatic API to interact with the Hexagon GeoCloud instance is not yet fully implemented.
  • The API’s documented here are subject to change as the package is still under development.

Installation

To install this package, you need to have access to the private @sdk npm scope.

To install the library, run the following command in your project directory. @sdk/embedded-engine is the main package, and @sdk/embedded-api provides the API to interact with the Hexagon GeoCloud instance. React and ReactDOM are peer dependencies, so you need to install them as well if the project doesn’t use them already. The version of React must currently be >=18 and the version of ReactDOM must match the version of React.

npm install @sdk/embedded-engine @sdk/embedded-api react@18.3.1 react-dom@18.3.1

Usage

Rendering the Hexagon GeoCloud instance consists of two steps:

  • Setup of the engine which loads the Hexagon GeoCloud instance and its dependencies.
  • Attaching the Hexagon GeoCloud instance to a DOM element.

Engine Setup

import { RcsEmbeddedEngine } from '@sdk/embedded-engine';
 
const engine = new RcsEmbeddedEngine({
  /**
   * Which tailored instance to use.
   */
  application: 'multivista',
  /**
   * A callback that returns the auth token to use for the embedded application to use.
   */
  authTokenResolver: async () => ({ isPublic: false, token: __my_auth_token__ }),
  /**
   * The asset ID to load.
   */
  assetId: __my_asset_id__,
  /**
   * The remote environment to load Hexagon GeoCloud from.
   * Can be 'stg' | 'qa' | 'uat' | 'prod' | string (custom URL)
   */
  remoteEnvironment: 'prod',
});

In this example, we create a new instance of the RcsEmbeddedEngine class, passing in the required configuration options. The application option specifies which tailored instance of Hexagon GeoCloud to use, while the authTokenResolver is a callback that returns the authentication token needed to access the Hexagon GeoCloud instance. The assetId is the ID of the asset to load, and remoteEnvironment specifies which environment to load Hexagon GeoCloud from.

Make sure you only use a single instance of the RcsEmbeddedEngine in your application. The engine is designed to be a singleton, and using multiple instances or creating/overwriting new instances on render can lead to unexpected behavior. The API of this module might change in the future to enforce this.

Attaching the Hexagon GeoCloud Instance

Once the engine is set up, you can attach the Hexagon GeoCloud instance to a DOM element. This is done by calling the attach method on the engine instance and passing in the target DOM element.

export function EmbeddedRCSComponent() {
  const setRef = useCallback((node: HTMLElement | null) => {
    if (!node) {
      engine.detatch();
      return;
    }
 
    engine.attach(node, { loaderComponent: <h1>Loading...</h1> });
 
    // After the Hexagon GeoCloud instance is attached, you can interact with it using the API.
    engine.getSDKClient().then(client => {
      console.log(client);
    });
  }, []);
 
  return <div style={{ width: '600px', height: '600px' }} ref={setRef} />;
}

This example shows how to create a React component that attaches the Hexagon GeoCloud instance to a div element, but it also should work similary with any other framework or even plain JavaScript.

Last updated on
ProjectRenderer Plugin SDK