@openfin/native-window-integration-client

OpenFin NWI Library

This library exports the NativeWindowIntegrationClient class to connect to a native component and add native windows to snapshots.

This class has the following methods: static create(options) A factory method which launches the provider and creates a connection to it.

decorateSnapshot(snapshot) an instance method which adds native window information to a snapshot.

applySnapshot(snapshot) an instance which will look for native window information in a snapshot and attempt to restore it.

Prerequisites

• OpenFin Runtime >= 20...*
• Some form of build script (see Hosting)
• Windows 10
• The correct api permissions

Installation

npm i @openfin/native-window-integration-client

Usage

Import the native provider into your project, see hosting, and create a connection to it using the NativeWindowIntegrationClient.create method, the url to the hosted native provider/asset should be passed in as the url property in the client options.

import { NativeWindowIntegrationClient } from '@openfin/native-window-integration-client';
// native provider url loaded using webpack's file-loader
import assetUrl from '@openfin/native-window-integration-client/lib/provider.zip';


const configuration = [
    {
        'name': 'Notepad',
        'title': 'my_platform_notes',
        'launch': {
            'alias': 'my_platform_notes',
            'target': 'my_platform_notes.txt',
            'lifetime': 'application',
            'arguments': ''
        }
    },
    {
        'name': 'Symphony',
        'title': 'Symphony',
        'launch': {
            'path': 'C:\\Users\\openfin\\AppData\\Local\\Programs\\Symphony\\Symphony\\Symphony.exe',
            'lifetime': 'application'
        }
    }
]

fin.Platform.init({
    overrideCallback: async (PlatformProvider, ...args) => {
        try {
            console.log('Native Window Integration Client is connecting...');
            const myClient = await NativeWindowIntegrationClient.create({ url: assetUrl, configuration });
            console.log('Native Window Integration Client connected successfully!');

            class WithNative extends PlatformProvider {
                async getSnapshot(...args: [undefined, OpenFin.ClientIdentity]) {
                    const snapshot = await super.getSnapshot(...args);
                    try {
                        const snapshotWithNativeWindows = await myClient.decorateSnapshot(snapshot);
                        return snapshotWithNativeWindows;
                    } catch (error) {
                        console.log('Native Window Integration failed to get snapshotWithNativeWindows:');
                        console.error(error);
                        return snapshot;
                    }
                }
                async applySnapshot(...args: [OpenFin.ApplySnapshotPayload, OpenFin.ClientIdentity]) {
                    await super.applySnapshot(...args);
                    try {
                        await myClient.applySnapshot(args[0].snapshot);
                    } catch (error) {
                        console.log('Native Window Integration error applying native snapshot:');
                        console.error(error);
                    }
                }
            }
            console.log('Native Window Integration successfully enabled!');
            return new WithNative(...args);
        } catch (error) {
            console.log('Native Window Integration failed to initialize:');
            console.error(error);
            return new PlatformProvider(args);
        }
    }
});

API Permissions Requirements

Necessary OpenFin Secure APIs permissions:

• System.downloadAsset
• System.launchExternalProcess
• System.enableNativeWindowIntegrationProvider

These will be called internally by the library.

Hosting

The native provider must be hosted. We highly reccomend using a tool such as webpack's file-loader to include the asset as part of your build to ensure versions stay in sync between the provider and library. Version mismatches will cause the NativeWindowClient.Create call to fail. Copying the provider.zip file to your project's root directory will cause version mismatches when the library is updated, which is why we recommend using a tool such as webpack to include the asset as part of your build.

####Example of hosting the native provider with webpack's file-loader:

module.exports = {
  module: {
    rules: [
      {
        test: /\.(zip)/,
        use: [
          {
            loader: 'file-loader',
             options: {
                            name: '[name].[ext]',
                            outputPath: 'static/',
                        }
          },
        ],
      },
    ],
  },
};