Embedded User Interface (UI)

Estimated Reading Time:  6 minutes

NOTE  Enhancements to Unqork's Embedded UI are underway for a full 7.2.0 release. Visit this article regularly to explore the new enhancements to this feature.

Overview

With Unqork's Embedded User Interface (UI), you can embed content outside Unqork while avoiding the security and usability issues associated with iframes. If you've created a page in another ecosystem outside Unqork, the Embedded UI feature lets you take reusable Unqork applications and embed them onto your page.

Inline frames or iframes An inline frame (or iframe) is an HTML element that loads another HTML page, essentially adding another page inside the parent page. are commonly used to embed content from one site into another. Using the HTML <iframe> element, you can embed videos, images, maps, and so on. While this process can provide a seamless user experience, iframes have many disadvantages.

What You'll Learn

In this article, you'll learn about Unqork's Embedded UI and how to embed content outside of Unqork.

Iframe Disadvantages

Various issues with iframes prevent many Creators Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform. from using them. These include:

Security Issues

Iframes are susceptible to XSS Cross Site Scripting attacks vulnerability used by malicious entities to bypass the access controls of a website. (cross-site scripting) attacks. Bad actors A bad actor is a cybercriminal or organization that might attempt to exploit vulnerabilites in your environment or application. Common exploits used by bad actors include XSS (cross-site scripting) attacks, malware, randsomware, and more. can perform XSS attacks and change the source site URL, install malware Malware is software designed to disrupt, damage, or gain access to a computer system., steal information, or hijack clicks and keystrokes.

Page Loads

Iframes are considered a separate page from the one they are embedded in. Most browsers load the page and then identify if an iframe exists. The result is slower page loads and site conversions. If you use Google Analytics, it also does not track the page load because of how they are loaded.

Usability Issues

Iframes tend to break navigation inside and outside the iframe. The embedded content can also break if it does not fit inside the iframe.

Device Accessibility

While a page might have a responsive layout, iframes do not. Without responsiveness, iframes interrupt the end-user End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product. experience when viewed on tablets and smartphones.

SEO Issues

Many search engines do not index iframes, affecting SEO Search Engine Optimization (SEO) is the process used to improve a website's content relevance and techical configuration. Search Engines rank public websites based on their SEO performance and popularity. (search engine optimization). Iframes are considered a different page from the one being viewed.

Embedded UI Advantages

The advantage of using Unqork's Embedded UI feature is that you do not experience the same limitations and security risks as iframes. Advantages include:

Seamless End-User Experience

Embed applications picture-to-picture, avoiding iframe limitations and risks to improve the end-user's End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product. experience.

Reusable Applications

Configure reusable applications that you can embed across multiple pages and domains. All application instances can share the configuration.

Unqork Functionality Outside Unqork

Embed applications containing workflows, integrations, and logic outside of Unqork. These applications then function as they would in Unqork.

Incremental Legacy Reconfiguration

Embedded UI lets you build and embed smaller applications immediately while incrementally reconfiguring your large legacy applications to be codeless.

Embedded UI Considerations

When embedding assets using Unqork's Embedded UI, there are a few considerations to keep in mind. While you can embed both module and workflow-type applications outside Unqork, Embedded UI is only supported on the Vega runtime engine. Vega is the software that powers your Unqork applications. It runs on the back-end to execute your modules, workflows, components, Data Workflow operators, and so on. Powering Embedded UI with Vega ensures you leverage the best performance and efficiency while modernizing your enterprise-grade applications.

TIP  To learn more about Unqork's Vega runtime engine, view our Welcome to Vega course in Academy.

Using Embedded UI Outside Unqork

Unqork's Embedded UI is intended for Creators Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform. with coding and JavaScript JavaScript is an object-oriented computer programming language. It is most-commonly used for interactive effects in the browser. experience. There are six necessary steps to embed content using Embedded UI.

1. Identify the parent page where you want to embed your Unqork modules and workflows.
2. Enter one or more locations where you want to embed content in Unqork's Environment Administration.
3. Define a custom Web Component tag to act as a target to embed your content.
4. Load the Vega runtime.
5. Authenticate your end-users so they can view your content outside of Unqork.
6. Initialize, mount, and run the Vega runtime.

Cross-Origin Resource Sharing (CORS)

The first step is to access Environment Administration and enter the location where you want to embed your content.

To access the Environment Administration page:

1. At the top right of the Unqork Designer Platform, click Settings ▾.
2. Click Administration.
3. Under Environment, select Environment Administration.
4. Scroll down to the Cross-Origin Resource Sharing (CORS) section.
5. In the Allowed Origins List, enter the location(s) where you want to embed your content.

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

Defining a Web Component Tag

Next, you must define a custom Web Component tag to act as a target for Embedded UI. You can embed content anywhere on the page, including nested HTML tags. However, you cannot place it in an <iframe> element.

In the example below, the name of the Web Component tag is mod-1, but you can give your tag any name you want.

Copy 
<body>
<mod-1></mod-1>
</body>

Loading the Vega Runtime

To load the Vega runtime, you need to provide a script to load an Express View Javascript file. Examples of what that looks like are the following:

Copy 
<script src="https://<unqork-express-environment>/embedded.js"></script>
Copy 
<script src="https://<unqork-express-environment>/embedded.js?runtimeId=myRuntime"></script>

You also need to retrieve the Vega runtime. Depending on the format you used for your Javascript file, you can get the Vega runtime in the following ways:

Copy 
const runtime = unqork.runtimes.default
Copy 
const runtime = unqork.runtimes.myRuntime

Authenticating the Vega Runtime

How you authenticate end-users is up to you. We recommend only Creators with knowledge of coding configure the authentication method. Depending on your method of choice, you can use the following examples to authenticate.

Interactive Pop-Up Window

To authenticate an interactive pop-up window using SAML, OIDC, or a login screen, use the following syntax example. This method requires a SAML, OIDC, or login entry-point URL to retrieve a frame.

Copy 
const entrypointUrl = runtime.getSamlEntrypointUrl('my-idp') or // runtime.getOidcEntrypointUrl('my-op') or runtime.getLoginEntrypointUrl()
let authFrame
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('mod-1')[0].appendChild(link)

const authFrame = await new Promise(resolve => {
  link.onclick = () => resolve(window.open(entrypointUrl, 'popup', 'popup=true'))
})

// Waits for an authentication frame to complete.
await runtime.waitForAuthFrameCompletion(authFrame)
authFrame.close()

Interactive iFrame

To authenticate an interactive iframe using SAML, OIDC, or a login screen, use the following syntax example. This method requires a SAML, OIDC, or login entry-point URL to retrieve a frame.

IMPORTANT  This method requires you to enter the origin to the Frame Ancestor List field in Environment Administration.

Copy 
const entrypointUrl = runtime.getSamlEntrypointUrl('my-idp') or // runtime.getOidcEntrypointUrl('my-op') or runtime.getLoginEntrypointUrl()
const authFrameElement = document.createElement('iframe')
authFrameElement.src = entrypointUrl

document.getElementsByTagName('mod-1')[0].appendChild(authFrameElement)

// Waits for an authentication frame to complete.
await runtime.waitForAuthFrameCompletion(authFrameElement.contentWindow)
authFrameElement.remove()

Hidden iFrame

To authenticate a hidden iframe using SAML or OIDC, use the following syntax example. This method requires a SAML or OIDC entry-point URL to retrieve a frame. It's important to note that you'll use your Web Component tag in this authentication method. In this example, the Web Component tag is 'mod-1'.

IMPORTANT  This method requires you to enter the origin to the Frame Ancestor List field in Environment Administration.

Copy 
const entrypointUrl = runtime.getSamlEntrypointUrl('my-idp') or // runtime.getOidcEntrypointUrl('my-op')
const authFrameElement = document.createElement('iframe')
authFrameElement.src = entrypointUrl
authFrameElement.hidden = true

document.getElementsByTagName('mod-1')[0].appendChild(authFrameElement)

// Waits for an authentication frame to complete.
await runtime.waitForAuthFrameCompletion(authFrameElement.contentWindow)
authFrameElement.remove()

Non-Interactive Refer String

You can generate and use a refer string for your authentication method. Below is an example of authenticating end-users using a refer string.

TIP  To generate a refer string, use the following documentation: https://developers.unqork.io/#operation/generateReferString.

Copy 
const referString = 'my-refer-string'
await authenticateReferString(referString)

Non-Interactive Anonymous

You can also use an anonymous module to allow end-users to interact with your embedded content. Below is an example of authenticating end-users using an anonymous module.

Copy 
const moduleId = 'my-anonymous-module-ID'
await authenticateAnonymous({ moduleId })

Initializing, Mounting, and Running the Vega Runtime

After loading the Vega runtime and configuring your end-user authentication, the remainder of the code performs the core functions. These functions include initializing, mounting, and running the Vega runtime. Once complete, end-users can begin interacting with your embedded content.

Below is an example of these functions and their required attributes:

Copy 
// Initializes the Vega runtime.
await initialize()

// Mount your module.
await mountModule({
  // Your Web Component tag to target and display the module.
  target: 'mod-1',
  // The module's module ID.
  moduleId: '654bd77da2f5afd918d9abe6',
  // Add an optional style to override the default style.
  style: 'style1'
})

// Start the Vega runtime.
start()

Example: Embedding a Single Module

Below is an example of the completed configuration for embedding a single module into your external ecosystem:

Copy 
<auth></auth>
<mod-1></mod-1>
<script src="https://trainingx.unqork.io/embedded.js"></script>
<script type="module">
const runtime = unqork.runtimes.default

await runtime.initialize()

const isAuthenticated = await runtime.isAuthenticated()
if (!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()
}

await runtime.mountModule({
  target: 'mod-1',
  moduleId: '654bd77da2f5afd918d9abe6'
})
runtime.start()
</script>

Example: Embedding Multiple Modules

Below is an example of the completed configuration for embedding multiple modules into your external ecosystem:

Copy 
<auth></auth>
<mod-1></mod-1>
<mod-2></mod-2>
<script src="https://trainingx.unqork.io/embedded.js"></script>
<script type="module">
const runtime = unqork.runtimes.default

await runtime.initialize()

const isAuthenticated = await runtime.isAuthenticated()
if (!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()
}

await runtime.mountModule({
  target: 'mod-1',
  moduleId: '654bd77da2f5afd918d9abe6'
})
await runtime.mountModule({
  target: 'mod-2',
  moduleId: '659f521e9dec2e14895dc433'
})
runtime.start()
</script>

Resources