Embedded UI How To: Embed Unqork in an External Application

The Embedded UI feature is intended for developers who have a strong understanding of the Unqork Designer Platform and JavaScript JavaScript is an object-oriented computer programming language. It is most-commonly used for interactive effects in the browser..

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.

A static image displaying the additional of a location in the Allowed Origins List field in Environment Administration.

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:

Copy 
const runtime = window.unqork.runtimes.default;

Initialize Runtime

This step initializes the Unqork runtime instance.

1. Run the following keyword operator:
Copy 
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:

For more details on authentication methods, view our Embedded User Interface (UI): 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:

Copy 
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 The Document Object Model (DOM) is the data representation of objects that form the structure and content of a document on the web. The DOM represents the page. 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:
Copy 
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 Express View is how your end-user views your application. Express View also lets you preview your applications to test your configuration and view the styling. This is also the view your end-users will see when interacting with your application. After configuring a module, click Preview in the Module Builder to interact with the module in 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 User Interface (UI): embedded.js File article.

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

Copy 
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.