io.Connect Desktop

The Main app can be configured to constantly check for the presence of a locally installed io.Connect Desktop. If such an instance is discovered, the Main app and all of its Browser Client apps will attempt to switch their io.Connect connection to io.Connect Desktop. If this operation is successful, the io.Connect Browser environment will be able to fully interoperate with all io.Connect Desktop clients.

This enables io.Connect Browser projects to seamlessly integrate with io.Connect Desktop without disrupting any of the running Browser Client apps.

As soon as the Main app discovers a running instance of io.Connect Desktop and manages to connect to it, all current Browser Client apps follow suit. The connection switch is executed without the apps reloading or flickering and is completely invisible to the end user. However, changing the connection of an io.Connect Browser environment has numerous effects in all aspects of the io.Connect functionalities, explained in the following sections.

Shared Contexts & Channels

Switching between an io.Connect Browser and an io.Connect Desktop connection is handled seamlessly for the Shared Contexts library. If the Main app is configured to look for an io.Connect Desktop connection, it will monitor all shared contexts and will be aware of their latest state. Once a connection switch happens, the Main app will be the last one to reconnect, ensuring that the latest state of all shared contexts is restored. All shared context subscriptions will be preserved and everything is executed without any visual interruption.

The Channels are based on Shared Contexts. This provides full integration when connecting to io.Connect Desktop. Both an io.Connect Browser app and an io.Connect Desktop app listening for changes to the same Channel will be notified at the same time when the Channel data has been updated.

Interop

Upon a connection change, the Interop library will re-initiate and re-announce its current state. This means that all io.Connect Browser clients, including the Main app, will preserve their respective peerId and instance ID. All registered Interop methods, streams and subscriptions will be preserved and carried over to the new connection.

Apps, Windows & Workspaces

The functionality of the App Management and Window Management libraries won't change in any way when an io.Connect Browser environment connects to an io.Connect Desktop instance. This means that the list() method of the Window Management API will always return a collection consisting only of the currently opened io.Connect Browser windows, regardless of the connection state. The open() method of the Window Management API and the start() method of an app instance will always open an io.Connect Browser window or start an io.Connect Browser app respectively when called from an io.Connect Browser app.

The same is applicable to the Workspaces library. Calling any of the Workspaces API methods from an io.Connect Browser app will always open, fetch data or manipulate an io.Connect Browser Workspace, regardless of whether or not the io.Connect Browser environment is connected to io.Connect Desktop.

Notifications

There aren't any changes in the operation of the Notifications library when connected to an io.Connect Desktop instance. All raised notifications will be io.Connect Browser notifications, meaning they will be raised by the browser. However, keep in mind that if you set an Interop method as a handler for a notification click or an action button of an io.Connect Browser notification, this method may also have been registered by an io.Connect Desktop app. Clicking on the notification or its action buttons will invoke all registered Interop methods with the same name, regardless of whether they have been registered by io.Connect Browser or by io.Connect Desktop apps. So, in a way, acting on an io.Connect Browser notification can have effects in io.Connect Desktop.

Rejected Connections

The following describes the cases when a connection attempt to io.Connect Desktop may fail entirely or partially:

• When the Main app has started an io.Connect Browser app that uses an old version of the @interopio/browser library. In this situation, the Browser Client app won't be able to handle the connection switch instructions of the Main app. As a result, the Main app will either ignore this app and proceed with the connection switch or will cancel the connection switch attempt. This is determined by the forceIncompleteSwitch setting when configuring the connection settings in the Main app (see the Configuration section).

• When the Main app is rejected by io.Connect Desktop based on origin filtration or a custom authentication mechanism. In this situation, the io.Connect Browser environment won't attempt to transfer the Browser Client apps and will cancel the reconnection attempt. However, the cycle for discovering io.Connect Desktop instances will continue, meaning that the Main app will periodically attempt a connection.

• When the connection request of the Main app is accepted by io.Connect Desktop, but the connection request of a Browser Client app is rejected. This may happen due to origin filtration when the Main app and the Browser Client app have different origins or as a result of some other custom io.Connect Desktop authenticator. In this situation, the Main app will either ignore this app and proceed with the connection switch or will cancel the connection switch attempt. This is determined by the forceIncompleteSwitch setting when configuring the connection settings in the Main app (see the Configuration section).

Default Connection

If the io.Connect Desktop instance to which the io.Connect Browser environment is connected disappears, the io.Connect Browser environment will resume its default state and all Browser Client apps will fall back to the default io.Connect Browser connection to their respective Main app.

Enabling and configuring the discovery of io.Connect Desktop is executed entirely in the Main app during the initialization of the @interopio/browser-platform library. Use the connection property of the configuration object to specify settings for the connection to io.Connect Desktop:

import IOBrowserPlatform from "@interopio/browser-platform";

const config = {
    licenseKey: "my-license-key",
    connection: {
        preferred: {
            url: "ws://localhost:8385",
            auth:{
                username: "user",
                password: "password"
            },
            forceIncompleteSwitch: true,
            discoveryIntervalMS: 60000
        }
    }
};

const { io } = await IOBrowserPlatform(config);

The preferred property instructs the Main app that in addition to its own default connection, there is an additional one, whose availability is unknown, but is preferred if available. The preferred object has the following properties, of which only url is required:

⚠️ Note that for an io.Connect Browser environment to be able to discover and connect to an io.Connect Desktop instance, the io.Connect Desktop Gateway must use a known port whose URL you must supply to the url property of the preferred object. Currently, an io.Connect Browser environment isn't able to discover an io.Connect Desktop instance configured to use a dynamic port for the io.Connect Gateway.

The Main app and all Browser Client apps can run in io.Connect Desktop without any code modification. The Main app will automatically detect that it's running in io.Connect Desktop and won't initialize any of its Browser Platform logic - it will default to being a normal io.Connect Desktop client app. The Browser Client apps will also auto detect the environment and will initialize the @interopio/desktop library instead of @interopio/browser, with all necessary features enabled and set to the highest possible level (e.g., the Aplication Management API will be initialized in "full" mode) to ensure correct app functionality. This gives you the option to easily experiment with your apps running in a functionally richer environment with more integration options.

For more information, see the io.Connect Desktop product page and the io.Connect Desktop official documentation.*

Guide

1. Download the trial version of io.Connect Desktop from here and install it.

2. Make sure that io.Connect Desktop runs with auto injection on:

• Open the system.json configuration file located in the %LocalAppData%\interop.io\io.Connect Desktop\Desktop\config folder.
• Edit the "autoInjectAPI" property of the "windows" top-level key using the following configuration:

{
    "windows": {
        "autoInjectAPI": {
            "enabled": true,
            "version": "6.*",
            "autoInit": false
        }
    }
}

For more details on configuring io.Connect Desktop, see the System Configuration section.

3. Create a definition file for your app. Use the template below and change the "name", "title" and "url" properties with the details of your app:

[
    {
        "title": "io.Connect Browser App",
        "type": "window",
        "name": "browser-app",
        "details": {
            "url": "http://localhost:4242/",
            "top": 100,
            "left": 200,
            "width": 600,
            "height": 300,
            "mode": "tab"
        }
    }
]

Save the configuration file in JSON format and place it in the app definitions folder. Usually, this is the %LocalAppData%\interop.io\io.Connect Desktop\UserData\<ENV-REG>\apps folder where <ENV-REG> should be replaced with the region and environment folder name used for the deployment of your io.Connect Desktop - e.g., DEMO-INTEROP.IO.

For more details on configuring an interop-enabled app in io.Connect Desktop, see the App Configuration section.

4. Start io.Connect Desktop and open your app from the io.Connect launcher.

Using io.Connect Desktop Features

If you want to keep your app running in both environments and also use features that are specific to io.Connect Desktop, you must check in your code in which environment your app is running.

For example, you may want to register a global hotkey shortcut using the Hotkeys API that is only available in io.Connect Desktop. Use the iodesktop or the iobrowser objects that are automatically injected in the global window object on startup of io.Connect Desktop or io.Connect Browser respectively to determine in which environment your app is running:

// Check whether the app is running in io.Connect Desktop in order to use the Hotkeys API.
if (typeof iodesktop !== "undefined") {

    // Define a hotkey object.
    const hotkeyClientDetails = {
        hotkey: "shift+alt+c",
        description: "Open Client Details"
    };

    // Define a hotkey handler.
    const handler = (details) => {
        // This function will be invoked when the hotkey is used.
        console.log("Shortcut has been used.");
    };

    // Register the hotkey.
    await io.hotkeys.register(hotkeyClientDetails, handler);
} else if (typeof iobrowser !== "undefined") {
    // Running in io.Connect Browser, will fall back to in-page shortcuts.
};

If you are using TypeScript, cast your @interopio/browser API to the @interopio/desktop API to get better types:

// Import the types.
import { IOConnectDesktop } from "@interopio/desktop";

if (typeof iodesktop !== "undefined") {
    // Running in io.Connect Desktop, you can now use io.Connect Desktop specific APIs.
    const ioConnect = io as IOConnectDesktop.API;
};