Integrating freestanding apps with the JavaScript adapter

Most times, Finsemble launches your HTML apps. But there may be some that should not be launched by Finsemble. We call apps launched outside of Finsemble freestanding apps. Examples of freestanding apps include:

  • HTML apps running in WebViews within .NET or Java
  • JavaScript APIs running in native apps (such as MS Office)
  • Apps running in Chrome or in other browsers

Freestanding apps can participate in FDC3 interop using Finsemble's JavaScript adapter.

Loading the JavaScript adapter

You can find the JavaScript adapter and a sample app in your Finsemble npm package:

  • node_modules/@finsemble/finsemble-core/finsemble-javascript-adapter.js
  • node_modules/@finsemble/javascript-adapter-example-app.html

The JavaScript adapter must be loaded into your freestanding app using one of these methods:

  1. In a <script> tag:

The script file can be hosted anywhere that you choose. By default:

<script src="http://localhost:3375/build/finsemble/finsemble-javascript-adapter.js"></script>"
  1. Preload:

Some containers, such as webviews, offer the ability to preload (inject) JavaScript. This example demonstrates how to preload Finsemble's JavaScript adapter using DotNetBrowser (a popular webview for .NET):

// Load the app in a Browser object
IEngine engine = EngineFactory.Create();
IBrowser browser = engine.CreateBrowser();
browser.Navigation.LoadUrl("https://yourserver.com/yourapp.html");

// Inject the JavaScript adapter
IFrame mainFrame = browser.MainFrame;
mainFrame.ExecuteJavaScript<string>("<script src='http://localhost:3375/build/finsemble/finsemble-javascript-adapter.js'></script>");
mainFrame.ExecuteJavaScript<string>("FSBL.startApp()");

// Display in a Browserview
BrowserView view = new BrowserView();
view.InitializeFrom(browser);

Configuring the JavaScript adapter

Including the JavaScript adapter as a script or preload adds two global objects: FSBL and fdc3.

Your code must explicitly start the JavaScript adapter by calling FSBL.startApp(). This function takes optional parameters:

  • appName (string) - This is used to lookup your app in Finsemble's AppD configuration (e.g. appd.json). This name appears in logs and in development tools.
  • digitalSigningKey (string) - Provides a digital signing key that enables authenticated communication with Finsemble's interop service. appName is required and must match an AppD configuration containing the app's pubic key. See (Static Authentication)[].
  • windowName (string) - You can give your app a specific window name. This will appear in log messages.
  • routerAddress (string) - You can provide a url for Finsemble's IAC. The default is http://127.0.0.1:3376.

Example: Starting the JavaScript adapter with custom values

FSBL.start({
	appName: "TradeBlotter",
	digitalSigningKey: "todo",
	windowName: "TradeBlotterWebview",
	routerAddress: "http://127.0.0.1:4765"
});

FSBL.start() can also be preloaded/injected. We recommend this approach when you're loading 3rd party FDC3 apps into webviews.

Using the JavaScript adapter

After the JavaScript adapter is loaded and started you can begin to make FDC3 calls.

Example: YourApp.html

FSBL.start();
fdc3.broadcast({type:"symbol", id: {"symbol":"AAPL"}});

The FSBL API is not currently supported in the JavaScript adapter. Only FDC3 API calls are currently supported.