How to...

io.Connect Desktop provides several options for interop-enabling your apps. You can either auto inject (and optionally auto initialize) the io.Connect JavaScript 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 is 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 the way to go if you need 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 io.Connect JavaScript. 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 versions of io.Connect JavaScript. Apps with auto injected io.Connect, however, won't be interop-enabled in the browser, which is something to consider if you need 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 io.Connect JavaScript 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 need to use a different version of the library.

Below you can explore both options for using the io.Connect JavaScript library.

From a JavaScript File

The io.Connect JavaScript library is available as a single JavaScript file, which you can include in your web apps using a <script> tag:

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

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

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

From an NPM Module

The io.Connect JavaScript library is also available as an NPM package, which you can include as a dependency in your project and import in your code. The currently available packages are @interopio/core and @interopio/desktop. The @interopio/core package is a subset of the @interopio/desktop package and offers basic functionalities for sharing data between apps (Interop, Shared Contexts, Pub/Sub, while the @interopio/desktop package offers additional options for sharing data between apps (Channels), as well as advanced window management functionalities (App Management, Layouts, Window Management).

To include any of the packages as a dependency in your project, navigate to the root directory of your project and run:

npm install @interopio/desktop

Your package.json file now should have an entry similar to this:

{
    "dependencies": {
        "@interopio/desktop": "^5.9.0"
    }
}

When included, the JavaScript library will register a global factory function called IODesktop(). It should be invoked with an optional configuration object to initialize the library. The factory function will resolve with the initialized io API object.

Initialization in an io.Connect Window:

import IODesktop from "@interopio/desktop";

// You don't need to specify any configuration.
const io = await IODesktop();

Initialization in a browser:

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

<script type="text/javascript">
    const initializeIOConnect = async () => {
        const config = {
            application: "MyWebApplication",
            gateway: {
                protocolVersion: 3,
                ws: "<GATEWAY_URL>"
            },
            auth: {
                username: "<YOUR_USERNAME>",
                password: "<YOUR_PASSWORD>"
            }
        };

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

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

You can customize the io.Connect configuration object by specifying which io.Connect libraries your app needs, and what level of features your app requires from these libraries. See the io.Connect Desktop Reference documentation for details.

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, edit the "autoInjectAPI" property under the "windows" top-level key in the system.json file of io.Connect Desktop located in %LocalAppData%/interop.io/io.Connect Desktop/Desktop/config:

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

You can see which versions of the io.Connect JavaScript library are available for auto injection in the %LocalAppData%/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 injected 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 gluePromise in the window object to wait for the io.Connect API:

await gluePromise.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 check below 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": ["clientlist"]
        }
    }
}

• 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": ["clientlist"]
        }
    }
}

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, edit (or add) the "autoInjectAPI" property under the "details" top-level key in the app definition file.

For more details on how to create an app definition and where the app definition files should be stored, see the App Definition section below 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
        }
    }
}

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, set the "autoInit" property under "autoInjectAPI" to true or false respectively.

If you want to auto initialize your app with a custom initialization Config object, simply specify the initialization options object instead of assigning a boolean value to "autoInit".

Below is an example configuration that will auto initialize an app with Channels enabled:

{
    "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 anew. This means that if you are using auto initialization and then try to initialize the library inside your app (e.g., with different configuration options), this won't work and you'll always receive the original auto initialized library instance.

To add your JavaScript app to the io.Connect launcher, you must create a JSON file with app definition. Place this file in the %LocalAppData%/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, 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.