@aics/frontend-insights

@aics/frontend-insights

Light abstraction API on top of 3rd party monitoring/metrics/analytics tool(s).

Plugins

This library is useful insofar as 3rd party services are plugged into it; without plugins, it is effectively a noop API. Plugins are given to the default export of this package, the FrontendInsights class, which acts as a dispatcher of messages to its configured plugins.

This library defines an interface that must be implemented for each 3rd party service to be usable as a plugin to FrontendInsights. The interface is intentionally as generalized as possible. That interface is:

interface FrontendInsightsPlugin {
    process(message: FrontendInsightsMessage, context: FrontendInsightsContext): void;
}

External services should be initialized (e.g., given an API key) in a plugin constructor. Thereafter, it is the decision of the plugin whether to process some, all, or no messages distributed by the FrontendInsights class. For example, a plugin that works entirely by monkeypatching the browser's window.onerror event (as some browser-based exception monitoring services do), might choose to not process any messages. An analytics service, on the other hand, might choose to process FrontendInsightsMessageType.UserEvent and FrontendInsightsMessageType.UserTiming messages.

Additional plugins and message types may be added as necessary with no concern to existing usages of the library. If a new message type (FrontendInsightsMessageType) is added, it is recommended to add a specific public method to FrontendInsights for dispatching that type of message, similar to FrontendInsights::dispatchUserEvent.

Usage

import FrontendInsights, { FrontendInsightsContext } from "@aics/frontend-insights";
import AmplitudeNodePlugin from "@aics/frontend-insights-plugin-amplitude-node";

const context: FrontendInsightsContext = {
    application: {
        name: APP_ID,
        version: "4.2.2",
    },
    userInfo: {
        userId: "[e-mail]",
    },
    session: {
        platform: "Electron"
    }
};
const frontendInsights = new FrontendInsights(context, [
    new AmplitudeNodePlugin({ apiKey: "abc123" }),
    new WhateverPlugin({ ... }),  // e.g., could be others...
]);

frontendInsights.dispatchUserEvent({
    type: "ANY_STRING",
    properties: {
        foo: true,
        bar: "no",
        baz: 123,
    },
});