Workspace events to log for analytics

Analytics can be an essential tool to help understand app usage, end-to-end workflows, performance, and more. Workspace Analytics supports your analysis needs with workspace platform events that you can log or otherwise write to your analytics solution.

How it works

The WorkspacePlatformProvider interface provides a handleAnalytics method that takes an AnalyticsEvent parameter object. This method is called when the events documented in this article are emitted. It's up to the provider to create an implementation to write the event information to the appropriate location.

You write these events to your preferred logging or analytics solution, or to console.log.

The AnalyticsEvent object does not include a timestamp. Events are typically passed to the handleAnalytics method when they are emitted, so you can add the timestamp of each event to your preferred logging or analytics implementation.

The AnalyticsEvent type declaration:

export type AnalyticsEvent = {
    source: AnalyticsSource;
    type: string;
    action: string;
    value?: string;
    entityId?: OpenFin.Identity;
    data?: any;
};

Where:

• source = the Workspace component the event was emitted from. One of:

  JavaScript

  export enum AnalyticsSource {
      Browser = 'Browser',
      Dock = 'Dock',
      Home = 'Home',
      Notification = 'Notification',
      Storefront = 'Storefront',
      Platform = 'Platform',
      Theming = 'Theming',
      Interop = 'Interop'
  }
  

• type = the UI element the Workspace user interacted with

• action = the user interaction that fired the event

• value = the result of the user interaction. Depending on the user interaction, this field might not be populated (optional).

• entityId = depending on the user interaction, the UUID of the result, the name of the result, or both (optional).

• data = any additional information the provider includes in an object that emits a Workspace event (optional).

How to do it

Start with a Workspace platform override:

import * as WorkspacePlatform from '@openfin/workspace-platform';

const overrideCallback: WorkspacePlatform.WorkspacePlatformOverrideCallback = async (
   WorkspacePlatformProvider
) => {
  class Override extends WorkspacePlatformProvider {
      handleAnalyticsEvent = async (event: WorkspacePlatform.AnalyticsEvent[]) => {
        // do something with the event
      };  
  }
  return new Override();
};

await WorkspacePlatform.init({ overrideCallback });

Then handle the emitted events as your analytics solution requires.

An example that writes events to the console is provided as part of the Workspace Platform starter example in the workspace-starter GitHub repository.

Events list

The events list is available as a PDF. The list includes the Workspace version the event was first provided in, and indicates whether the data is hashed if you choose to send events to OpenFin.

Optionally send to OpenFin

Starting in Workspace v12.6, platform developers can choose to send analytics events to OpenFin. OpenFin analyzes this information to understand the usage of the OpenFin Workspace product. To ensure that OpenFin does not receive any private information, events that can include sensitive information are hashed before they are sent to OpenFin. Whether an event is hashed is indicated in the events list. Even if a platform opts into sending events to OpenFin, desktop owners can block this capability.

Platform developers

1. Add the analytics property to the WorkspacePlatform.init call:

   JavaScript

   import * as WorkspacePlatform from '@openfin/workspace-platform';
   
   await WorkspacePlatform.init({
     browser: { overrideCallback },
     theme: customThemes,
     analytics: {
       sendToOpenfin: true
     }
   });
   

   The default value of sendtoOpenFin is false.

2. Because OpenFin implements an iframe to process and send event messages, you must also enable injection of the OpenFin API into cross-origin iframes:

   JSON

   {
     "platform": {
       "api": {
         "iframe": {
           "crossOriginInjection": true
         }
       },
       "uuid": "my-uuid",
       "name": "my-name",
       // app config continues ...
     }
   }
   

Desktop owners

You can disable this option in the Desktop Owner Settings file:

{ 
  "desktopSettings": { 
    "systemApps": { 
      "workspace": { 
        "version": "13.0",
        "customConfig": {
           "disableOpenFinAnalytics": true
        }
      }
    }
  }
}

The default value of disableOpenFinAnalytics is false.

What OpenFin collects

If analytics data are sent to OpenFin, in addition to the event data, the user ID and some other potentially sensitive items are included in the payload. The following information is hashed before it is sent to OpenFin:

• combined_id (concatenated username and machine_id)
• machine_id
• username