Embedded UI How To: Embed Unqork in an External Application

Updated
  • Updated on Sep 26, 2025
  • Published on Sep 26, 2025
  • 4 minute(s) read
Prev Next

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

Overview

Learn how to embed an Unqork application or module into an external website or application using the Embedded UI feature.

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

Enabling and Embedding the Unqork User Interface

To enable and embed an Unqork User Interface, you'll do the following:

  1. Enable the Cross-Orgin Resource Sharing (CORS) setting.

  2. Insert the embedded.js file into the host application.

  3. Initialize the Unqork runtime.

  4. Authenticate Users.

  5. Mount an Unqork module.

  6. (Optional) Build Interactions With the Unqork Module.

Learn more about each step below.

Enable Cross-Origin Resource Sharing (CORS)

First, grant Unqork access to the host application or website. This is an important security step that prevents other applications from accessing your Unqork application.

  1. At the top right of the Unqork Designer Platform, click Administration.

  2. Under Environment, select Environment Administration.

  3. Scroll down to the Cross-Origin Resource Sharing (CORS) section.

  4. In the Allowed Origins List field, enter the location(s) where you want to embed your content.

    Enter commas to separate more than one location. For example, https://example1.com, https://example2.com.

Insert embedded.js Into the Host Application.

Next, add the JavaScript file in the host application's HTML <head> section. The most common way to achieve this task is by adding a script tag into the HTML page.

In the host application:

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

After loading the file, all the necessary functionality becomes available on the global window.unqork object. You can access the default runtime instance using the following declaration:

const runtime = window.unqork.runtimes.default;

Initialize Runtime

This step initializes the Unqork runtime instance.

  1. Run the following keyword operator:

    await runtime.initialize()

    The await keyword must be used in an async function and cannot be used in the top-level scope.

Authenticate Into the Unqork Environment

For the Unqork application to render and communicate with the platform, a valid authentication session is required. The EmbeddedRuntime provides several authentication methods:

  • SAML                                                

  • OIDC                                                

  • Unqork Login

  • Unqork Refer Auth

  • Anonymous

For more details on authentication methods, view our Embedded UI: Understanding the embedded.js File article.

Here's an example of how to check for an existing session and initiate SAML authentication if the user is not logged in:

if (!await runtime.isAuthenticated()) {
  const entrypointUrl = runtime.getSamlEntrypointUrl('https://example.com')
  const link = document.createElement('a')
  link.style='cursor:pointer'
  link.innerText = 'You are not logged in. Click here to log in using My IdP.'
  document.getElementsByTagName('auth')[0].appendChild(link)
  const authFrame = await new Promise(resolve => {
    link.onclick = () => resolve(window.open(entrypointUrl, 'popup', 'popup=true'))
  })
  await runtime.waitForAuthFrameCompletion(authFrame)
  authFrame.close()
  link.remove()
}

Mount the Unqork Application

After authentication, create a DOM element in your HTML page to serve as the mount target for the Unqork application. This element must be a valid custom tag.

  1. In the HTML of the host application, insert a valid custom tag. For example, <unqork-app></unqork-app>.

  2. Use the mountModule() method to insert the Unqork application and render it:

    const module = await runtime.mountModule({
  // Your custom element to target and display the module.
  target: 'unqork-app',
  // The module's module ID.
  moduleId: '654bd77da2f5afd918d9abe6',
  // Add an optional style to override the default style.
  style: 'style1'
})
// Start the runtime.
start()

The Unqork module's Express View displays in the host application or browser.

(Optional) Build Interactions With the Unqork Module

Once the module renders, developers can interact with it in real time using the EmbeddedModule interface. This allows developers to retrieve data from the module or trigger actions in it to achieve the desired behavior.

For a full list of available methods, view our Embedded UI: Understanding the embedded.js File article.

Here's an example of how to send data to a module's components:

interface EmbeddedModule {
  moduleId: string
  ready(callback: () => void): Promise<void>
  on(event: EventType | RuntimeDataUpdatedEvent, callback: (eventData?: any) => void): void
  send(event: "submission_data" | "operation", data: unknown, context?: any): Promise<void>
  get(data: RuntimeDataType): any
  validate(): Promise<void>
  swapModule(module: AnyModuleDefinition, submissionData?: SubmissionData): Promise<void>
  registerSubmissionHandler(handler: ModuleSubmissionHandler): void
  unregisterSubmissionHandler(): void
  registerValidationHandler(handler: ModuleValidationHandler): void
  unregisterValidationHandler(): void
  removeSubscriptions(): void
  destroy(): Promise<void>
}

Resources

Introduction to the Embedded User Interface (UI)

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

Understand the embedded.js File

Review the script that embeds the runtime API into an external application web page

Understand the EmbeddedModule Interface

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

Related articles