# Platform

Source: https://docs.interop.io/bridge/configuration/platform/index.html

## io.Connect Desktop

To configure **io.Connect Desktop** to connect to **io.Bridge**, use the `"gw"` top-level key in the `system.json` [system configuration](https://docs.interop.io/desktop/developers/configuration/system/index.md) file of **io.Connect Desktop** located in the `<installation_location>/interop.io/io.Connect Desktop/Desktop/config` folder.

First, you must enable the io.Connect Gateway version that supports connecting to **io.Bridge** by setting the `"useBeta"` property to `true`:

```json
{
    "gw": {
        "useBeta": true
    }
}
```

Then, use the `"cluster"` property of the `"configuration"` object to configure **io.Connect Desktop** to connect to **io.Bridge**:

```json
{
    "gw": {
        "configuration": {
            "cluster": {
                "enabled": true,
                "type": "p2p",
                "p2p": {
                    "directory": {
                        "type": "rest",
                        "config": {
                            "directory_uri": "https://my-io-bridge.com:8084",
                            "announce_interval": 30000
                        }
                    }
                }
            }
        }
    }
}
```

The `"cluster"` object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"enabled"` | `boolean` | If `true`, will allow the io.Connect Gateway embedded in **io.Connect Desktop** to connect to **io.Bridge**. |
| `"p2p"` | `object` | Describes the cluster to which to connect. Use the `"directory"` property of the `"p2p"` object to configure the connection to **io.Bridge**. |
| `"type"` | `string` | Type of the cluster to which to connect. Must be set to `"p2p"`. |

The `"directory"` object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"config"` | `object` | Settings for connecting to **io.Bridge**. |
| `"type"` | `string` | Type of the discovery mechanism used for connecting members with each other within the cluster. Must be set to `"rest"`. |

The `"config"` object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"announce_interval"` | `string` | Interval in milliseconds at which the io.Connect Gateway will ping **io.Bridge**. Defaults to `10000`. |
| `"directory_uri"` | `string` | URL pointing to the location of **io.Bridge**. Defaults to `"http://localhost:8888"`. |

## io.Connect Browser

Available since io.Connect Browser 4.2

Connecting to **io.Bridge** from an **io.Connect Browser** project requires modifying the configuration for initializing the [`@interopio/browser-platform`](https://www.npmjs.com/package/@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`](https://www.npmjs.com/package/@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:

```javascript
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](#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](#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](https://docs.interop.io/browser/capabilities/data-sharing/shared-contexts/index.md) and [Interop methods](https://docs.interop.io/browser/capabilities/data-sharing/interop/index.md)) 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:

```javascript
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:

```javascript
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: [
                    {
                        method: "MyInteropMethod",
                        restrictions: "local"
                    }
                ]
            }
        }
    },
    user: {
        id: "user-id"
    }
};

const { io } = await IOBrowserPlatform(config);
```