feat: add user activity tracking for embedded apps

Author: mrednic-1A

packages/@ama-mfe/messages/src/messages/user-activity/base.ts

@@ -0,0 +1,14 @@
+/** The user activity message type used for communication between shell and iframes */
+export const USER_ACTIVITY_MESSAGE_TYPE = 'user_activity';
+
+/**
+ * Types of user activity events that can be tracked
+ */
+export type UserActivityEventType =
+  | 'click'
+  | 'keydown'
+  | 'scroll'
+  | 'touchstart'
+  | 'focus'
+  | 'visibilitychange'
+  | 'iframeinteraction';

packages/@ama-mfe/messages/src/messages/user-activity/index.ts

@@ -0,0 +1,8 @@
+import type {
+  UserActivityMessageV1_0,
+} from './user-activity-versions';
+
+/** The versions of user activity messages */
+export type UserActivityMessage = UserActivityMessageV1_0;
+export * from './user-activity-versions';
+export { USER_ACTIVITY_MESSAGE_TYPE, type UserActivityEventType } from './base';

packages/@ama-mfe/messages/src/messages/user-activity/user-activity-versions.ts

@@ -0,0 +1,22 @@
+import type {
+  VersionedMessage,
+} from '@amadeus-it-group/microfrontends';
+import type {
+  USER_ACTIVITY_MESSAGE_TYPE,
+  UserActivityEventType,
+} from './base';
+
+/**
+ * User activity message version 1.0
+ * Sent from embedded modules to the shell to indicate user interaction
+ */
+export interface UserActivityMessageV1_0 extends VersionedMessage {
+  /** @inheritdoc */
+  type: typeof USER_ACTIVITY_MESSAGE_TYPE;
+  /** @inheritdoc */
+  version: '1.0';
+  /** The type of activity event that occurred */
+  eventType: UserActivityEventType;
+  /** Timestamp when the activity occurred */
+  timestamp: number;
+}

packages/@ama-mfe/messages/src/public_api.ts

@@ -2,3 +2,4 @@ export * from './messages/history/index';
 export * from './messages/navigation/index';
 export * from './messages/resize/index';
 export * from './messages/theme/index';
+export * from './messages/user-activity/index';

packages/@ama-mfe/ng-utils/README.md

@@ -295,3 +295,157 @@ The host information is stored in session storage so it won't be lost when navig
 When using iframes to embed applications, the browser history might be shared by the main page and the embedded iframe. For example `<iframe src="https://example.com" sandbox="allow-same-origin">` will share the same history as the main page. This can lead to unexpected behavior when using browser 'back' and 'forward' buttons.
 
 To avoid this, the `@ama-mfe/ng-utils` will forbid the application running in the iframe to alter the browser history. It will happen when connection is configured using `provideConection()` function. This will prevent the iframe to be able to use the `history.pushState` and `history.replaceState` methods.
+
+### User Activity Tracking
+
+The User Activity Tracking feature allows a host application (shell) to monitor user interactions across embedded micro-frontends. This is useful for implementing session timeout functionality, analytics, or any feature that needs to know when users are actively interacting with the application.
+
+#### How it works
+
+- **Producer**: The `ActivityProducerService` listens for DOM events (click, keydown, scroll, touchstart, focus) and:
+  - Exposes a `localActivity` signal for consumers within the same application (not throttled for local detection).
+  - Sends throttled activity messages via the communication protocol to connected peers.
+- **Consumer**: The `ActivityConsumerService` receives activity messages from connected peers via the communication protocol and exposes them via the `latestReceivedActivity` signal.
+
+Both services can be used in either the shell (host) or embedded applications depending on your use case. For example:
+- A shell can produce activity signals to notify embedded modules of user interactions in the host.
+- An embedded module can consume activity signals from the shell.
+- An application can use the producer's `localActivity` signal to detect activity locally.
+
+The service automatically throttles messages sent to peers to prevent flooding the communication channel. High-frequency events like `scroll` have additional throttling.
+
+#### Producer Configuration
+
+Start the `ActivityProducerService` to send activity signals to connected peers:
+
+```typescript
+import { inject, runInInjectionContext } from '@angular/core';
+import { bootstrapApplication } from '@angular/platform-browser';
+import { ConnectionService, ActivityProducerService } from '@ama-mfe/ng-utils';
+
+bootstrapApplication(App, appConfig)
+  .then((m) => {
+    runInInjectionContext(m.injector, () => {
+      if (window.top !== window.self) {
+        inject(ConnectionService).connect('hostUniqueID');
+        // Start activity tracking with custom throttle
+        inject(ActivityProducerService).start({
+          throttleMs: 5000 // Send at most one message every 5 seconds
+        });
+      }
+    });
+  });
+```
+
+##### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `throttleMs` | `number` | `1000` | Minimum interval between activity messages sent to the host |
+| `trackNestedIframes` | `boolean` | `false` | Enable tracking of nested iframes within the application |
+| `nestedIframePollIntervalMs` | `number` | `1000` | Polling interval for detecting iframe focus changes |
+| `nestedIframeActivityEmitIntervalMs` | `number` | `30000` | Interval for sending activity signals while an iframe has focus |
+| `highFrequencyThrottleMs` | `number` | `300` | Throttle time for high-frequency events (scroll) |
+| `shouldBroadcast` | `(event: Event) => boolean` | - | Optional filter function to control which events are broadcast |
+
+##### Filtering Events with shouldBroadcast
+
+The `shouldBroadcast` option allows you to filter which events trigger activity messages. This is useful in the shell application to exclude events that occur on iframes, since user activity inside embedded modules is already tracked via the communication protocol.
+
+```typescript
+// In the shell application
+inject(ActivityProducerService).start({
+  throttleMs: 1000,
+  shouldBroadcast: (event: Event) => {
+    // Exclude events on iframes - activity from embedded modules comes via the communication protocol
+    return !(event.target instanceof HTMLIFrameElement);
+  }
+});
+```
+
+##### Tracking Nested Iframes
+
+When a user interacts with content inside an iframe (e.g., a third-party widget, payment form, or embedded content), the parent application cannot detect those interactions directly. This is because:
+
+1. **Cross-origin restrictions**: DOM events inside cross-origin iframes do not bubble up to the parent document.
+2. **Focus isolation**: When an iframe has focus, the parent document stops receiving keyboard and mouse events.
+
+This creates a problem for detection of user interactions: a user could be actively filling out a form inside an iframe, but the host application would see no activity and might incorrectly trigger a session timeout.
+
+**Solution**: When `trackNestedIframes` is enabled, the `ActivityProducerService` polls `document.activeElement` to detect when an iframe gains focus. While an iframe has focus, the service simulates activity by periodically emitting `iframeinteraction` events. This ensures the host application knows the user is still active, even though it cannot see the actual interactions inside the iframe.
+
+Enable nested iframe tracking in embedded applications that contain other iframes:
+
+```typescript
+inject(ActivityProducerService).start({
+  throttleMs: 5000,
+  trackNestedIframes: true,
+  nestedIframePollIntervalMs: 1000, // Check for iframe focus every second
+  nestedIframeActivityEmitIntervalMs: 30000 // Send activity every 30s while iframe has focus
+});
+```
+
+**When to use**: Enable this option in embedded modules that contain iframes whose content you cannot modify to include activity tracking (e.g., third-party widgets, payment providers, or external content).
+
+#### Consumer Configuration
+
+Start the `ActivityConsumerService` to receive activity signals from connected peers:
+
+```typescript
+import { Component, inject, effect } from '@angular/core';
+import { ActivityConsumerService } from '@ama-mfe/ng-utils';
+
+@Component({
+  selector: 'app-shell',
+  template: '...'
+})
+export class ShellComponent {
+  private readonly activityConsumer = inject(ActivityConsumerService);
+
+  constructor() {
+    // Start listening for activity messages
+    this.activityConsumer.start();
+
+    // React to activity changes
+    effect(() => {
+      const activity = this.activityConsumer.latestReceivedActivity();
+      if (activity) {
+        console.log(`Activity from ${activity.channelId}: ${activity.eventType} at ${activity.timestamp}`);
+        // Reset session timeout, update analytics, etc.
+      }
+    });
+  }
+
+  ngOnDestroy() {
+    this.activityConsumer.stop();
+  }
+}
+```
+
+#### Local Activity Signal
+
+The `ActivityProducerService` also exposes a `localActivity` signal for detecting activity within the same application:
+
+```typescript
+import { Component, inject, effect } from '@angular/core';
+import { ActivityProducerService } from '@ama-mfe/ng-utils';
+
+@Component({
+  selector: 'app-root',
+  template: '...'
+})
+export class AppComponent {
+  private readonly activityProducer = inject(ActivityProducerService);
+
+  constructor() {
+    this.activityProducer.start({ throttleMs: 1000 });
+
+    effect(() => {
+      const activity = this.activityProducer.localActivity();
+      if (activity) {
+        // React to local activity (not throttled for local detection)
+      }
+    });
+  }
+}
+```

packages/@ama-mfe/ng-utils/src/messages/index.ts

@@ -1,3 +1,4 @@
 export * from './available-sender';
 export * from './error-sender';
 export * from './error/index';
+export * from './user-activity';

packages/@ama-mfe/ng-utils/src/messages/user-activity.spec.ts

@@ -0,0 +1,87 @@
+import {
+  USER_ACTIVITY_MESSAGE_TYPE,
+  type UserActivityMessageV1_0,
+} from '@ama-mfe/messages';
+import {
+  isUserActivityMessage,
+} from './user-activity';
+
+describe('isUserActivityMessage', () => {
+  it('should return true for valid UserActivityMessageV1_0', () => {
+    const message: UserActivityMessageV1_0 = {
+      type: USER_ACTIVITY_MESSAGE_TYPE,
+      version: '1.0',
+      eventType: 'click',
+      timestamp: Date.now()
+    };
+
+    expect(isUserActivityMessage(message)).toBe(true);
+  });
+
+  it('should return true for all valid event types', () => {
+    const eventTypes = ['click', 'keydown', 'scroll', 'touchstart', 'focus', 'visibilitychange', 'iframeinteraction'] as const;
+
+    eventTypes.forEach((eventType) => {
+      const message: UserActivityMessageV1_0 = {
+        type: USER_ACTIVITY_MESSAGE_TYPE,
+        version: '1.0',
+        eventType,
+        timestamp: Date.now()
+      };
+
+      expect(isUserActivityMessage(message)).toBe(true);
+    });
+  });
+
+  it('should return false for null', () => {
+    expect(isUserActivityMessage(null)).toBe(false);
+  });
+
+  it('should return false for undefined', () => {
+    expect(isUserActivityMessage(undefined)).toBe(false);
+  });
+
+  it('should return false for non-object values', () => {
+    expect(isUserActivityMessage('string')).toBe(false);
+    expect(isUserActivityMessage(123)).toBe(false);
+    expect(isUserActivityMessage(true)).toBe(false);
+  });
+
+  it('should return false for object without type property', () => {
+    const message = {
+      version: '1.0',
+      eventType: 'click',
+      timestamp: Date.now()
+    };
+
+    expect(isUserActivityMessage(message)).toBe(false);
+  });
+
+  it('should return false for object with wrong type', () => {
+    const message = {
+      type: 'wrong_type',
+      version: '1.0',
+      eventType: 'click',
+      timestamp: Date.now()
+    };
+
+    expect(isUserActivityMessage(message)).toBe(false);
+  });
+
+  it('should return false for empty object', () => {
+    expect(isUserActivityMessage({})).toBe(false);
+  });
+
+  it('should return false for array', () => {
+    expect(isUserActivityMessage([])).toBe(false);
+  });
+
+  it('should return true even if other properties are missing (only checks type)', () => {
+    // The type guard only checks for the type property
+    const message = {
+      type: USER_ACTIVITY_MESSAGE_TYPE
+    };
+
+    expect(isUserActivityMessage(message)).toBe(true);
+  });
+});

packages/@ama-mfe/ng-utils/src/messages/user-activity.ts

@@ -0,0 +1,20 @@
+import {
+  USER_ACTIVITY_MESSAGE_TYPE,
+  type UserActivityMessage,
+} from '@ama-mfe/messages';
+import type {
+  VersionedMessage,
+} from '@amadeus-it-group/microfrontends';
+
+/**
+ * Type guard to check if a message is a user activity message
+ * @param message The message to check
+ */
+export function isUserActivityMessage(message: unknown): message is UserActivityMessage {
+  return (
+    typeof message === 'object'
+    && message !== null
+    && 'type' in message
+    && (message as VersionedMessage).type === USER_ACTIVITY_MESSAGE_TYPE
+  );
+}

packages/@ama-mfe/ng-utils/src/public_api.ts

@@ -6,4 +6,5 @@ export * from './messages/index';
 export * from './navigation/index';
 export * from './resize/index';
 export * from './theme/index';
+export * from './user-activity/index';
 export * from './utils';