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:

    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.

sourcetypeactionentityIdevent description
HomeNavigationShowPlatform UUIDUser displayed Home, entered search term, and pressed enter.
HomeResultSelectSearch Result ID, Search Result TitleSearch result selected.
HomeFilterSelectFilter ValueSearch results filtered.
BrowserWindowOpenWindow UUID, Window Name
BrowserWindowCloseWindow UUID, Window Name
BrowserPageOpenPage/Tab UUID, Page/Tab Name
BrowserPageClosePage UUID, Page Name
BrowserToolbarNew PagePage UUID, Page Name
BrowserPage TabDragPage/Tab UUID, Page/Tab NamePage moved to change window layout.
BrowserViewOpenView UUID, View Name
BrowserViewCloseView UUID, View Name
BrowserView TabDragView UUID, View NameView moved to change window layout.
BrowserMenuGlobalContext menu of browser window selected.
BrowserGlobalItem NameMenu item of browser window context menu selected.
BrowserMenuPage TabPage context menu selected.
BrowserPage TabItem NameMenu item of page context menu selected.
BrowserMenuView TabView context menu selected.
BrowserView TabItem NameMenu item of view context menu selected.
BrowserToolbarItem or Item ButtonBrowser toolbar item selected.
BrowserItem ButtonItem NameMenu item of browser toolbar selected.
BrowserModalButtonItem Name
BrowserInteropjoin-group:App Name
NotificationsPlatformSelectPlatform UUID
NotificationsCenterClear AllPlatform ID, Notification Title
NotificationsCenterClearPlatform ID, Notification Title
NotificationsToastRemovePlatform ID, Notification Title
NotificationsToastButtonClickPlatform ID, Notification Title, Button Label Name
NotificationsCenterMenu ItemItem Name
NotificationsSettingsChangeSetting Type, Setting ValueSetting the user changed: which setting, and what changed.
DockNavigationSelectDock Item nameItem selected in Dock.
DockNavigationSwitch PlatformPlatform UUIDPlatform user switched to from Dock.
DockNavigationSwitch WorkspaceWorkspace Name
DockMore MenuSelectItem Name
DockNavigationSelectHome, Store, NC
StoreHeroSelectAsset NameHero selected from Storefront.
StoreLandingSelectAsset NameStore item selected from the landing page.
StoreLandingLaunchAsset NameApp launched from the landing page.
StoreLeft PanelSelectAsset NameApp grid selected from the left pane navigation.
StoreApp GridSelectAsset NameApp preview selected.
StoreApp GridLaunchAsset NameApp launched from the app grid.
StoreApp PreviewLaunchAsset NameApp launched from the app preview.