@ama-mfe/ng-utils 14.0.0-next.0 → 14.0.0-next.10

package/README.md

@@ -59,7 +59,7 @@ import {inject, runInInjectionContext} from '@angular/core';
 import {bootstrapApplication} from '@angular/platform-browser';
 import {ConnectionService, NavigationConsumerService} from '@ama-mfe/ng-utils';
 
-bootstrapApplication(AppComponent, appConfig)
+bootstrapApplication(App, appConfig)
   .then((m) => {
     runInInjectionContext(m.injector, () => {
       if (window.top !== window.self) {
@@ -94,12 +94,12 @@ If you are a consumer of the message, call the `start` and `stop` methods to res
 ```typescript
 import {Component, inject} from '@angular/core';
 import {NavigationConsumerService} from '@ama-mfe/ng-utils';
-import {ThemeConsumerService} from "./theme.consumer.service";
+import {ThemeConsumerService} from "./theme-consumer-service";
 
 @Component({
-  selector: 'app-example-module',
-  template: './example-module.template.html',
-  styleUrl: './example-module.style.scss',
+  selector: 'app-example-module-component',
+  template: './example-module-component.html',
+  styleUrl: './example-module-component.scss',
 })
 export class ExampleModuleComponent {
   private readonly navigationConsumerService = inject(NavigationConsumerService);
@@ -123,7 +123,7 @@ import {inject, runInInjectionContext} from '@angular/core';
 import {bootstrapApplication} from '@angular/platform-browser';
 import {ConnectionService, ThemeConsumerService} from '@ama-mfe/ng-utils';
 
-bootstrapApplication(AppComponent, appConfig)
+bootstrapApplication(App, appConfig)
   .then((m) => {
     runInInjectionContext(m.injector, () => {
       if (window.top !== window.self) {
@@ -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)
+      }
+    });
+  }
+}
+```