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 customize-workspace example in the workspace-starter GitHub repository.

Events list

The following table lists the required fields of the AnalyticsEvent object plus the entityId where available.