Embeddable Engine

API Documentation

The @sdk/embeddable-engine package provides the core functionality for embedding and interacting with a customized instance of RCS. 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 (opens in a new tab) to load the RCS instance and its dependencies. In order to isolate CSS styling and prevent conflicts with the host application, the RCS 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 RCS 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 RCS 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 RCS 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 RCS instance consists of two steps:

Setup of the engine which loads the RCS instance and its dependencies.
Attaching the RCS 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 () => __my_auth_token__,
  /**
   * The asset ID to load.
   */
  assetId: __my_asset_id__,
  /**
   * The remote environment to load RCS 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 RCS to use, while the authTokenResolver is a callback that returns the authentication token needed to access the RCS instance. The assetId is the ID of the asset to load, and remoteEnvironment specifies which environment to load RCS 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 RCS Instance

Once the engine is set up, you can attach the RCS 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) => {
    engine.attach(node, { loaderComponent: <h1>Loading...</h1> });
 
    // After the RCS 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 RCS instance to a div element, but it also should work similary with any other framework or even plain JavaScript.

Project Notification