Openfin Web Application Developer Guide

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

Note - if you are a platform developer looking to setup an OpenFin Web Interop Broker, please check out this guide.

First Steps

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

npm install @openfin/core-web -S

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

It is framework agnostic, meaning it should work with any UI framework.

Connecting to a Web Broker

An @openfin/core-web Web Broker is a piece of hosted infrastructure which 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 the Web Broker url is known, connecting to a specific @openfin/core-web broker will return a fin connection.

Example: Basic Connection Setup

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

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, we connect to a channel.
    const channelClient = await fin.InterapplicationBus.Channel.connect('some channel name');
})();

Setting a Timeout

If desired, the timeout option (in milliseconds) can be specified to abandon the connection after a set amount of time.

An example below shows setting up a 30 second timeout.

Example: Setting a Timeout

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

Setting up an Interop Connection

An Interop connection can be configured in order to automatically set up an interop client. This client may be accessed via the fin.me.interop namespace.

A Provider ID must be specified for the fin.me.interop client to work if connectionInheritance is not supported. An example is shown below:

Example: Connecting 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'));

Specifying 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: Joining 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 will receive updates published on the `red` context group.
fin.me.interop.addContextHandler((context) => console.log('received context'));

Initializing FDC3

This library does not produce any global variables. To leverage FDC3 you may use the .getFDC3 or .getFDC3Sync apis of a connected InteropClient. (Note that with an interop config provided in connect fin.me.interop is instantiated as an InteropClient)

Supported versions for fdc3 are 1.2 or 2.0.

Example: Creating an FDC3 Client

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

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

@openfin/core-web 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.

Capture debug logs to your own services

@openfin/core-web enables capturing logs via an optional logger connection option. It accepts an implementation of CustomLogger, which allows you to forward logs to your own logging infrastructure or external services.

The CustomLogger interface requires four methods: debug, info, warn, and error, each accepting a string message.

import { connect, type CustomLogger } from '@openfin/core-web';

const myLogger: CustomLogger = {
    debug: (message: string) => {...},
    info: (message: string) => {...},
    warn: (message: string) => {...},
    error: (message: string) => {...}
};

const fin = await connect({
    ...,
    logger: myLogger,
    logLevel: 'debug'
});

Note: The logger option respects the logLevel setting. Only messages at or above the specified level will get propagated.

API Reference

(Please note, this link works in your IDE and not on npmjs.com, we will update this soon.)

@openfin/core-web