Skip to main content

Create a third-party Clea Portal App

The Platform supports loading external web apps that can be developed by third-party actors.

A Clea Portal App consists of an external web application encapsulated within Clea Portal as a shadow DOM.

The App is viewable in any appliance depending on its compatibility with supported Astarte interfaces. When it comes to authentication and data collection, it requires interaction with Astarte APIs.

Requirements

To ensure interoperability with the Platform, an app must meet the following criteria:

  1. Availability: the app is made available at a public URL as a single JavaScript file bundle;
  2. Bundle format: the app’s bundle must be a JavaScript ES Module;
  3. Bundle content: the default export of the app must be an object to handle the app’s lifecycle. More on this later.

Availability

The app must be accessible at a public URL and served with appropriate CORS configuration in order to be fetched from the Platform web app.

Bundle format

The app must be a single file bundle that can be parsed as an ES Module.

Bundle content

The app’s bundle must have a default export with the following object structure, using TypeScript signatures:

{
mount: (
container: HTMLElement,
props: AppProps,
settings: Settings
) => void;
unmount: (container: HTMLElement) => void;
}

where:

  • mount is a synchronous function that will be called to instantiate the app inside a Platform’s page. container is the DOM element within which the app must render itself, while props and settings are objects supplied by the Platform. Read the dedicated paragraph below for further details about the props and settings objects.
  • unmount is a synchronous function that will be called to dispose of the app’s instance, if any cleanup should be done. container is the DOM element where the app was instantiated on.

These lifecycle methods are intended to be lightweight and should return quickly. If the app requires a long setup, that should be handled separately.

App props

Upon mount, the app will be provided with a props object that has the following type signature:

type AppProps = {
astarteUrl: URL;
realm: string;
token: string;
deviceId: string;
}

Thus you will have access to the following parameters:

  • astarteUrl is a URL object pointing to an Astarte instance.
  • realm refers to the Astarte realm.
  • token is the authentication token to access Astarte services.
  • deviceId refers to the Astarte device ID used also as Clea unique identifier.

The Astarte token grants permissions to access Astarte services in order to query for interface data on the device with ID deviceId. You can look at Astarte’s documentation to know about querying a device or the REST API reference.

Settings

The settings object contains data to have a congruent experience with Clea

type Settings = {
themeUrl: string;
userPreferences: UserPreferences;
}

type UserPreferences = {
language: string;
};
  • themeUrl contains the URL or a relative path of the css style used by Clea. You can incorporate this in the App using a link tag to have the same look and feel of Clea.
  • language is the language selected by the user logged in using the ISO 639-1 format. When no language is selected, it defaults to “en” for english.

Styling the App

DOM elements can be styled as usual with inline styles or CSS id and classes. Inline styles aside, CSS styles can only be declared with one or multiple <style> or <link> tags in the top level of the App container provided during the mount phase.

The App is mounted inside a shadow DOM, so style declared there won’t leak outside and vice versa.

Clea uses a customized version of Bootstrap 5.1. The stylesheet file used by Clea is provided to external apps via the themeUrl parameter (see also Settings section).

Limitations

The Platform supports third-party apps thanks to modern technologies such as ES Modules. As such, apps run on browsers that support such features. You can look at the compatibility matrixes for details about browser support.

Since the app is loaded as a module inside a Platform’s web page, JavaScript methods that modify global state of the page must be avoided; these forbidden actions include:

  • Changing the page’s location or history.
  • Interacting with the browser’s storages such as localStorage.
  • Using global variables or modifying the window object.

Example apps

You can look at the sample boilerplate codes (React + Typescript) for app development that are provided in the Clea Examples repository.

Registering an app on the Platform

The Platform provides a dedicated section to register third-party Clea Portal Apps. Check how to do that in the Tenant Applications section on the Admin Console page.