io.Connect Desktop

6.13.0

io.Connect Desktop is a desktop integration platform that enables functional and visual integration of web, native and legacy apps.

The io.Connect JavaScript library enables web apps to participate in io.Connect Desktop and use io.Connect functionalities via a set of APIs.

Referencing

From a JavaScript File

io.Connect JavaScript is a library 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 Core package is a subset of the Desktop package and offers basic functionalities for sharing data between apps (Interop, Shared Contexts, Pub/Sub, Metrics), while the Desktop package offers additional options for sharing data between apps (Channels), as well as advanced window management functionalities (App Management, Layouts, Window Management).

To install the io.Connect library in your project, execute the following command:

npm install @interopio/desktop

Initialization

The io.Connect Desktop library registers a global factory function called IODesktop() that will resolve with the initialized API object when invoked:

import IODesktop from "@interopio/desktop";

const io = await IODesktop();

Optionally, you can provide configuration for the library:

import IODesktop from "@interopio/desktop";

// Enabling the Channels API.
const config = { channels: true };

const io = await IODesktop(config);

Description

Instance of the initialized io.Connect library.

Properties

Property	Type	Description
agm	API	Interop library.
appManager	API	App Management API.
bus	API	Pub/Sub library.
channels	API	Channels API.
contexts	API	Contexts library.
cookies	API	Cookies API.
displays	API	Displays API.
hotkeys	API	Hotkeys API.
info	object	Info object containing versions of all included libraries and io.Connect itself.
intents	API	Intents API.
interception	API	Interception API. Available since io.Connect Desktop 9.6
interop	API	Interop library.
layouts	API	Layouts API.
logger	API
metrics	API	Metrics library.
notifications	API	Notifications API.
prefs	API	App Preferences API.
themes	API	Themes API.
version	string	io.Connect version.
windows	API	Window Management API.
workspaces	API	Workspaces API.

Methods

done

feedback

donemethod

Signature

() => Promise<void>

Description

Disposes the io.Connect API. This will remove all Interop methods and streams registered by the application.

feedbackmethod

Signature

(info?: FeedbackInfo) => void

Description

Brings up the IOConnect Desktop feedback dialog.

Parameters

Name	Type	Required	Description
info	FeedbackInfo

Description

Authentication can use one of the following flows:

username/password;
token - access tokens can be generated after successful login from the Auth Provider (e.g., Auth0);
gatewayToken - Gateway tokens are time limited tokens generated by the Gateway after an explicit request. To generate one, use the io.connection.authToken() method;
sspi - using sessionId and authentication challenge callback;

Properties

Property	Type	Description
flowCallback	(sessionId: string, token: any) => Promise<{ data: any; }>
flowName	"sspi"
gatewayToken	string	Authenticate using gatewayToken
password	string	Password to be used
provider	string	GW auth provider to be used
providerContext	any	A context object, which will be passed along to the GW auth provider to be used to request verification
sessionId	string
token	string	Authenticate using token generated from the auth provider.
username	string	Username to be used

Description

Optional configuration object for initializing the io.Connect library.

Properties

Property	Type	Default	Description
application	string		Application name. If not specified, the value depends on the hosting environment. For the browser - `document.title + random number` (e.g., ClientList321333). In desktop - `containerName + browserWindowName` (e.g., Internal.ClientList).
appManager	boolean \| "startOnly" \| "skipIcons" \| "full"	"startOnly"	Initializes or disables the App Management API. You can also specify mode in which that App Management API will be initialized.
auth	string \| Auth		Authentication can use one of the following flows: username/password; `token` - access tokens can be generated after successful login from the Auth Provider (e.g., Auth0); `gatewayToken` - Gateway tokens are time limited tokens generated by the Gateway after an explicit request. To generate one, use the `io.connection.authToken()` method; `sspi` - using `sessionId` and authentication challenge callback;
bus	boolean		Enable or disable the Pub/Sub API.
channels	boolean \| Configuration	false	Initializes or disables the Channels API.
contexts	boolean \| ContextsConfig		Enable, disable and configure the Contexts API.
customLogger	CustomLogger		Pass this to override the build-in logger and handle logging on your own
displays	boolean	true	Initializes or disables the Displays API.
exposeAPI	boolean	true	Determines whether io.Connect will share the initialized API object upon request via a custom web event.
gateway	GatewayConfig		Configurations for the io.Connect Gateway connection.
identity	{ [key: string]: string \| number \| boolean; }		Specify custom identity fields. Those can also override some of the system fields assigned
intents	Config		Configuration for the Intents Resolver UI.
layouts	boolean \| "full" \| "fullWaitSnapshot" \| "slim" \| Configuration	"slim"	Initializes or disables the Layouts API. You can also specify mode and configuration with which that Layouts API will be initialized.
libraries	((io: API, config?: Config) => Promise<void>)[]		A list of io.Connect factory functions that will be initialized internally to provide access to specific functionalities.
logger	"off" \| "trace" \| "debug" \| "info" \| "warn" \| "error" \| LoggerConfig		Defines logging levels per output target.
metrics	boolean \| MetricsConfig		Metrics configurations.
windows	boolean	true	Initializes or disables the Window Management API.

Description

Allows customizing the feedback form

Properties

Property	Type	Default	Required	Description
message	string			Will be added to the description field in the feedback form

Description

Configurations for the io.Connect Gateway connection.

Properties

Property	Type	Default	Description
gwTokenProvider	GwTokenProvider		A way to pass custom token provider for Gateway v.3 tokens.
inproc	InprocGWSettings		Connect with GW in memory
protocolVersion	number		Legacy (Version of the Gateway that you are connected to)
reconnectAttempts	number	10	Number of reconnect attempts.
reconnectInterval	number	500	Reconnect interval in milliseconds.
sharedWorker	string
webPlatform	WebPlatformConnection		An object containing the configuration settings when core is operating in a web platform environment
ws	string		URL for the WebSocket connections to the Gateway.

Properties

Property	Type	Default	Required	Description
facade	IOConnectCore

Properties

Property	Type	Default	Required	Description
console	LogLevel			Console logging level.
publish	LogLevel			File logging level. To allow logging to files in your apps, you must set the `"allowLogging"` top-level property to `true` in the app definition.

Description

Metrics configurations.

Properties

Property	Type	Default	Required	Description
disableAutoAppSystem	boolean			If `false` (default), an App system will be created on top level, and all other metrics will live in it. If `true`, an App system will be created, and all metrics will live on top level.
pagePerformanceMetrics	PagePerformanceMetricsConfig

Properties

Property	Type	Default	Required	Description
enabled	boolean
initialPublishTimeout	number
publishInterval	number

Properties

Property	Type	Default	Required	Description
allowedOrigins	string[]
port	MessagePort
windowId	string