feat: integrate penguin analytics tracking

- Add analytics.service.ts wrapper around analytics.io library
- Add penguin-analytics-plugin.ts for backend communication
- Track page views, link clicks, button clicks, user activity
- Add getUserGuid() and getPreferredUsername() to KeycloakService
- Fix Keycloak reload loop (checkLoginIframe: false, URL hash cleanup)
- Add analytics npm package dependency
- Add proxy.conf.json for local dev (proxies to localhost:3000)
- Add proxyConfig to angular.json for local development

Author: danieltruong

.yarn/install-state.gz

@@ -90,7 +90,8 @@
           "builder": "@angular/build:dev-server",
           "options": {
             "port": 4200,
-            "buildTarget": "base-app2:build:development"
+            "buildTarget": "base-app2:build:development",
+            "proxyConfig": "proxy.conf.json"
           },
           "configurations": {
             "production": {

angular.json

@@ -29,6 +29,7 @@
     "@ng-select/ng-select": "^21.1.0",
     "@popperjs/core": "^2.11.8",
     "@tinymce/tinymce-angular": "^9.0.0",
+    "analytics": "^0.8.14",
     "bootstrap": "^5.3.7",
     "jszip": "^3.10.1",
     "keycloak-angular": "^21.0.0",

package.json

@@ -0,0 +1,11 @@
+{
+  "/api/analytics": {
+    "target": "http://localhost:3000",
+    "secure": false,
+    "changeOrigin": true,
+    "pathRewrite": {
+      "^/api/analytics": "/events"
+    },
+    "logLevel": "debug"
+  }
+}

proxy.conf.json

@@ -1,11 +1,14 @@
 import { Component, OnInit, HostBinding, inject } from '@angular/core';
 
-import { RouterModule } from '@angular/router';
+import { Router, NavigationEnd, RouterModule } from '@angular/router';
+import { filter } from 'rxjs/operators';
 import { HeaderComponent } from './header/header.component';
 import { SidebarComponent } from './sidebar/sidebar.component';
 import { ToggleButtonComponent } from './toggle-button/toggle-button.component';
 import { FooterComponent } from './footer/footer.component';
 import { SideBarService } from './services/sidebar.service';
+import { AnalyticsService } from './services/analytics/analytics.service';
+import { KeycloakService } from './services/keycloak.service';
 
 @Component({
     selector: 'app-root',
@@ -23,7 +26,9 @@ import { SideBarService } from './services/sidebar.service';
 
 export class AppComponent implements OnInit {
   private sideBarService = inject(SideBarService);
-
+  private analyticsService = inject(AnalyticsService);
+  private keycloakService = inject(KeycloakService);
+  private router = inject(Router);
 
   @HostBinding('class.sidebarcontrol')
   isOpen = false;
@@ -32,5 +37,44 @@ export class AppComponent implements OnInit {
     this.sideBarService.toggleChange.subscribe(isOpen => {
       this.isOpen = isOpen;
     });
+
+    // Identify user for analytics if authenticated
+    // This MUST be called before any page tracking to ensure userId is set
+    if (this.keycloakService.isAuthenticated()) {
+      const userGuid = this.keycloakService.getUserGuid();
+      if (userGuid) {
+        const sessionStart = new Date().toISOString();
+        this.analyticsService.identify(userGuid, {
+          username: this.keycloakService.getPreferredUsername(),
+          roles: this.keycloakService.getUserRoles(),
+          session_start: sessionStart,
+          auth_provider: this.keycloakService.getIdpFromToken() || 'unknown'
+        });
+      }
+    }
+
+    // Track page views on navigation
+    // These will only be sent AFTER identify() is called
+    this.router.events
+      .pipe(filter(event => event instanceof NavigationEnd))
+      .subscribe((event: NavigationEnd) => {
+        const routePath = event.urlAfterRedirects || event.url;
+        const pageName = this.getPageName(routePath);
+        this.analyticsService.page(pageName, { path: routePath });
+      });
+  }
+
+  /** Extract page name from URL path */
+  private getPageName(path: string): string {
+    const cleanPath = path.split('?')[0].split('#')[0].split(';')[0];
+    const routePath = cleanPath.replace(/^\/admin\/?/, '');
+    
+    if (!routePath || routePath === '/') return 'Home';
+    
+    return routePath
+      .split('/')
+      .filter(s => s && !s.match(/^[0-9a-f-]{20,}$/i)) // Remove IDs
+      .map(s => s.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase()))
+      .join(' > ') || 'Home';
   }
 }

src/app/app.component.ts

@@ -1,9 +1,8 @@
 @for (item of items; track item) {
-<tr (click)="itemClicked(item)">
-  <td scope="row" data-label="Name" [style.width]="!useSmallTable && columns[0].width">{{item.type || '-'}}</td>
-  <td scope="row" data-label="Name" [style.width]="!useSmallTable && columns[1].width">{{item.appliedTo || '-'}}</td>
-  <td scope="row" data-label="Name" [style.width]="!useSmallTable && columns[2].width">{{item.start | date: 'longDate'}}</td>
-  <td scope="row" data-label="Name" [style.width]="!useSmallTable && columns[3].width">{{item.end | date: 'longDate'}}</td>
-  <td scope="row" data-label="Name" [style.width]="!useSmallTable && columns[4].width"><a href="javascript:void(0);" (click)="goToItem(item)">View</a></td>
-</tr>
+  <tr (click)="itemClicked(item)">
+    <td scope="row" data-label="Name" [style.width]="!useSmallTable && columns[0].width">{{item.type || '-'}}</td>
+    <td scope="row" data-label="Name" [style.width]="!useSmallTable && columns[1].width">{{item.appliedTo || '-'}}</td>
+    <td scope="row" data-label="Name" [style.width]="!useSmallTable && columns[2].width">{{item.start | date: 'longDate'}}</td>
+    <td scope="row" data-label="Name" [style.width]="!useSmallTable && columns[3].width">{{item.end | date: 'longDate'}}</td>
+  </tr>
 }

src/app/projects/add-edit-project/modifications-list-table-rows/modifications-list-table-rows.component.html

@@ -0,0 +1,96 @@
+import { Injectable } from '@angular/core';
+import Analytics from 'analytics';
+import type { AnalyticsInstance } from 'analytics';
+import { penguinAnalyticsPlugin } from './penguin-analytics-plugin';
+
+interface EnvConfig {
+  ANALYTICS_API_URL?: string;
+  ANALYTICS_DEBUG?: boolean;
+  API_LOCATION?: string;
+  API_PATH?: string;
+}
+
+declare const window: Window & { __env?: EnvConfig };
+
+const buildDefaultAnalyticsUrl = (env?: EnvConfig): string => {
+  const base = env?.API_LOCATION?.replace(/\/$/, '') || '';
+  const apiPath = env?.API_PATH || '/api';
+  const normalizedPath = apiPath.startsWith('/') ? apiPath : `/${apiPath}`;
+  return base ? `${base}${normalizedPath}/telemetry` : `${normalizedPath}/telemetry`;
+};
+
+/**
+ * Analytics service using Analytics.io with Penguin Analytics plugin.
+ * 
+ * ## Auto-tracked events (no code needed):
+ * - Page views (on route changes)
+ * - Link clicks
+ * - Button clicks  
+ * - User activity pings
+ * 
+ * ## Manual tracking:
+ * Use "Object + Past Verb" naming: "Form Submitted", "Document Downloaded"
+ * 
+ * @example
+ * ```typescript
+ * // Page view (auto-tracked, but can override)
+ * analytics.page('Project Details', { project_id: '123' });
+ * 
+ * // Custom event
+ * analytics.track('Report Generated', { format: 'pdf' });
+ * 
+ * // Identify user after login
+ * analytics.identify(userId, { username: 'john', roles: ['admin'] });
+ * ```
+ */
+@Injectable({
+  providedIn: 'root'
+})
+export class AnalyticsService {
+  private analytics: AnalyticsInstance;
+  private initialized = false;
+
+  constructor() {
+    const env = window.__env;
+    const apiUrl = env?.ANALYTICS_API_URL || buildDefaultAnalyticsUrl(env);
+    const debug = env?.ANALYTICS_DEBUG ?? false;
+
+    this.analytics = Analytics({
+      app: 'eagle-admin',
+      debug: debug,
+      plugins: [
+        penguinAnalyticsPlugin({
+          apiUrl: apiUrl,
+          sourceApp: 'eagle-admin',
+          debug: debug
+        })
+      ]
+    });
+
+    this.initialized = true;
+  }
+
+  /** Track a page view */
+  page(name?: string, properties?: Record<string, any>): void {
+    if (!this.initialized) return;
+    this.analytics.page({ name, ...properties });
+  }
+
+  /** Track a custom event. Use "Object + Past Verb" naming. */
+  track(event: string, properties?: Record<string, any>): void {
+    if (!this.initialized) return;
+    this.analytics.track(event, properties);
+  }
+
+  /** Identify user after authentication */
+  identify(userId: string, traits?: Record<string, any>): void {
+    if (!this.initialized) return;
+    this.analytics.identify(userId, traits);
+  }
+
+  /** Reset on logout */
+  reset(): void {
+    if (!this.initialized) return;
+    this.analytics.reset();
+  }
+}