@equinor/fusion-framework-module-analytics

Fusion Framework module for collecting and exporting application analytics using
OpenTelemetry standards.

Overview

The analytics module provides a pluggable adapter/collector architecture:

• Collectors observe application state (context changes, app selection,
  app loads) and emit structured AnalyticsEvent objects.
• Adapters receive those events and forward them to a backend — the browser
  console for debugging, or an OTLP-compatible endpoint for production.

When a collector emits an event it is delivered to every registered adapter.

Entry points

Import path	Contents
@equinor/fusion-framework-module-analytics	Module definition, enableAnalytics, core types
@equinor/fusion-framework-module-analytics/adapters	ConsoleAnalyticsAdapter, FusionAnalyticsAdapter, IAnalyticsAdapter
@equinor/fusion-framework-module-analytics/collectors	ContextSelectedCollector, AppSelectedCollector, AppLoadedCollector, IAnalyticsCollector
@equinor/fusion-framework-module-analytics/logExporters	OTLPLogExporter, FusionOTLPLogExporter

Quick Start

Call enableAnalytics inside your application or portal configuration callback
to register adapters and collectors:

import { enableAnalytics } from '@equinor/fusion-framework-module-analytics';
import { ConsoleAnalyticsAdapter } from '@equinor/fusion-framework-module-analytics/adapters';
import { ContextSelectedCollector } from '@equinor/fusion-framework-module-analytics/collectors';

const configure = (configurator) => {
  enableAnalytics(configurator, (builder) => {
    // Register an adapter — receives every event
    builder.setAdapter('console', async () => new ConsoleAnalyticsAdapter());

    // Register a collector — emits events on context change
    builder.setCollector('context-selected', async (args) => {
      const contextProvider = await args.requireInstance('context');
      const appProvider = await args.requireInstance('app');
      return new ContextSelectedCollector(contextProvider, appProvider);
    });
  });
};

Note: The analytics module initialises automatically when used inside the
Fusion Framework module system. Manual initialisation is only required when
accessing the provider directly.

Adapters

Adapters implement IAnalyticsAdapter and are responsible for processing and
sending analytics data to their destinations. All adapters support async
initialisation and will be initialised automatically when the provider starts.

ConsoleAnalyticsAdapter

Logs every analytics event to the browser console. Useful for development and
debugging. No configuration required.

builder.setAdapter('console', async () => new ConsoleAnalyticsAdapter());

FusionAnalyticsAdapter

Forwards analytics events to an OpenTelemetry-compatible log endpoint via a
bundled LoggerProvider.

Configuration options:

Option	Type	Description
portalId	string	Portal identifier included in every log record
logExporter	OTLPExporterBase	OTLP log exporter for transport

Using OTLPLogExporter (direct HTTP)

import { OTLPLogExporter } from '@equinor/fusion-framework-module-analytics/logExporters';
import { FusionAnalyticsAdapter } from '@equinor/fusion-framework-module-analytics/adapters';

builder.setAdapter('fusion-log', async () => {
  const logExporter = new OTLPLogExporter({
    url: 'https://example.com/v1/logs',
    headers: { 'Content-Type': 'application/json' },
  });
  return new FusionAnalyticsAdapter({ portalId: 'my-portal', logExporter });
});

Using FusionOTLPLogExporter (service discovery HTTP client)

import { FusionOTLPLogExporter } from '@equinor/fusion-framework-module-analytics/logExporters';
import { FusionAnalyticsAdapter } from '@equinor/fusion-framework-module-analytics/adapters';

builder.setAdapter('fusion', async (args) => {
  if (args.hasModule('serviceDiscovery')) {
    const sd = await args.requireInstance('serviceDiscovery');
    const httpClient = await sd.createClient('analytics');
    const logExporter = new FusionOTLPLogExporter(httpClient);
    return new FusionAnalyticsAdapter({ portalId: 'my-portal', logExporter });
  }
  console.error('Service discovery unavailable — analytics adapter not created');
});

Creating a Custom Adapter

Implement IAnalyticsAdapter and register it with setAdapter:

import type { IAnalyticsAdapter } from '@equinor/fusion-framework-module-analytics/adapters';
import type { AnalyticsEvent } from '@equinor/fusion-framework-module-analytics';

class MyRemoteAdapter implements IAnalyticsAdapter {
  registerAnalytic(event: AnalyticsEvent): void {
    navigator.sendBeacon('/analytics', JSON.stringify(event));
  }

  [Symbol.dispose](): void {
    // cleanup if needed
  }
}

builder.setAdapter('remote', async () => new MyRemoteAdapter());

Collectors

Collectors implement IAnalyticsCollector (or extend BaseCollector) and emit
AnalyticsEvent objects that are forwarded to all adapters. All collectors
support async initialisation.

ContextSelectedCollector

Emits an event when the active Fusion context changes. Includes the new context,
the previous context, and the current app key in attributes.

builder.setCollector('context-selected', async (args) => {
  const ctx = await args.requireInstance('context');
  const app = await args.requireInstance('app');
  return new ContextSelectedCollector(ctx, app);
});

AppSelectedCollector

Emits an event when the active application changes. Includes the new and
previous app key metadata.

builder.setCollector('app-selected', async (args) => {
  const app = await args.requireInstance('app');
  return new AppSelectedCollector(app);
});

AppLoadedCollector

Emits an event when an application's modules finish loading. Includes app
manifest metadata and the current context (if available).

builder.setCollector('app-loaded', async (args) => {
  const event = await args.requireInstance('event');
  const app = await args.requireInstance('app');
  return new AppLoadedCollector(event, app);
});

Creating a Custom Collector

Extend BaseCollector with a Zod schema for validation:

import { BaseCollector, createSchema } from '@equinor/fusion-framework-module-analytics/collectors';
import { z } from 'zod';
import { of } from 'rxjs';

const schema = createSchema(z.string(), z.object({ page: z.string() }));

class PageViewCollector extends BaseCollector<string, { page: string }> {
  constructor() {
    super('page-view', schema);
  }

  _initialize() {
    return of({ value: window.location.pathname, attributes: { page: document.title } });
  }
}

Tracking Events Manually

The provider exposes methods for ad-hoc event tracking outside of collectors:

// Single event
provider.trackAnalytic({
  name: 'button-click',
  value: 'save',
  attributes: { section: 'toolbar' },
});

// Observable stream
const subscription = provider.trackAnalytic$(myEvent$);
// later: subscription.unsubscribe();

Configuration

The Context Selected Collector needs the context provider.

Example configuration

import { enableAnalytics } from '@equinor/fusion-framework-module-analytics';
import { ContextSelectedCollector } from '@equinor/fusion-framework-module-analytics/collectors';

const configure = (configurator: IModulesConfigurator<any, any>) => {
  enableAnalytics(configurator, (builder) => {
    builder.setCollector('context-selected', async (args) => {
      const contextProvider = await args.requireInstance('context');
      const appProvider = await args.requireInstance('app');
      return new ContextSelectedCollector(contextProvider, appProvider);
    });
  });
}

Creating Custom Collectors

You can create custom analytics collector by extending the BaseCollector class,
or implement the IAnalyticsCollector interface and add it in configuration.

Example Custom Collector

import { type AnalyticsEvent, enableAnalytics } from '@equinor/fusion-framework-module-analytics';

const configure = (configurator: IModulesConfigurator<any, any>) => {
  enableAnalytics(configurator, (builder) => {
    builder.setCollector('click-test', async () => {
      const subject = new Subject<AnalyticsEvent>();
      window.addEventListener('click', (e) => {
        subject.next({
          name: 'window-clicker',
          value: 42,
        });
      });

      return {
        subscribe: (subscriber) => {
          return subject.subscribe(subscriber);
        },
      };
    });
  });
}