Universal/HTML Applications

Universal Applications are HTML applications that are platform agnostic, but require a platform specific Web App Wrapper to launch. When an application is setup as a Universal Application in the Experience Manager, it activates additional features with the Manager to support delivering the Universal Application.

The primary feature enabled is when a Univeral Application is added to a Node Template, the Web App Wrapper is automatically added to the template. This enables the Experience Agent to serve the Universal Application using the Web App Wrapper. When run via the Experience Agent, Universal Applications will also be server via the Agents built in web server.

Control Panels

One of the use cases for Universal Applications is serving Control Panels for the Control Gateway.

When a Universal Application is configured as a Control Panel, it will automatically be unbundled and served via the Experience Manager allowing Control Panels to interact with the Control Gateway directly from the Experience Manager.

Development Considerations

To fully utilize the Experience Manager and Agent, Universal Application will some additional configuration to work properly in different contexts.

Examples below are for Vue/Vite, but the concepts apply to other Javascript frameworks such as React.

Application Environment

When building an application integrated with the Experience Manager such as a Control Panel, the application will typically load environment variables from the Experience Agent using the Node Environment API endpoint.

When a Universal application is served from the Experience Manager, it will not have access to Experience Agent API's, but will likely still need access to information such as MQTT credentials typically provided as environment variables.

To work around this, an ./environment.json file is provided and served with you application bundle. This is a truncated set of variables, information such a Node details will not be included since the application is not hosted on a Node and credentials such as MQTT will be scoped to the user instead of the Node.

To simplify switching, your application will be loaded with the?xmanager= query parameter.

For example:

const is_xmanager = window.location.search.includes('xmanager=')
const response = await fetch(is_xmanager ? './environment.json' : 'http://127.0.0.1:8002/node/environment/')
const env = await response.json()

When the environment is read from a JSON file, rather then the environment, variables will be provided as key/value pairs:

{
    "AGENT_HOST": "http://localhost:8002",
    ...
}

See: Environment Variables

Relative Asset Paths

By default, many Javascript frameworks serve dependencies (CSS, Javascript) from root absolute paths. For examples /assets/css/index.css or /assets/js/index.js.

This works well when the application is hosted as the root page in a domain (i.e. https://example.com/index.html), but the depecdencies do not resolve when hosted in a sub-folder (i.e. https://example.com/bundle/x/index.html).

To ensure your dependencies load, the base loading path should be set to be relative to your bundle root. For example, this is done by setting base to ./ in your vite.config.js file for Vite/Vue applications:

export default defineConfig({
    base: './',
})

Push State Routing