io.Bridge

Overview

Available since io.Connect Browser 4.2

io.Connect Browser projects can connect to io.Bridge and use its functionalities.

io.Bridge is a distributed server-side app that provides connectivity between the io.Connect platforms (io.Connect Desktop and io.Connect Browser), your interop-enabled apps running on different machines, and third-party apps for which you are using Application Adapters (Microsoft Office apps, Bloomberg, Fidessa, Salesforce, and more).

ℹ️ For more details about io.Bridge, see the io.Bridge documentation.

Setup

Connecting to io.Bridge from an io.Connect Browser project requires modifying the configuration for initializing the @interopio/browser-platform library in the Main app.

To specify settings for the connection to io.Bridge, use the bridge property of the gateway object inside the configuration object for initializing the @interopio/browser-platform library. The following example demonstrates configuring the connection to io.Bridge by specifying the io.Bridge URL, user details, and settings for the io.Connect APIs:

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

const config = {
    licenseKey: "my-license-key",
    gateway: {
        bridge: {
            // URL pointing to io.Bridge.
            url: "https://my-io-bridge.com",
            // Disabling the Channels API for cross-platform and cross-machine interoperability via io.Bridge.
            channels: {
                enabled: false
            },
            contexts: {
                // Settings for the visibility of the shared context objects when using io.Bridge.
                visibility: [
                    {
                        // Name of the shared context object whose visibility to restrict.
                        context: "MySharedContext",
                        // The specified shared context will be visible only within the current platform.
                        restrictions: "local"
                    }
                ]
            }
        }
    },
    // When connecting to io.Bridge, it's required to specify user details.
    // Only the platforms of the same user can be connected via io.Bridge.
    user: {
        id: "user-id"
    }
};

const { io } = await IOBrowserPlatform(config);

The bridge object has the following properties:

Property	Type	Description
`channels`	`object`	Settings for the Channels API when using io.Bridge.
`contexts`	`object`	Settings for the Shared Contexts API when using io.Bridge.
`getHeaders`	`function`	Callback that will be invoked on every request. Use this callback to provide extra headers that will be applied to the request.
`getWebSocketSearchParams`	`function`	Callback that will be invoked on every HTTP `Upgrade` request (i.e., when establishing or re-establishing a WebSocket connection to io.Bridge). Use this callback to provide search parameters that will be added to the HTTP `Upgrade` request.
`headers`	`object`	Object containing key/value pairs of headers to be sent with every request.
`intents`	`object`	Settings for the Intents API when using io.Bridge.
`interop`	`object`	Settings for the Interop API when using io.Bridge.
`search`	`object`	Settings for the Search API when using io.Bridge.
`url`	`string`	Required. URL pointing to io.Bridge.

The channels object has the following properties:

Property	Type	Description
`enabled`	`boolean`	If `true` (default), will enable using the Channels API for cross-platform and cross-machine interoperability via io.Bridge.

The contexts object has the following properties:

Property	Type	Description
`enabled`	`boolean`	If `true` (default), will enable using the Shared Contexts API for cross-platform and cross-machine interoperability via io.Bridge.
`visibility`	`object[]`	Settings for the cross-platform and cross-machine visibility of the shared context objects. By default, all shared contexts are visible by all platforms on all machines of the same user that are connected to io.Bridge. If you want a shared context to be visible only within the current platform on the local user machine, set its visibility restriction to `"local"`. Restricting the visibility of a shared context to `"local"` also prevents the current platform from seeing any other shared contexts with the same name offered by other platforms. The `visibility` property takes precedence over `enabled` which means that you can use `enabled: false` to restrict the visibility of all shared contexts to the current platform on the local user machine and specify exceptions only for some shared contexts by setting their visibility restriction to `"cluster"`. For more details, see the Visibility Restrictions section.

The intents object has the following properties:

Property	Type	Description
`enabled`	`boolean`	If `true` (default), will enable using the Intents API for cross-platform and cross-machine interoperability via io.Bridge.

The interop object has the following properties:

Property	Type	Description
`enabled`	`boolean`	If `true` (default), will enable using the Interop API for cross-platform and cross-machine interoperability via io.Bridge.
`visibility`	`object[]`	Settings for the cross-platform and cross-machine visibility of the Interop methods. By default, all Interop methods are visible by all platforms on all machines of the same user that are connected to io.Bridge. If you want an Interop method to be visible only within the current platform on the local user machine, set its visibility restriction to `"local"`. Restricting the visibility of an Interop method to `"local"` also prevents the current platform from seeing any other Interop methods with the same name offered by other platforms. The `visibility` property takes precedence over `enabled` which means that you can use `enabled: false` to restrict the visibility of all Interop methods to the current platform on the local user machine and specify exceptions only for some Interop methods by setting their visibility restriction to `"cluster"`. For more details, see the Visibility Restrictions section.

The search object has the following properties:

Property	Type	Description
`enabled`	`boolean`	If `true` (default), will enable using the Search API for cross-platform and cross-machine interoperability via io.Bridge.

Visibility Restrictions

By default, all io.Connect APIs are available for cross-platform and cross-machine interoperability via io.Bridge. The Shared Contexts and the Interop APIs use specific object instances (shared context objects and Interop methods) in their API operations whose visibility you can control.

It's possible to restrict the visibility of one or more of these objects to the current platform on the local user machine, or to restrict all objects to the current platform on the local user machine and only allow selected ones to be visible by all platforms on all machines of the same user.

Shared Contexts

To specify visibility restrictions for shared contexts, use the visibility array of the contexts object when specifying settings for connecting to io.Bridge.

Each object in the visibility array has the following properties:

Property	Type	Description
`context`	`RegExp` \| `string`	The name of the shared context whose visibility to restrict or a regular expression for matching one or more shared contexts.
`restrictions`	`"local"` \| `"cluster"`	Restriction for the matched shared contexts. If set to `"local"`, the shared contexts will be visible only within the current platform on the local user machine. This also prevents the current platform from seeing any other shared contexts with the same name offered by other platforms. If set to `"cluster"`, they will be visible by all platforms on all machines of the same user connected to io.Bridge.

The following example demonstrates restricting the visibility of all shared contexts to the current platform on the local user machine and allowing only a specific shared context to be visible by all platforms on all machines of the same user:

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

const config = {
    licenseKey: "my-license-key",
    gateway: {
        bridge: {
            url: "https://my-io-bridge.com",
            contexts: {
                // Restricting the visibility of all shared contexts.
                enabled: false,
                // Allowing a specific shared context to be visible by all platforms on all machines of the same user.
                visibility: [
                    {
                        context: "MySharedContext",
                        restrictions: "cluster"
                    }
                ]
            }
        }
    },
    user: {
        id: "user-id"
    }
};

const { io } = await IOBrowserPlatform(config);

Interop Methods

To specify visibility restrictions for Interop methods, use the visibility array of the interop object when specifying settings for connecting to io.Bridge.

Each object in the visibility array has the following properties:

Property	Type	Description
`method`	`RegExp` \| `string`	The name of the Interop method whose visibility to restrict or a regular expression for matching one or more Interop methods.
`restrictions`	`"local"` \| `"cluster"`	Restriction for the matched Interop methods. If set to `"local"`, the Interop methods will be visible only within the current platform on the local user machine. This also prevents the current platform from seeing any other Interop methods with the same name offered by other platforms. If set to `"cluster"`, they will be visible by all platforms on all machines of the same user connected to io.Bridge.

The following example demonstrates restricting the visibility of a specific Interop method to the current platform on the local user machine:

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

const config = {
    licenseKey: "my-license-key",
    gateway: {
        bridge: {
            url: "https://my-io-bridge.com",
            // By default, all Interop methods are visible by all platforms on all machines of the same user.
            interop: {
                // Restricting the visibility of a specific Interop method to the current platform on the local user machine.
                visibility: [
                    {
                        context: "MyInteropMethod",
                        restrictions: "local"
                    }
                ]
            }
        }
    },
    user: {
        id: "user-id"
    }
};

const { io } = await IOBrowserPlatform(config);