Web Interop

Web Interop allows web content to participate in OpenFin interoperability workflows such as context sharing, intents, and the OpenFin Channel API.

Web Interop allows web content that runs in a standard browser tab or a Progressive Web App (PWA) on a tablet to interact directly with other content in that browser tab or PWA. For example, a user could:

Select a contact from a view in their web browser.
Watch as the contact's portfolio appears in another view on that web browser tab through context sharing.

Web Interop enables cross-site communication in a "platform-like" environment within a single web browser tab.

To accomplish this, Web Interop requires the platform owner to host the following on the same domain:

The top-level app that embeds other content
The Web Broker server components described below

Any iframe running under such a top-level app can connect to the page's Web Broker of the page and interoperate, regardless of origin.

There are some limitations to what Web Interop is able to accomplish in a browser:

Web Interop does not connect web pages that exist in separate native web browser tabs. Web Interop cannot enable communication between native web browser tabs in a way that conflicts with web browsers' privacy sandboxes.
Web Interop works with cross-site and cross-origin websites so long as the Web Broker and the top-level app exist in the same origin.
- Examples of cross-site websites: example.com and ejemplo.com, or compare.com and contrast.com
- Examples of cross-origin websites: docs.example.com, support.example.com

OpenFin minimizes the differences between the desktop Interop and web Interop APIs. In most cases, code that works with the desktop Interop API works with the web Interop API, though some changes may be needed.

Web Interop for content developers

If you are a developer who is building content applications which use the OpenFin APIs, the default entry point of the Web Interop package provides a connect function. This is designed to complement the type definitions found in @openfin/core.

First steps for content developers

To install @openfin/web-interop, run the following command:

npm install @openfin/web-interop -S

We recommend using @openfin/web-interop with a modern build tool like Next.js, Webpack, or Vite.

Web Interop is framework agnostic; it is designed to work with any UI framework.

Connect to a Web Broker

An @openfin/web-interop Web Broker is a piece of hosted infrastructure that you can connect to from a web site in order to interact with other content connected to the same Web Broker. A Web Broker is responsible for deciding whether you can connect to it, and connecting you to other applications via OpenFin's Interop and Channels APIs.

When you connect to a @openfin/web-interop broker with a specific URL, it returns a fin connection.

Example: Basic connection setup

import { connect } from '@openfin/web-interop';

const brokerUrl = 'http://example.com/web-broker';

(async () => {
    // Connect to the OpenFin Web Broker.
    const fin = await connect({ options: { brokerUrl }});

    // You may now use the `fin` object. In this case, use it to connect to a channel.
    const channelClient = await fin.InterapplicationBus.Channel.connect('some channel name');
})();

Set a timeout

You can use the timeout option (in milliseconds) to specify to abandon the connection after a set amount of time.

The example below shows how to set up a 30-second timeout.

Example: Set a timeout

// This connect call throws if a connection is not established within 30 seconds.
await connect({ options: { brokerUrl, timeout: 30000 }});

Set up an interop connection

You can configure an Interop connection to automatically set up an interop client. You can then access the client via the fin.me.interop namespace.
You must specify a Provider ID. An example is shown below:

Example: Connect to an interop broker

// Specify an interopConfig with a specific provider ID to initialize the `fin.me.interop` client on connection.
const fin = await connect({ options: { brokerUrl, interopConfig: { providerId: 'PROVIDER_ID' }}});

// fin.me.interop is an InteropClient connected to the `PROVIDER_ID` InteropBroker.
fin.me.interop.addContextHandler((context) => console.log('received context'));

Specify an initial context group

By default OpenFin's Interop Client API does not select a context group. The following example illustrates setting up an initial context group during connection.

Example: Join a default context group

// Specify an interopConfig with a specific provider ID and a context group to initialize the `fin.me.interop` client on connection.
const fin = await connect({ options: { brokerUrl, interopConfig: { providerId: 'provider-id', currentContextGroup: 'red' }}});

// The fin.me.interop client adds a context handler which receives updates published on the `red` context group.
fin.me.interop.addContextHandler((context) => console.log('received context'));

Initialize FDC3

This library does not produce any global variables. To leverage FDC3, you can use the .getFDC3 or .getFDC3Sync APIs of a connected InteropClient. Note that with an Interop configuration provided in connect, fin.me.interop is instantiated as an InteropClient.

Supported versions for fdc3 are 1.2 or 2.0.

Example: Create an FDC3 client

import { connect } from '@openfin/web-interop';

const brokerUrl = 'http://example.com/web-broker';

// Specify an interopConfig with a specific provider ID and a context group to initialize the `fin.me.interop` client on connection.
const fin = await connect({ options: { brokerUrl, interopConfig: { providerId: 'PROVIDER_ID', currentContextGroup: 'red' }}});

// Set window.fdc3 to an FDC3 2.0 DesktopAgent which is connected to the `PROVIDER_ID` InteropBroker on the `red' channel.
window.fdc3 = fin.me.interop.getFDC3Sync('2.0');

Note that FDC3 support in web is currently limited to context sharing on system channels.

Context-aware connections and connection inheritance

The @openfin/web-interop API has been designed to support inheritance of brokerUrls and interop configurations if your content is running as a view within an OpenFin Layout. This allows content developers to develop platform-agnostic experiences and ensure that they are able to interact with other content connected to the same Web Broker.

Web Interop for platform developers

If you are a Platform owner who wishes to include OpenFin's web capabilities in your platform, a few steps are required. This section guides you through the process of setting up an environment.

First steps for platform developers

Ensure that @openfin/web-interop is installed by running the following command:

npm i @openfin/web-interop -S

Host the @openfin/web-interop shared worker

An @openfin/web-interop/shared-worker entry point is included in this package's distribution. This is a non-customizable, standalone piece of javascript that must be hosted on your server for @openfin/web-interop to function.

The shared-worker file has already been bundled, which means you just need to host it on a web server on a known URL.

Build a Web Broker

An HTML page, loaded as a hidden iframe by clients, must be hosted in the same origin as the @openfin/shared-worker. This iframe acts as a gatekeeper to the shared-worker and therefore must be hosted on the same domain.

In order to build a Web Broker, the following requirements must be met:

You must host the @openfin/web-interop/shared-worker bundle on a domain (for example https://www.example.com/mysharedworker.js).
You must host a web broker page on that same domain (for example, https://www.example.com/web-broker).
That page must call init from @openfin/web-interop/iframe-broker with the URL of the shared worker hosted in step 1.

// This code runs on https://www.example.com/web-broker
import {init} from '@openfin/web-interop/iframe-broker;

const sharedWorkerUrl = 'https://www.example.com/mysharedworker.js';

await init({sharedWorkerUrl})

Here is a basic example of hosting a Web Broker:

Example: Set up a basic Web Broker

First, host @openfin/web-interop/shared-worker at /openfin-shared-worker.js

File: iframe-broker.html

<html>
    <body>
        <script src ="iframe-broker.js"></script>
    </body>
</html>

File: iframe-broker.js

import { init } from '@openfin/web-interop/iframe-broker';

init({
    sharedWorkerUrl: `${location.origin}/openfin-shared-worker.js`
});

Reject connections

As an owner of an Iframe Broker, your first defence is existing web security tools such as the frame-ancestors CSP rule to prevent content that you don't expect from connecting to the broker.

You can implement your own custom logic for the rejectConnections utility function. If neither init or rejectConnection is invoked, an embedding client could hang indefinitely.

Example: Reject a cross-origin connection using @openfin/web-interop/iframe-broker

import { init, rejectConnections } from '@openfin/web-interop/iframe-broker';

// If the origins do not match.
if (new URL(document.referrer).origin !== location.origin) {
    rejectConnections({
        reason: 'Connections from this domain are not supported' // Reason allows an error to be returned to the connecting client.
    })
} else {
    init({
        sharedWorkerUrl: `${location.origin}/openfin-shared-worker.js`
    });
}

Experimental: Enable cross-tab support

By default, @openfin/web-interop disables the sharing of connections across browser tabs. However, this feature can be enabled by specifying the following flag in an iframe Broker:

init({
    sharedWorkerUrl: `${location.origin}/openfin-shared-worker.js`,
    experimental: {
        crossTab: 'same-site'
    }
});

Example: Enable cross-tab support

Note that cross-tab support is experimental, browser-dependent and respects each browser's privacy sandbox.