Embedded User Interface (UI)
Overview
With Unqork's Embedded User Interface (UI), you can embed content from Unqork to a non-Unqork application or website 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.
Iframe Disadvantages
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, Creators Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform. can embed videos, images, maps, and so on. While this process can provide a seamless user experience, various issues with iframes prevent many Creators 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.
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.
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.
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.
Unqork Functionality Outside Unqork
Embed applications containing integrations and logic outside of Unqork. These applications then function as they would in Unqork.
Reusable Applications
Configure reusable applications that you can embed across multiple pages and domains. All application instances can share the configuration.
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 module 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, components, Data Workflow operators, and so on. Powering Embedded UI with Vega The Vega (v 2.0.0) runtime is the next-generation engine of the UDesigner platform. Vega uses cutting-edge technologies to improve the Creator and end-user experience. ensures you leverage the best performance and efficiency while modernizing your enterprise-grade applications.
To learn more about Unqork's Vega runtime, view our Introduction to Vega article.
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. |
| 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 The Vega (v 2.0.0) runtime is the next-generation engine of the UDesigner platform. Vega uses cutting-edge technologies to improve the Creator and end-user experience. 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 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.
Defining a Web Component Tag
Next, 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.
<body>
<mod-1></mod-1>
</body>
Loading the Vega Runtime
To load the Vega runtime, provide a script to load an Express View Javascript file. Examples of what that looks like are the following:
<script src="https://<unqork-express-environment>/embedded.js"></script><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 The Vega (v 2.0.0) runtime is the next-generation engine of the UDesigner platform. Vega uses cutting-edge technologies to improve the Creator and end-user experience. runtime in the following ways:
|
Copy
|
Copy
|
Authenticating the Vega Runtime
How you authenticate end-users 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. is up to you. We recommend only Creators Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform. 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.
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.
This method requires you to enter the origin to the Frame Ancestor List field in Environment Administration.
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'.
This method requires you to enter the origin to the Frame Ancestor List field in Environment Administration.
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.
To generate a refer string, use the following documentation: https://developers.unqork.io/#operation/generateReferString.
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.
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:
// 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()Examples of Embedded Modules
Click on the tabs below to view completed configurations of single or mutli-module embeds:
Example: Embedding a Single Module
Below is an example of the completed configuration for embedding a single module into your external ecosystem:
<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:
<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
