# 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](https://www.npmjs.com/package/@openfin/core).

Note - if you are a platform developer looking to setup an OpenFin Web Interop Broker, please check out [this guide](./platform-developer-guide.md).

## First Steps

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

```bash
npm install @openfin/web-interop -S
```

We recommend using `@openfin/web-interop` 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/web-interop` 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/web-interop` broker will return a fin connection.

### Example: Basic Connection Setup

```typescript
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, 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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
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

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

However, as Web Layouts is not publicly available yet, the `connect` `connectionInheritance` setting will default to `'disabled'`.

## API Reference

-   [@openfin/web-interop](out/docs/@openfin/web-interop/README.md)
-   [Fin API reference](https://developer.openfin.co/docs/javascript/stable)
-   [OpenFin Container Developer guide](https://developers.openfin.co/of-docs/docs/container-overview)