# Platform Developer Guide

If you are a Platform owner who wishes to include OpenFin's web capabilities in your platform, there are a few steps required. This section will guide you through the process of setting up an environment. Please note, none of these steps are necessary for content developers (See the [content developer guide](web-application-developer-guide.md)).

## First Steps

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

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

## Hosting 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. 

This file has already been bundled, which means consumers just need to host it on their server on a known url.

## Building 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:
1. You must host the `@openfin/web-interop/shared-worker` bundle on a domain (for example https://www.example.com/mysharedworker.js).
2. You must host a web broker page on that same domain (for example, https://www.example.com/web-broker).
3. That page must call `init` from `@openfin/web-interop/iframe-broker` with the url of the shared worker hosted in step 1.
   ```typescript
   // 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: Setting up a Basic Web Broker

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

_iframe-broker.html_

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

_iframe-broker.js_

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

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

```

## Rejecting Connections

As an owner of an Iframe Broker, you should first and foremost rely on existing web security tools such as the frame-ancestors CSP rule to prevent content from connecting to you which you don't expect.

`@openfin/web-interop` exposes a `rejectConnections` utility if you wish to implement more bespoke logic. If neither `init` or `rejectConnection` is invoked, an embedding client may hang indefinitely.

#### Example: Rejecting a Cross Origin Connection using `@openfin/web-interop/iframe-broker`

```typescript
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: Enabling Cross Tab Support

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

### Example: Enabling Cross Tab Support

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

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

## API Reference

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