Embedded UI Public API Reference

The Embedded UI Public API is a JavaScript API that loads onto the host page when you embed an Unqork module. It exposes a window.unqork namespace with methods for mounting modules and workflows, authenticating users, and managing module lifecycle. This reference documents all public methods, events, and global flags.

Note: If you previously used the Vega embedded.js API, note the following changes in Centauri: runtime.start() is no longer required after mounting. The EmbeddedModule interaction interface (on(), send(), get(), swapModule()) has been replaced by IframeAPI, which is available when mounting with iframe: true. Workflow embedding is now supported through mountWorkflow().

window.unqork

When the Embedded UI script loads, it creates a window.unqork namespace on the host page. This namespace holds the runtime instances the API uses for all operations. The type definition below shows the top-level shape.

interface UnqorkGlobal {
  runtimes: {
    [runtimeId: string]: UnqorkRuntime
  }
}

The default runtime is accessible at window.unqork.runtimes.default.

UnqorkRuntime

The UnqorkRuntime object is the main interface for embedding Unqork content. After loading the Embedded UI script, you access it at window.unqork.runtimes.default. All mounting, authentication, and lifecycle operations are methods on this object.

Lifecycle

Call initialize() once before any other API calls. It loads the Angular application bundle and sets up the runtime environment.

Field: initialize() | Type: Method | Returns: Promise<void>

Initializes the runtime instance. Must be called before mounting any modules.

Module Mounting

Use mountModule() to embed a single Unqork module into the host page. The module renders inside a Shadow DOM web component, which keeps its styles isolated from the host page's CSS. Pass iframe: true to embed the module in a sandboxed iframe instead. In that case, the method returns an IframeAPI object rather than an HTMLElement.

Field: mountModule(options) | Type: Method | Returns: Promise<HTMLElement | IframeAPI>

Mounts a single Unqork module into the host page. Returns an IframeAPI when iframe is set to true.

Workflow Mounting

Use mountWorkflow() to embed a multi-step workflow instead of a single module. A workflow is an ordered sequence of modules with navigation, submission persistence, and step progress indicators.

Field: mountWorkflow(options) | Type: Method | Returns: Promise<HTMLElement>

Mounts a workflow (multi-step sequence of modules) into the host page.

Authentication Methods

These methods handle user authentication before or after mounting a module. Call isAuthenticated() first to check whether the current session is already active. Then use the method that matches your authentication setup.

Field: isAuthenticated() | Type: Method | Returns: Promise<boolean>

Returns true if the current session is authenticated (through /auth/me).

Field: authenticateAnonymous(options) | Type: Method | Returns: Promise<void>

Authenticates anonymously through /auth/customAuth. Use this for public-facing modules that do not require a login.

Field: authenticateReferString(referString) | Type: Method | Returns: Promise<void>

Authenticates using a refer string through /auth/refer.

Field: getSamlEntrypointUrl(idp) | Type: Method | Returns: string

Returns the SAML redirect URL for the specified identity provider. Use with an iframe or popup window for SAML-based authentication.

Field: getOidcEntrypointUrl(op) | Type: Method | Returns: string

Returns the OIDC redirect URL for the specified OpenID Connect provider.

Field: getLoginEntrypointUrl() | Type: Method | Returns: string

Returns the login form URL for iframe-based authentication.

Field: waitForAuthFrameCompletion(iframe) | Type: Method | Returns: Promise<void>

Returns a promise that resolves when the authentication iframe completes its flow.

Field: onAuthComplete(callback) | Type: Method | Returns: () => void

Registers a callback that fires when in-embed login completes. Returns an unsubscribe function.

Module Management

Use reloadModule() to refresh a module that is already mounted, for example after authentication completes and the module needs to reload with the authenticated user's context.

Field: reloadModule(moduleId) | Type: Method | Returns: Promise<void>

Reloads an already-mounted module. Useful after authentication completes.

Custom Events

The Embedded UI dispatches custom browser events on window during key lifecycle moments. Listen for these using window.addEventListener('eventName', handler). The event.detail property contains the event payload.

Global Flags

The Embedded UI script sets several global properties on the host page's window object. Some are set automatically at startup; others are optional callbacks the host page can define before mounting.

IframeAPI - Return Value of mountModule() with iframe: true

When calling mountModule() with iframe: true, the module renders inside a sandboxed iframe rather than a Shadow DOM web component. In this mode, the method returns an IframeAPI object instead of an HTMLElement. This object lets you read and write data inside the iframe from the host page.

Data Access

These methods let the host page read and write data inside the mounted iframe module.

Actions

These methods trigger actions inside the mounted iframe module from the host page.

Events

These methods let the host page subscribe to and unsubscribe from events emitted by the iframe module.

Supported Events through api.on()

The table below lists the events available to subscribe to through api.on().

Lifecycle

Use unmount() to remove the iframe and clean up all event listeners when the module is no longer needed.

Error Payload Shape

Every error dispatched through the unqork-embed-error event or bridge handler includes the following base fields. Additional fields depend on the error type. For full per-type payload details, see the Embedded UI Error Surfacing Reference.

Base Fields

Per-Type Fields