`@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:
``typescript 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 theFrontendInsightsclass. For example, a plugin that works entirely by monkeypatching the browser'swindow.onerrorevent (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 processFrontendInsightsMessageType.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 toFrontendInsights 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: "leaping_kangaroo@example.com", }, 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, }, });``

Plugins

typescript
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: "leaping_kangaroo@example.com",
    },
    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,
    },
});