Embedded UI: Understanding the embedded.js File

The Embedded UI feature is intended for developers who have a strong understanding of the Unqork Designer Platform and JavaScript.

Overview

Embedded UI works by inserting a JavaScript file named embedded.js into an external website. This script is a lightweight wrapper for the Runtime API, providing a simple interface to authenticate, initialize, and render Unqork modules. After loading the file, the Unqork application is ready to be displayed on the external website.

The embedded.js file is the entry point script that is fetch by an external application. This script exposes the runtime interface, enabling Creators to create and control the rendering of an Unqork application.

The Unqork Vega (2.0) runtime is required for Embedded UI.

Embedded UI is currently in open beta. Please contact your Unqork representative for more details and access.

Embedding the embedded.js File And Exposing the Runtime Interface

To embed the embedded.js file, insert the following into the host application's HTML file: <script src="https://<unqork-express-environment>/embedded.js?runtimeId=myRuntime"></script>, where <unqork-express-environment> is the name of your Unqork express environment. For example, <script src="https://trainingx.unqork.io/embedded.js?runtimeId=myRuntime"></script>.

After embedding, the runtime interface can be exposed in the following ways:

• Default: const runtime = window.unqork.runtimes.default;

• Named Runtime: If you specify a runtimeId query parameter in the URL, you can access the runtime instance by its ID: const runtime = window.unqork.runtimes.myRuntime;

In addition to the unqork object, the embedded.js script also adds a makeUnqorkApi function to the window object. This function is for more advanced use cases, letting you manually create and manage additional runtime instances.

The embedded.js script requires the two global variables listed above. Other frameworks that  manipulate or control the window object—for example, the Single SPA framework— might cause conflicts from incompatibility with the Embedded UI framework. Due to this potential incompatibility, developers might need to create additional custom code to achieve integration.

Embedding Multiple Runtimes

By default, you can embed multiple modules using the same runtime instance. Because they share the same runtime, they also share the same application state and data, effectively functioning as a single web application.

However, if you need to create a separate application state for each module,  specify a unique runtimeId query parameter. Each runtime instance created using this method has its own independent state and data.

Understanding the embedded.js Interface

The embedded.js interface consists of the following:

interface EmbededRuntime {
  constructor({ runtimeId, hostUrl }): EmbededRuntime
  getSamlEntrypointUrl(idp: string): string
  getOidcEntrypointUrl(op: string): string
  getLoginEntrypointUrl(): string
  authenticateReferString(referString: string): Promise<void>
  authenticateAnonymous({ moduleId }): Promise<void>
  isAuthenticated(): Promise<boolean>
  waitForAuthFrameCompletion(authFrame): Promise<void>
  initialize({ httpWithCredentials = true, application = {} }): Promise<void>
  mountModule({ moduleId, target, style }): Promise<EmbeddedModule>
  start(): void
}

Methods of the embedded.js Interface

Line 3:

getSamlEntrypointUrl(idp: string): string

Creates an entry point URL for SAML authentication. The URL is used in popup windows or iframes to authenticate end-users into the Unqork environment.

Returns: The SAML entrypoint URL.

Args

• idp: Represents the information that you retrieve from the identity provider

For more information on configuring SAML authentication, view our Unqork as a SAML Service Provider article.

For example:

const entrypoint = runtime.getSamlEntrypointUrl('my-idp')

Line: 4:

getOidcEntrypointUrl(op: string): string

Creates an entry point URL for OIDC authentication. The URL is used in popup windows or iframes to authenticate end-users into the Unqork environment.

Returns: The OIDC entrypoint URL.

Args

• op: The unique identifier of the identity provider.

For more information on configuring OIDC authentication, view our OpenID Connect (OIDC) article.

For example:

const entrypoint = runtime.getOidcEntrypointUrl('my-op')

Line 5:

getLoginEntrypointUrl(): string

Creates an entrypoint URL with the Unqork authentication method.

Returns: The Unqork authentication URL.

const entrypoint = runtime.getLoginEntrypointUrl()

Line 6:

authenticateReferString(referString: string): Promise<void>

Authenticates end-users into the Unqork environment using a refer string. This string is generated by the Unqork Customer API /referstring endpoint.

Returns: A promise that resolves when the user has been authenticated.

Args

• referString: The unique string used for authentication.

For example:

await runtime.authenticateReferString('my-refer-string')

Line 7:

authenticateAnonymous({ moduleId }): Promise<void>

Authenticates an end-user into the Unqork environment using an anonymous session. Doing so enables view access only to modules available for anonymous users.

Returns: A promise that resolves when the anonymous session establishes.

Args

• AuthenticateOptions: OBJECT

  •  moduleId: The unique identifier of the module to access anonymously.

For example:

await runtime.authenticateAnonymous({ moduleId }): Promise<void>

Line 8: 

isAuthenticated(): Promise<boolean>

Checks if the end-user is authenticated in the Unqork environment.

Returns: A promise that resolves to true if the user is authenticated.

For example:

const isAuthenticated = await runtime.isAuthenticated()

Line 9:

waitForAuthFrameCompletion(authFrame: WindowProxy): Promise<void>

Check if the user is successfully authenticated in the Unqork environment. This method is useful as an asynchronous authentication method (for iframes or pop-up windows), as it allows the host application to await a successful login before rendering the embedded Unqork application.

Returns: A promise that resolves when authentication in the frame is complete.

Args

•  authFrame: A reference to the iframe or pop-up window object.

  • To learn more about window objects, view the following documentation: https://developer.mozilla.org/en-US/docs/Glossary/WindowProxy.

For example:

const authFrameElement = document.createElement('iframe')
// ...initialize iframe here
// Waits for an authentication frame to complete.
await runtime.waitForAuthFrameCompletion(authFrameElement.contentWindow)

Line 10:

initialize({ httpWithCredentials = true, application = {} }?: InitializeOptions): Promise<void>

Loads the necessary JavaScript bundles for the runtime, and prepares or initializes the runtime SDK.

This line should only be called once.

Returns: A promise that resolves when initialization is complete.

Args

• InitializeOptions: OBJECT OPTIONAL

  • httpWithCredentials: If true, will include credentials for every HTTP request made to the Unqork back-end.

    By default, this value is true.

• application:  OBJECT Contains Unqork application data.

  • id: The unique identifier of the Unqork application.

  • version: The version of the Unqork application.

For example:

await runtime.initialize()

Line 11:

mountModule({ moduleId, target, style }: MountOptions): Promise<EmbeddedModule>

Given a target element, this method creates a web component wrapper and bootstraps the Unqork application. The web component wrapper uses a Shadow DOM to create a separate context, ensuring that styles do not conflict with the host application. This method can be used to render multiple modules for different targets using the same runtime.

Returns: A promise that resolves to an EmbeddedModule instance.

Args

• MountOptions: OBJECT

  • moduleId: The unique identifier of the Unqork module.

  • target:  The name of the custom element to use as the mount target. For example, 'mod-1'.

  • style: OPTIONAL The name of a CSS stylesheet to apply. For example, 'embeddedDemo'.

For example:

await runtime.mountModule({
target: 'mod-1',
moduleId: '654bd77da2f5afd918d9abe6',
style: 'embeddedDemo'
})

Line 12: 

start(): void

Begins the runtime and renders all modules that have been mounted. This method should only be called once after Line 11: mountModule({ moduleId, target, style }: MountOptions): Promise<EmbeddedModule>.

Resources

Introduction to the Embedded User Interface (UI)

Learn how the Embedded UI feature works and discover frequently asked questions (FAQ).

How to: Embed Unqork in an External Application

View the methods that enable you to interact with an Unqork module in real time

Understand the EmbeddedModule Interface

View the methods that enable you to interact with an Unqork module in real time

Examples of Embedded UI Modules

Discover examples of the embedded single or multi-modules