@equinor/fusion-framework-module-analytics 3.0.8-next.0 → 3.0.8

package/CHANGELOG.md

@@ -1,13 +1,11 @@
 # @equinor/fusion-framework-module-analytics
 
-## 3.0.8-next.0
+## 3.0.8
 
 ### Patch Changes
 
-- c8008e3: Internal: rebase `next` onto `main`, syncing in already-published stable releases so they carry a `next` pre-release tag.
-- Updated dependencies [c8008e3]
-  - @equinor/fusion-framework-module-app@8.0.6-next.0
-  - @equinor/fusion-framework-module-context@9.0.0-next.0
+- Updated dependencies [6b449ae]
+  - @equinor/fusion-observable@9.2.0
 
 ## 3.0.7
 

package/README.md

@@ -3,15 +3,6 @@
 Fusion Framework module for collecting and exporting application analytics using
 OpenTelemetry standards.
 
-## Who should use this
-
-- **Application and portal developers** who want to track user interactions
-  (clicks, context changes, app usage) without wiring up telemetry by hand.
-- **Module authors** who want their module's lifecycle events picked up by
-  analytics automatically via a collector.
-- **Test authors** who need to assert which analytics events an app or
-  collector produced.
-
 ## Overview
 
 The analytics module provides a pluggable **adapter/collector** architecture:
@@ -31,16 +22,6 @@ When a collector emits an event it is delivered to **every** registered adapter.
 | `@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` |
-| `@equinor/fusion-framework-module-analytics/mock` | `MockAnalyticsAdapter` — record tracked events for test assertions |
-
-## Documentation
-
-| Topic | Description |
-|---|---|
-| [Adapters](docs/adapters.md) | `ConsoleAnalyticsAdapter`, `FusionAnalyticsAdapter`, and creating a custom `IAnalyticsAdapter` |
-| [Collectors](docs/collectors.md) | Built-in collectors (context/app selection, app loaded) and creating a custom `IAnalyticsCollector` |
-| [Tracking Events Manually](docs/tracking-events.md) | `provider.trackAnalytic` / `trackAnalytic$` for ad-hoc event tracking |
-| [Testing](docs/testing.md) | `MockAnalyticsAdapter`, recording and awaiting tracked events, and using a bespoke `ModulesConfigurator` in tests |
 
 ## Quick Start
 
@@ -71,6 +52,217 @@ const configure = (configurator) => {
 > Fusion Framework module system. Manual initialisation is only required when
 > accessing the provider directly.
 
-See [Adapters](docs/adapters.md), [Collectors](docs/collectors.md), and
-[Tracking Events Manually](docs/tracking-events.md) for the full adapter/collector
-reference and how to build your own.
+## 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.
+
+```typescript
+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)
+
+```typescript
+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)
+
+```typescript
+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`:
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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).
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+// 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
+
+```typescript
+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
+
+```typescript
+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);
+        },
+      };
+    });
+  });
+}
+```

package/dist/esm/version.js

@@ -1,3 +1,3 @@
 // Generated by genversion.
-export const version = '3.0.8-next.0';
+export const version = '3.0.8';
 //# sourceMappingURL=version.js.map

package/dist/esm/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAC3B,MAAM,CAAC,MAAM,OAAO,GAAG,cAAc,CAAC"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAC3B,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}