# Platform

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

## io.Connect Desktop

To configure **io.Connect Desktop** to connect to **io.Manager**, use the `"server"` top-level key of 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. Add the following basic configuration to enable connection to **io.Manager**:

```json
{
    "server": {
        "enabled": true,
        "url": "http://localhost:4356/api"
    }
}
```

This will add **io.Manager** as an additional app store and instruct it to store Layouts and app preferences. If you want **io.Manager** to be the only app store, set the `"appStores"` top-level key in the `system.json` file to an empty array.

The `"server"` top-level key has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"advancedLayouts"` | `object` | Settings for advanced Layouts. Must match the [`AdvancedLayoutsConfig`](https://docs.interop.io/manager/configuration/server/index.md#configuration_object-advancedlayoutsconfig) settings on the connected **io.Manager** Server. *Available since **io.Connect Desktop** 10.5 (unreleased) & **io.Manager** 4.0.* |
| `"cache"` | `object` | Settings for persisting data received from **io.Manager**. Defaults to `{}`. *Available since **io.Connect Desktop** 9.4.* |
| `"clientAuth"` | `"no-auth" \| "negotiate" \| "kerberos"` | The client authentication mechanism for the REST service. Defaults to `"no-auth"`. |
| `"enabled"` | `boolean` | If `true`, will enable connecting to **io.Manager**. |
| `"features"` | `object` | Features to be injected automatically in **io.Connect Desktop**. |
| `"fetchInterval"` | `number` | Interval in seconds at which the server will be polled for new data (apps, Layouts, commands). Defaults to `30`. |
| `"requests"` | `object` | Settings for the requests sent to **io.Manager**. Defaults to `{}`. *Available since **io.Connect Desktop** 9.4.* |
| `"startRetries"` | `number` | Number of times **io.Connect Desktop** will try to reconnect to **io.Manager**. Defaults to `10`. |
| `"startRetryInterval"` | `number` | Interval in seconds at which **io.Connect Desktop** will try to connect to **io.Manager**. Defaults to `10`. |
| `"tokenRefreshInterval"` | `number` | Interval in seconds at which **io.Connect Desktop** will try to refresh the **io.Manager** token. Defaults to `3600`. |
| `"url"` | `string` | **Required.** URL pointing to **io.Manager**. |

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

| Property | Type | Description |
|----------|------|-------------|
| `"applicationsStore"` | `boolean` | If `true` (default), the **io.Manager** app store will be automatically injected. |
| `"layoutsStore"` | `boolean` | If `true` (default), the **io.Manager** Layout store will be automatically injected. |
| `"commands"` | `boolean` | If `true` (default), the **io.Manager** commands will be automatically injected. |
| `"preferencesStore"` | `boolean` | If `true` (default), the **io.Manager** app preferences store will be automatically injected. |
| `"preferencesRefreshEnabled"` | `boolean` | If `true` (default), **io.Connect Desktop** requests cross-session preference refreshes from **io.Manager**. Disable in deployments where preference payloads are large enough to make the refresh costly. *Available since **io.Connect Desktop** 10.5 (unreleased).* |

As of **io.Connect Desktop** 10.5 (unreleased), when **io.Manager** is enabled, crash reports from the io.Connect platform are sent to the **io.Manager** Server automatically - no additional configuration is required. Explicit `"crashReporter"` settings still take precedence when present.

To send client crashes to the **io.Manager** Server explicitly, edit the `"output"` property of the `"crashReporter"` top-level key in the `system.json` file:

```json
{
    "crashReporter": {
        "output": {
            "type": "server",
            "serverUrl": "http://localhost:4356/api/crashes"
        }
    }
}
```

If you want to support different environments and regions that connect to different **io.Manager** instances, see the [Developers > Configuration > System > Environments & Regions](https://docs.interop.io/desktop/developers/configuration/system/index.md#environments__regions) section of the **io.Connect Desktop** documentation.

Available since io.Connect Desktop 9.4

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

| Property | Type | Description |
|----------|------|-------------|
| `"clearOld"` | `boolean` | If `true`, on opening a new session to **io.Manager**, all cache files from previous sessions will be deleted. Defaults to `false`. |
| `"enabled"` | `boolean` | If `true`, will enable caching and persisting data from **io.Manager** locally (e.g., in case of connection interruptions). Defaults to `false`. |
| `"location"` | `string` | Location for the persisted cache files. Defaults to `"%IO_CD_USER_DATA_DIR%/ioManagerCache"`. |

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

| Property | Type | Description |
|----------|------|-------------|
| `"closeSessionTimeout"` | `number` | Interval in milliseconds to wait for a response to the `closeSession` request to **io.Manager**. Defaults to `10000`. |
| `"loggerLevel"` | `string` | Log level with which the requests to **io.Manager** will be logged. Defaults to `"trace"`. |
| `"logHTTPHeaders"` | `boolean` | If `true`, will log the request and response HTTP headers of the requests sent to **io.Manager**. Defaults to `false`. |
| `"logSanitization"` | `boolean` | If `true` (default), the logged requests will be sanitized. If set to `false`, sensitive information (tokens) won't be removed from the logged requests. |
| `"openSessionTimeout"` | `number` | Interval in milliseconds to wait for a response to the `openSession` request to **io.Manager** before proceeding from cache. Defaults to `60000`. |
| `"requestBodyValidation"` | `boolean` | If `true` (default), the bodies of the requests sent to **io.Manager** will be validated. |
| `"responseBodyValidation"` | `boolean` | If `true` (default), the response bodies received from **io.Manager** will be validated. |
| `"timeout"` | `number` | Interval in milliseconds to wait for a response from **io.Manager**. Defaults to `60000`. |

Available since io.Connect Desktop 10.5 (unreleased) & io.Manager 4.0

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

| Property | Type | Description |
|----------|------|-------------|
| `"enabled"` | `boolean` | If `true`, **io.Connect Desktop** consumes advanced Layouts from the connected **io.Manager** Server. Must match the server's `API_ADVANCED_LAYOUTS_ENABLED` setting. Defaults to `false`. |

## io.Connect Browser

[Connecting](https://docs.interop.io/browser/capabilities/manager/index.md#setup) to **io.Manager** 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 the **io.Manager**, use the `manager` property of the optional configuration object when initializing the [`@interopio/browser-platform`](https://www.npmjs.com/package/@interopio/browser-platform) library. The following example demonstrates configuring the connection to **io.Manager** with [Basic](https://docs.interop.io/manager/authentication/basic/index.md) authentication:

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

const config = {
    licenseKey: "my-license-key",
    manager: {
        // URL pointing to io.Manager.
        url: "https://my-io-manager.com:4242/api",
        // Basic authentication.
        auth: {
            basic: {
                username: "username",
                password: "password"
            }
        },
        fetchIntervalMS: 10000,
        tokenRefreshIntervalMS: 15000
    }
};

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

The `manager` object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `auth` | `object` | **Required.** User authentication configuration. |
| `cache` | `object` | Settings for persisting data received from **io.Manager**. *Available since **io.Connect Browser** 3.4.* |
| `features` | `object` | Settings for which **io.Manager** stores (apps, Layouts, app preferences) to retrieve and keep updated. *Available since **io.Connect Browser** 3.5.* |
| `fetchIntervalMS` | `number` | Interval in milliseconds at which a new snapshot of app definitions and Layouts will be fetched from **io.Manager**. Defaults to `60000`. |
| `getHeaders` | `function` | Callback that will be invoked on every request. Returns extra headers that will be merged with the existing ones. This callback can be used as a convenient way to refresh your access tokens. For more details, see the [Request Headers](#ioconnect_browser-request_headers) section. *Available since **io.Connect Browser** 3.4.* |
| `headers` | `object` | Object containing key/value pairs of headers to be sent with every request. |
| `requests` | `object` | Settings for the requests sent to **io.Manager**. *Available since **io.Connect Browser** 3.4.* |
| `tokenRefreshIntervalMS` | `number` | Interval in milliseconds at which the session token will be refreshed. Defaults to `3600000`. |
| `url` | `string` | **Required.** URL pointing to **io.Manager**. |

The `auth` object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `basic` | `object` | Object with required `username` and `password` properties for [Basic](https://docs.interop.io/manager/authentication/basic/index.md) authentication. |
| `username` | `string` | Username for authentication. |
| `token` | `object` | Object with an optional `bearer` property holding an access token for token-based authentication. Keep in mind that the token provided here can't be refreshed after it expires. To be able to refresh your access token, use the `getHeaders` property of the `manager` object. For more details, see the [Request Headers](#ioconnect_browser-request_headers) section. |

Available since io.Connect Browser 9.4

The `cache` object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `clearOld` | `boolean` | If `true`, on opening a new session to **io.Manager**, all cache databases from previous sessions will be deleted. Defaults to `false`. |
| `enabled` | `boolean` | If `true` (default), will enable caching and persisting data from **io.Manager** locally (e.g., in case of connection interruptions). |

The `requests` object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `closeSessionTimeout` | `number` | Interval in milliseconds to wait for a response to the `closeSession` request to **io.Manager**. Defaults to `10000`. |
| `openSessionTimeout` | `number` | Interval in milliseconds to wait for a response to the `openSession` request to **io.Manager** before proceeding from cache. Defaults to `10000`. |
| `timeout` | `number` | Interval in milliseconds to wait for a response from **io.Manager**. Defaults to `10000`. |

Available since io.Connect Browser 3.5

The `features` object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `applicationsStore` | `boolean` | If `true` (default), app definitions will be fetched periodically from the **io.Manager** app store. |
| `layoutsStore` | `boolean` | If `true` (default), Layout definitions will be fetched periodically from the **io.Manager** Layout store. |
| `preferencesStore` | `boolean` | If `true` (default), app preferences will be fetched periodically from the **io.Manager** app preferences store. |

### Request Headers

The `headers` object allows you to provide additional headers that will be sent with every request to **io.Manager**.

```javascript
// Defining additional headers that will be applied to every request sent to io.Manager.
const headers = {
    HeaderName: "HeaderValue",
    AnotherHeaderName: "AnotherHeaderValue"
};

const config = {
    licenseKey: "my-license-key",
    manager: {
        url: "https://my-io-manager.com:4242/api",
        // Providing additional headers.
        headers
    }
};

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

Available since io.Connect Browser 9.4

The `getHeaders` property can be used to provide a callback that will be invoked on every request sent to **io.Manager**. This offers a convenient way to refresh your access tokens. The callback will receive as an argument an object containing all current request headers. The information about the current headers can help you determine what additional headers to apply to the request in case you need to send different headers with the different requests. The callback must return an object with key/value pairs representing the additional request headers that will be merged with the existing ones.

The following example demonstrates how to provide a callback that will obtain and add to the headers a valid access token on each request sent to **io.Manager**:

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

// Callback for handling the request headers.
const getHeaders = async () => {
    // Your custom internal logic for refreshing and retrieving the access token.
    const token = await getAccessToken();

    const extraHeaders = {
        Authorization: `Bearer ${token}`
    };

    // The returned headers will be merged with the existing ones.
    return extraHeaders;
};

const config = {
    licenseKey: "my-license-key",
    manager: {
        url: "https://my-io-manager.com:4242/api",
        // Providing a callback that will be invoked on every request sent to io.Manager.
        getHeaders
    }
};

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