Skip to main content

Here™ Core UI Components events to log for analytics

Analytics can be an essential tool to help understand app usage, end-to-end workflows, performance, and more. Here™ Core UI 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 Here Core UI 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 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 an event (optional).

How to do it​

Start with a Here Core UI 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 events list is available as a PDF. The list includes the Here Core UI Components version the event was first provided in, and indicates whether the data is hashed if you choose to send events to Here™.

Optionally send to OpenFin​

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

Platform developers​

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

    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 Here™ implements an iframe to process and send event messages, you must also enable injection of the Here™ Core API into cross-origin iframes:

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

Desktop owners​

You can disable this option in desktop owner settings:

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

The default value of disableOpenFinAnalytics is false.

What Here™ collects​

If analytics data are sent to Here™, 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 Here™:

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

Table of Contents