--- title: "Embedded UI: Understanding the embedded.js File" slug: "embedded-ui-understanding-the-embeddedjs-file" updated: 2025-09-26T06:40:26Z published: 2025-09-26T06:40:26Z canonical: "docs.unqork.io/embedded-ui-understanding-the-embeddedjs-file" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.unqork.io/llms.txt > Use this file to discover all available pages before exploring further. # Embedded UI: Understanding the embedded.js File > [!WARNING] > The Embedded UI feature is intended for developers who have a strong understanding of the Unqork Designer Platform and JavaScript. ## Overview Embedded UI works by inserting a JavaScript file named `embedded.js` into an external website. This script is a lightweight wrapper for the Runtime API, providing a simple interface to authenticate, initialize, and render Unqork modules. After loading the file, the Unqork application is ready to be displayed on the external website. The `embedded.js` file is the entry point script that is fetch by an external application. This script exposes the runtime interface, enabling Creators to create and control the rendering of an Unqork application. The runtime is required for Embedded UI. > [!NOTE] > Embedded UI is currently in open beta. Please contact your Unqork representative for more details and access. ## Embedding the `embedded.js` File And Exposing the Runtime Interface To embed the `embedded.js` file, insert the following into the host application's HTML file: `<script src="https://<unqork-express-environment>/embedded.js?runtimeId=myRuntime"></script>`, where is the name of your Unqork express environment. For example, `<script src="https://trainingx.unqork.io/embedded.js?runtimeId=myRuntime"></script>`. After embedding, the runtime interface can be exposed in the following ways: - **Default**: `const runtime = window.unqork.runtimes.default;` - **Named Runtime**: If you specify a `runtimeId` query parameter in the URL, you can access the runtime instance by its ID: `const runtime = window.unqork.runtimes.myRuntime;` In addition to the `unqork` object, the `embedded.js` script also adds a `makeUnqorkApi` function to the `window` object. This function is for more advanced use cases, letting you manually create and manage additional runtime instances. > [!WARNING] > The `embedded.js` script requires the two global variables listed above. Other frameworks that manipulate or control the `window` object—for example, the Single SPA framework— might cause conflicts from incompatibility with the Embedded UI framework. Due to this potential incompatibility, developers might need to create additional custom code to achieve integration. #### Embedding Multiple Runtimes By default, you can embed multiple modules using the same runtime instance. Because they share the same runtime, they also share the same application state and data, effectively functioning as a single web application. However, if you need to create a separate application state for each module, specify a unique `runtimeId` query parameter. Each runtime instance created using this method has its own independent state and data. ## Understanding the `embedded.js` Interface The `embedded.js` interface consists of the following: ```typescript interface EmbededRuntime {  constructor({ runtimeId, hostUrl }): EmbededRuntime  getSamlEntrypointUrl(idp: string): string  getOidcEntrypointUrl(op: string): string  getLoginEntrypointUrl(): string  authenticateReferString(referString: string): Promise  authenticateAnonymous({ moduleId }): Promise  isAuthenticated(): Promise  waitForAuthFrameCompletion(authFrame): Promise  initialize({ httpWithCredentials = true, application = {} }): Promise  mountModule({ moduleId, target, style }): Promise  start(): void } ``` ### Methods of the `embedded.js` Interface #### Line 3: `getSamlEntrypointUrl(idp: string): string` Creates an entry point URL for SAML authentication. The URL is used in popup windows or iframes to authenticate end-users into the Unqork environment. **Returns**: The SAML entrypoint URL. ##### Args - `idp`: Represents the information that you retrieve from the identity provider > For more information on configuring SAML authentication, view our [Unqork as a SAML Service Provider](/v1/docs/unqork-as-a-saml-service-provider) article. For example: ```javascript const entrypoint = runtime.getSamlEntrypointUrl('my-idp') ``` #### Line: 4: `getOidcEntrypointUrl(op: string): string` Creates an entry point URL for OIDC authentication. The URL is used in popup windows or iframes to authenticate end-users into the Unqork environment. **Returns**: The OIDC entrypoint URL. ##### Args - `op`: The unique identifier of the identity provider. > For more information on configuring OIDC authentication, view our [OpenID Connect (OIDC)](/v1/docs/openid-connect-oidc) article. For example: ```javascript const entrypoint = runtime.getOidcEntrypointUrl('my-op') ``` #### Line 5: `getLoginEntrypointUrl(): string` Creates an entrypoint URL with the Unqork authentication method. **Returns**: The Unqork authentication URL. ```javascript const entrypoint = runtime.getLoginEntrypointUrl() ``` #### Line 6: `authenticateReferString(referString: string): Promise<void>` Authenticates end-users into the Unqork environment using a refer string. This string is generated by the [Unqork Customer API](https://developers.unqork.io/#operation/generateReferString) `/referstring` [endpoint](https://developers.unqork.io/#operation/generateReferString). **Returns**: A promise that resolves when the user has been authenticated. ##### Args - `referString`: The unique string used for authentication. For example: ```javascript await runtime.authenticateReferString('my-refer-string') ``` #### Line 7: `authenticateAnonymous({ moduleId }): Promise<void>` Authenticates an end-user into the Unqork environment using an anonymous session. Doing so enables view access only to modules available for anonymous users. **Returns**: A promise that resolves when the anonymous session establishes. ##### Args - `AuthenticateOptions`: OBJECT - `moduleId`: The unique identifier of the module to access anonymously. For example: ```javascript await runtime.authenticateAnonymous({ moduleId }): Promise ``` #### Line 8: `isAuthenticated(): Promise<boolean>` Checks if the end-user is authenticated in the Unqork environment. **Returns**: A promise that resolves to `true` if the user is authenticated. For example: ```javascript const isAuthenticated = await runtime.isAuthenticated() ``` #### Line 9: `waitForAuthFrameCompletion(authFrame: WindowProxy): Promise<void>` Check if the user is successfully authenticated in the Unqork environment. This method is useful as an asynchronous authentication method (for or pop-up windows), as it allows the host application to await a successful login before rendering the embedded Unqork application. **Returns**: A promise that resolves when authentication in the frame is complete. ##### Args - `authFrame`: A reference to the iframe or pop-up window object. > - To learn more about window objects, view the following documentation: [https://developer.mozilla.org/en-US/docs/Glossary/WindowProxy](https://developer.mozilla.org/en-US/docs/Glossary/WindowProxy). For example: ```javascript const authFrameElement = document.createElement('iframe') // ...initialize iframe here // Waits for an authentication frame to complete. await runtime.waitForAuthFrameCompletion(authFrameElement.contentWindow) ``` #### Line 10: `initialize({ httpWithCredentials = true, application = {} }?: InitializeOptions): Promise<void>` Loads the necessary JavaScript bundles for the runtime, and prepares or initializes the runtime SDK. > [!WARNING] > This line should only be called once. **Returns**: A promise that resolves when initialization is complete. ##### Args - `InitializeOptions`: OBJECT OPTIONAL - `httpWithCredentials`: If `true`, will include credentials for every HTTP request made to the Unqork back-end. By default, this value is `true`. - `application`: OBJECT Contains Unqork application data. - `id`: The unique identifier of the Unqork application. - `version`: The version of the Unqork application. For example: ```javascript await runtime.initialize() ``` #### Line 11: `mountModule({ moduleId, target, style }: MountOptions): Promise<EmbeddedModule>` Given a target element, this method creates a web component wrapper and bootstraps the Unqork application. The web component wrapper uses a Shadow DOM to create a separate context, ensuring that styles do not conflict with the host application. This method can be used to render multiple modules for different targets using the same runtime. **Returns**: A promise that resolves to an `EmbeddedModule` instance. ##### Args - `MountOptions`: OBJECT - `moduleId`: The unique identifier of the Unqork module. - `target`: The name of the custom element to use as the mount target. For example, `'mod-1'`. - `style`: OPTIONAL The name of a CSS stylesheet to apply. For example, `'embeddedDemo'`. For example: ```javascript await runtime.mountModule({ target: 'mod-1', moduleId: '654bd77da2f5afd918d9abe6', style: 'embeddedDemo' }) ``` #### Line 12: `start(): void` Begins the runtime and renders all modules that have been mounted. This method should only be called once after Line 11: `mountModule({ moduleId, target, style }: MountOptions): Promise<EmbeddedModule>`. ## Resources ### [Introduction to the Embedded User Interface (UI)](/v1/docs/introduction-to-the-embedded-user-interface-ui) Learn how the Embedded UI feature works and discover frequently asked questions (FAQ). ### [How to: Embed Unqork in an External Application](/v1/docs/embedded-ui-understanding-the-embeddedmodule-interface) View the methods that enable you to interact with an Unqork module in real time ### [Understand the EmbeddedModule Interface](/v1/docs/embedded-ui-understanding-the-embeddedmodule-interface) View the methods that enable you to interact with an Unqork module in real time ### [Examples of Embedded UI Modules](/v1/docs/embedded-ui-understanding-the-embeddedmodule-interface) Discover examples of the embedded single or multi-modules JavaScript is an object-oriented computer programming language. It is most-commonly used for interactive effects in the browser. APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services. Fetching is the process of retrieving data from a database, making it available to the application and the end-user. Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform. Security Assertion Markup Language (SAML) is a protocol that allows an identity provider (IdP) to send a user's credentials to a service provider (SP) to verify their identity and grant them access to a service. 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. OIDC (OpenID Connect) is an identity authentication protocol that lets two applications share user information without exposing user credentials. 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. HTTP (Hypertext Transfer Protocol) is an application-layer protocol used to transmit hypermedia documents like HTML. The Shadow DOM is a web standard that allows you to create encapsulated, hidden DOM subtrees for your web components. It provides a way to scope CSS styles and JavaScript behavior within a component, preventing them from leaking out and interfering with the rest of the page. Cascading Style Sheets (CSS) is a style sheet language used for presenting how a HTML or XML document looks to end-users.