How to...

The @interopio/desktop library provides APIs with which you can access the io.Connect functionalities and interop-enable your web apps. You can either auto inject (and optionally auto initialize) the library in your apps, or reference it (either as an NPM module, or as a standalone JavaScript file) and then initialize it. Both approaches have their respective advantages and disadvantages. Usually, it's recommended to choose a global approach for all your interop-enabled apps (in some cases, there may be hundreds of interop-enabled apps in use) based on what best suits your needs and requirements.

Auto injecting the library is preferable if you want all your interop-enabled apps to use the same version of the library and have the option to be easily updated to the latest version of @interopio/desktop. Updating the library in all apps can be accomplished simply by redeploying io.Connect Desktop - all interop-enabled apps will be automatically injected with the new version of the library, saving you the effort to update them one by one. Another option is to use a REST service providing the latest library versions. When using auto injection, however, your apps won't be interop-enabled if running in a browser, which is something to consider if you want to use them in a browser. Auto injection may not work well for you in some other cases as well, depending on your production and deployment model.

Using the @interopio/desktop library as a standalone file or as an NPM package has its advantages too - your apps can use a different version of the library if necessary. Also, your apps can be interop-enabled in a browser. This, of course, means that updating the library can be a tedious and slow process, especially if you have many interop-enabled apps, the majority of which are using different versions of the library.

The @interopio/desktop library is available as an NPM package which you can include as a dependency in your project and import in your code.

⚠️ Note that the @interopio/desktop depends on the @interopio/core library. The @interopio/core library is a subset of @interopio/desktop and offers only basic functionalities for sharing data between apps (Interop, Shared Contexts, Pub/Sub), while the @interopio/desktop library offers additional, more sophisticated interoperability options such as (Channels, Intents), as well as advanced app and window management functionalities (App Management, Layouts, Window Management). The @interopio/desktop library also provides APIs for using Notifications, App Preferences, Themes, Displays, Hotkeys, Interception, and more.

To install the @interopio/desktop library, execute the following command:

npm install @interopio/desktop

You can now import the factory function exposed by the library and start interop-enabling your apps:

import IODesktop from "@interopio/desktop";

You can also reference the library as a JavaScript file in the HTML file of your web app using a <script> tag:

<script type="module" src="./desktop.umd.js"></script>

When deploying your app in production, it's recommended to always reference a specific minified version:

<script type="module" src="./desktop.umd.min.js"></script>

The following sections describe how to initialize the @interopio/desktop library depending on whether your web app will run in an io.Connect Window or in a web browser.

io.Connect Window

The @interopio/desktop library exposes a global factory function called IODesktop(). It accepts as an argument an optional Config object which you can use to configure various library features. To initialize the library, invoke the factory function and use the returned API object to access the io.Connect APIs:

import IODesktop from "@interopio/desktop";

// It isn't necessary to specify any configuration.
const io = await IODesktop();

// Now you can use the io.Connect APIs via the initialized API object.
await io.appManager.application("my-app").start();

The optional Config object allows you to configure some of the available io.Connect APIs. You can enable or disable an API and for some of the APIs it's possible to specify the level of features your app will require from them. For more details on configuring the different APIs, see the respective entry in the Capabilities section.

Web Browser

If you want to run your app in a web browser, you must provide the necessary details and authentication information for connecting to the io.Connect framework as demonstrated in the following example:

<script type="module" src="desktop.umd.min.js"></script>

<script>
    const initializeIOConnect = async () => {
        const config = {
            // Name for your app.
            application: "MyWebApp",
            // Settings for connecting to the io.Connect Gateway.
            gateway: {
                protocolVersion: 3,
                ws: "<gateway_url>"
            },
            // Authentication settings.
            auth: {
                username: "<username>",
                password: "<password>"
            }
        };

        window.io = await IODesktop(config);
    };

    initializeIOConnect().catch(console.error);
</script>

Auto injection can be configured on a system level and can be overridden on an app level (with some limitations). You can also optionally specify whether you want to auto initialize the library after injection.

System Level

To enable auto injection on a system level, use the "autoInjectAPI" property under the "windows" top-level key in the system.json system configuration file of io.Connect Desktop:

{
    "windows": {
        "autoInjectAPI":{
            "enabled": true,
            "version": "5.11.2",
            "autoInit": false
        }
    }
}

The "autoInjectAPI" object has the following properties:

Each version of io.Connect Desktop is distributed with a set of @interopio/desktop library version that are used for auto injection. You can see the versions available for auto injection in the <installation_location>/interop.io/io.Connect Desktop/Desktop/assets/preloads folder. If you specify a version which isn't available, io.Connect Desktop will continue working normally without injecting a library in the apps running in it.

If the library is injected but not auto initialized, you can use the IODesktop() factory function to initialize it and pass an optional Config object to it:

// Enabling the Channels API.
const config = { channels: true };

const io = await IODesktop(config);

console.log(`io.Connect JS version ${io.version} has been successfully initialized!`);
console.log(`Channels are ${io.channels ? "enabled" : "disabled"}.`);

If the library is injected and auto initialized, you should use the injected ioPromise in the window object to wait for the io.Connect API:

await ioPromise.catch(console.error);

// The returned `io` object is assigned to the global `window` object.
if (window.io) {
    console.log(`io.Connect JS version ${io.version} has been successfully initialized!`);

    // Channels are disabled by default. If you haven't specified a custom initialization object that enables
    // the Channels API in the `autoInit` property under `autoInjectAPI` (e.g., "autoInit": { "channels": true }),
    // then the following check will return `false`.
    console.log(`Channels are ${io.channels ? "enabled" : "disabled"}.`);
};

Filtering

You can allow and block apps on a system level to control which apps should be auto injected with the library and which should use their own version of the library instead.

• all allowed apps will be auto injected with the library, all other apps won't be auto injected:

{
    "windows": {
        "autoInjectAPI":{
            "enabled": true,
            "version": "5.9.0",
            "autoInit": false,
            "allowed": ["my-app", "my-other-app"]
        }
    }
}

• blocked apps won't be auto injected with the library, all other apps will be auto injected:

{
    "windows": {
        "autoInjectAPI":{
            "enabled": true,
            "version": "5.9.0",
            "autoInit": false,
            "blocked": ["my-app", "my-other-app"]
        }
    }
}

If an app is both in the allowed and the blocked lists, it will be auto injected with the library.

App Level

If auto injection of the library is disabled on a system level, it can't be enabled on an app level. If auto injection is enabled on a system level, then each app can opt out of it. Apps can specify whether the auto injected library will be auto initialized or not, but can't specify which version of the library to be auto injected - this is possible only on a system level. If an app needs to use a different version of the library than the auto injected one, you should disable auto injection in the app definition and reference a version of the library file in your app instead.

To configure auto injection on an app level, use the "autoInjectAPI" property of the "details" top-level key in the app definition.

ℹ️ For more details on how to create an app definition and where the app definition files should be stored, see the App Definition section or the Developers > Configuration > Application section.

The following is an example configuration for auto injection on an app level:

{
    "details": {
        "autoInjectAPI":{
            "enabled": true,
            "autoInit": false
        }
    }
}

The "autoInjectAPI" object has the following properties:

Auto Initialization

Auto initialization of the injected library can be specified globally in the system.json file, or can be overridden on an app level in the app definition file. To enable or disable auto initialization of the library, use the "autoInit" property of the "autoInjectAPI" object.

If you want to auto initialize your app with custom library configuration, provide a Config object with initialization settings instead of a Boolean value.

The following example demonstrates how to auto initialize an app and enable Channels:

{
    "autoInjectAPI":{
        "enabled": true,
        "autoInit": {
            "channels": true
        }
    }
}

⚠️ Note that the auto initialization configuration takes precedence over initializing the library inside your app. The @interopio/desktop library can't be initialized more than once - the factory function will always return the first initialized instance, even if you attempt to initialize the library again.

To add your JavaScript app to the io.Connect launcher, you must create a JSON app definition file for it. Place this file in the <installation_location>/interop.io/io.Connect Desktop/UserData/<ENV>-<REG>/apps folder, where <ENV>-<REG> represents the environment and region of io.Connect Desktop (e.g., DEMO-INTEROP.IO).

The following is an example definition of a JavaScript app:

{
    "name": "my-app",
    "title": "My App",
    "type": "window",
    "details": {
        "url": "https://example.com/my-app/",
        "mode": "tab",
        "width": 500,
        "height": 400
    }
}

The "name", "type" and "url" properties are required and "type" must be set to "window". The "url" property points to the location of the web app.

The value of the "title" property will be used as a name for the app in the io.Connect launcher and as a window title if the web app doesn't have a document title.

ℹ️ For more details on defining apps, see the Developers > Configuration > Application section.

ℹ️ See the JavaScript examples on GitHub which demonstrate various io.Connect Desktop features.

Once the io.Connect JavaScript library has been initialized, your app has access to all io.Connect functionalities. For more detailed information on the different io.Connect capabilities and APIs, see:

• App Management
• App Preferences
• Intents
• Shared Contexts
• Channels
• Interop
• Pub/Sub
• Window Management
• Workspaces
• Layouts
• Notifications
• Search
• Hotkeys
• Zooming
• Displays
• Logging

For a complete list of the available JavaScript APIs, see the io.Connect JavaScript Reference Documentation.