valtech-components 2.0.687 → 2.0.689

package/src/lib/services/firebase/analytics.service.ts

@@ -0,0 +1,707 @@
+/**
+ * Analytics Service (Firebase GA4)
+ *
+ * Servicio para tracking de eventos, page views y errores con Firebase Analytics.
+ * Integra con el sistema de auth para user properties y respeta consent mode GDPR.
+ */
+
+import { Inject, Injectable, Injector, PLATFORM_ID, signal, computed } from '@angular/core';
+import { isPlatformBrowser } from '@angular/common';
+import { Analytics, logEvent, setUserId, setUserProperties } from '@angular/fire/analytics';
+
+import { VALTECH_FIREBASE_CONFIG } from './config';
+import { ValtechFirebaseConfig } from './types';
+import {
+  AnalyticsConfig,
+  AnalyticsDebugEvent,
+  AnalyticsEventName,
+  AnalyticsEventParams,
+  AnalyticsItem,
+  ConsentSettings,
+  ConsentState,
+  DebugEventType,
+  TimingMetric,
+  UserProperties,
+} from './analytics-types';
+
+/** Key por defecto para persistir consent en localStorage */
+const DEFAULT_CONSENT_STORAGE_KEY = 'analytics_consent';
+
+/** Máximo de eventos en historial de debug */
+const MAX_DEBUG_HISTORY = 100;
+
+/**
+ * Servicio de Firebase Analytics (GA4).
+ *
+ * Proporciona tracking de eventos, page views, errores y métricas de performance.
+ * Soporta GDPR Consent Mode y modo debug para desarrollo.
+ *
+ * @example
+ * ```typescript
+ * @Component({...})
+ * export class ProductComponent {
+ *   private analytics = inject(AnalyticsService);
+ *
+ *   onPurchase(product: Product) {
+ *     this.analytics.logEvent('purchase', {
+ *       transaction_id: order.id,
+ *       value: order.total,
+ *       currency: 'EUR'
+ *     });
+ *   }
+ * }
+ * ```
+ */
+@Injectable({ providedIn: 'root' })
+export class AnalyticsService {
+  // ===========================================================================
+  // ESTADO (Signals)
+  // ===========================================================================
+
+  private readonly _consentState = signal<ConsentState>({
+    settings: {},
+    updatedAt: null,
+    hasDecided: false,
+  });
+
+  private readonly _isDebugMode = signal<boolean>(false);
+  private readonly _debugHistory = signal<AnalyticsDebugEvent[]>([]);
+
+  /** Estado de consentimiento actual (readonly) */
+  readonly consentState = this._consentState.asReadonly();
+
+  /** Indica si está en modo debug */
+  readonly isDebugMode = this._isDebugMode.asReadonly();
+
+  /** Indica si analytics está habilitado y funcionando */
+  readonly isEnabled = computed(() => {
+    return this.isAnalyticsSupported() && this._consentState().settings.analytics === true;
+  });
+
+  // ===========================================================================
+  // CONFIGURACIÓN
+  // ===========================================================================
+
+  private readonly analyticsConfig: AnalyticsConfig;
+  private readonly consentStorageKey: string;
+  private readonly eventPrefix: string;
+  private readonly samplingRate: number;
+
+  constructor(
+    private injector: Injector,
+    @Inject(VALTECH_FIREBASE_CONFIG) private config: ValtechFirebaseConfig,
+    @Inject(PLATFORM_ID) private platformId: Object
+  ) {
+    this.analyticsConfig = config.analyticsConfig ?? {};
+    this.consentStorageKey =
+      this.analyticsConfig.consentStorageKey ?? DEFAULT_CONSENT_STORAGE_KEY;
+    this.eventPrefix = this.analyticsConfig.eventPrefix ?? '';
+    this.samplingRate = this.analyticsConfig.samplingRate ?? 1.0;
+
+    this.initializeAnalytics();
+  }
+
+  // ===========================================================================
+  // INICIALIZACIÓN
+  // ===========================================================================
+
+  /**
+   * Inicializa el servicio de analytics
+   */
+  private initializeAnalytics(): void {
+    if (!isPlatformBrowser(this.platformId)) {
+      return;
+    }
+
+    // Cargar consent desde localStorage
+    this.loadConsentFromStorage();
+
+    // Configurar debug mode
+    const debugMode = this.analyticsConfig.debugMode ?? false;
+    this._isDebugMode.set(debugMode);
+
+    // Aplicar consent inicial a gtag
+    this.applyConsentToGtag(this._consentState().settings);
+
+    // Setear user properties por defecto
+    if (this.analyticsConfig.defaultUserProperties) {
+      this.setUserProperties(this.analyticsConfig.defaultUserProperties);
+    }
+
+    if (debugMode) {
+      console.log('[Analytics] Inicializado en modo debug - eventos se loguean en consola Y se envían a Firebase');
+    }
+  }
+
+  /**
+   * Obtiene la instancia de Analytics de forma perezosa.
+   * Esto evita el error de APP_INITIALIZER de AngularFire.
+   */
+  private getAnalyticsInstance(): Analytics | null {
+    if (!this.config.enableAnalytics) {
+      return null;
+    }
+
+    try {
+      return this.injector.get(Analytics, null);
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Verifica si Analytics está soportado
+   */
+  private isAnalyticsSupported(): boolean {
+    if (!isPlatformBrowser(this.platformId)) {
+      return false;
+    }
+
+    if (!this.config.enableAnalytics) {
+      return false;
+    }
+
+    if (!this.config.firebase.measurementId) {
+      console.warn('[Analytics] measurementId no configurado en firebase config');
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Verifica si debe enviar el evento (sampling)
+   */
+  private shouldSample(): boolean {
+    if (this.samplingRate >= 1.0) {
+      return true;
+    }
+    return Math.random() < this.samplingRate;
+  }
+
+  // ===========================================================================
+  // PAGE VIEWS
+  // ===========================================================================
+
+  /**
+   * Registra un page view.
+   * Normalmente se usa automáticamente via AnalyticsRouterTracker.
+   *
+   * @param pagePath - Ruta de la página (ej: '/products/123')
+   * @param pageTitle - Título de la página (opcional)
+   */
+  logPageView(pagePath: string, pageTitle?: string): void {
+    this.logEvent('page_view', {
+      page_path: pagePath,
+      page_title: pageTitle ?? document?.title,
+      page_location: window?.location?.href,
+    });
+  }
+
+  /**
+   * Registra un screen view (para apps tipo SPA).
+   *
+   * @param screenName - Nombre del screen
+   * @param screenClass - Clase del screen (opcional)
+   */
+  logScreenView(screenName: string, screenClass?: string): void {
+    this.logEvent('screen_view', {
+      screen_name: screenName,
+      screen_class: screenClass,
+    });
+  }
+
+  // ===========================================================================
+  // EVENTOS
+  // ===========================================================================
+
+  /**
+   * Registra un evento tipado GA4.
+   *
+   * @param eventName - Nombre del evento (tipado)
+   * @param params - Parámetros del evento (tipados según el nombre)
+   *
+   * @example
+   * ```typescript
+   * // Evento tipado con autocompletado
+   * analytics.logEvent('add_to_cart', {
+   *   item_id: '123',
+   *   item_name: 'Producto',
+   *   value: 99.99,
+   *   currency: 'EUR'
+   * });
+   * ```
+   */
+  logEvent<T extends AnalyticsEventName>(
+    eventName: T,
+    params?: AnalyticsEventParams[T]
+  ): void {
+    this.trackEvent(eventName, params as Record<string, unknown>);
+  }
+
+  /**
+   * Registra un evento custom con parámetros libres.
+   * Usar cuando el evento no está en el catálogo tipado.
+   *
+   * @param eventName - Nombre del evento custom
+   * @param params - Parámetros libres
+   */
+  logCustomEvent(eventName: string, params?: Record<string, unknown>): void {
+    const prefixedName = this.eventPrefix + eventName;
+    this.trackEvent(prefixedName, params);
+  }
+
+  /**
+   * Lógica común para enviar eventos
+   */
+  private trackEvent(eventName: string, params?: Record<string, unknown>): void {
+    // Verificar consent
+    if (!this._consentState().settings.analytics) {
+      this.addToDebugHistory('event', eventName, params, false);
+      return;
+    }
+
+    // Aplicar sampling
+    if (!this.shouldSample()) {
+      return;
+    }
+
+    // Debug mode: loguear en consola (pero seguir enviando a Firebase)
+    if (this._isDebugMode()) {
+      console.log(`[Analytics] Event: ${eventName}`, params);
+    }
+
+    // Enviar a Firebase
+    const analytics = this.getAnalyticsInstance();
+    if (analytics) {
+      try {
+        logEvent(analytics, eventName as string, params);
+        this.addToDebugHistory('event', eventName, params, true);
+      } catch (error) {
+        console.error('[Analytics] Error enviando evento:', error);
+        this.addToDebugHistory('event', eventName, params, false);
+      }
+    } else {
+      this.addToDebugHistory('event', eventName, params, false);
+    }
+  }
+
+  // ===========================================================================
+  // ECOMMERCE
+  // ===========================================================================
+
+  /**
+   * Registra vista de item
+   */
+  logViewItem(item: AnalyticsItem): void {
+    this.logEvent('view_item', {
+      item_id: item.item_id,
+      item_name: item.item_name,
+      value: item.price,
+      currency: item.currency,
+    });
+  }
+
+  /**
+   * Registra agregar al carrito
+   */
+  logAddToCart(item: AnalyticsItem, quantity = 1): void {
+    this.logEvent('add_to_cart', {
+      item_id: item.item_id,
+      item_name: item.item_name,
+      value: (item.price ?? 0) * quantity,
+      currency: item.currency,
+      quantity,
+    });
+  }
+
+  /**
+   * Registra inicio de checkout
+   */
+  logBeginCheckout(items: AnalyticsItem[], value: number, currency = 'EUR'): void {
+    this.logEvent('begin_checkout', {
+      value,
+      currency,
+      items,
+    });
+  }
+
+  /**
+   * Registra compra completada
+   */
+  logPurchase(
+    transactionId: string,
+    items: AnalyticsItem[],
+    value: number,
+    currency = 'EUR'
+  ): void {
+    this.logEvent('purchase', {
+      transaction_id: transactionId,
+      value,
+      currency,
+      items,
+    });
+  }
+
+  // ===========================================================================
+  // USER PROPERTIES
+  // ===========================================================================
+
+  /**
+   * Setea el userId para asociar eventos con el usuario.
+   * Llamado automáticamente si enableAuthIntegration=true.
+   *
+   * @param userId - ID del usuario o null para limpiar
+   */
+  setUserId(userId: string | null): void {
+    if (!this.isAnalyticsSupported()) {
+      return;
+    }
+
+    // Debug mode: loguear en consola (pero seguir enviando a Firebase)
+    if (this._isDebugMode()) {
+      console.log(`[Analytics] Set userId: ${userId}`);
+    }
+
+    const analytics = this.getAnalyticsInstance();
+    if (analytics) {
+      try {
+        setUserId(analytics, userId);
+        this.addToDebugHistory('user_property', 'user_id', { userId }, true);
+      } catch (error) {
+        console.error('[Analytics] Error seteando userId:', error);
+        this.addToDebugHistory('user_property', 'user_id', { userId }, false);
+      }
+    } else {
+      this.addToDebugHistory('user_property', 'user_id', { userId }, false);
+    }
+  }
+
+  /**
+   * Setea propiedades del usuario para segmentación.
+   *
+   * @param properties - Propiedades key-value
+   *
+   * @example
+   * ```typescript
+   * analytics.setUserProperties({
+   *   subscription_tier: 'premium',
+   *   preferred_language: 'es'
+   * });
+   * ```
+   */
+  setUserProperties(properties: UserProperties | Record<string, string | number | boolean>): void {
+    if (!this.isAnalyticsSupported()) {
+      return;
+    }
+
+    // Debug mode: loguear en consola (pero seguir enviando a Firebase)
+    if (this._isDebugMode()) {
+      console.log('[Analytics] Set user properties:', properties);
+    }
+
+    const analytics = this.getAnalyticsInstance();
+    if (analytics) {
+      try {
+        // Convertir a Record<string, string> para Firebase
+        const stringProps: Record<string, string> = {};
+        for (const [key, value] of Object.entries(properties)) {
+          if (value !== undefined) {
+            stringProps[key] = String(value);
+          }
+        }
+        setUserProperties(analytics, stringProps);
+        this.addToDebugHistory('user_property', 'properties', properties, true);
+      } catch (error) {
+        console.error('[Analytics] Error seteando user properties:', error);
+        this.addToDebugHistory('user_property', 'properties', properties, false);
+      }
+    } else {
+      this.addToDebugHistory('user_property', 'properties', properties, false);
+    }
+  }
+
+  /**
+   * Setea la organización activa (multi-tenant).
+   * Llamado automáticamente si enableAuthIntegration=true.
+   *
+   * @param orgId - ID de la organización o null
+   */
+  setActiveOrganization(orgId: string | null): void {
+    if (orgId) {
+      this.setUserProperties({ active_organization: orgId });
+    }
+  }
+
+  // ===========================================================================
+  // ERROR TRACKING
+  // ===========================================================================
+
+  /**
+   * Registra un error para tracking.
+   * Integra automáticamente con Angular ErrorHandler si enableErrorTracking=true.
+   *
+   * @param error - Error o mensaje de error
+   * @param context - Contexto adicional
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   await riskyOperation();
+   * } catch (error) {
+   *   analytics.logError(error, { context: 'checkout_flow' });
+   * }
+   * ```
+   */
+  logError(error: Error | string, context?: Record<string, string>): void {
+    const errorMessage = error instanceof Error ? error.message : error;
+    const errorStack = error instanceof Error ? error.stack : undefined;
+    const errorType = error instanceof Error ? error.name : 'Error';
+
+    this.logEvent('error_occurred', {
+      error_type: errorType,
+      error_message: errorMessage.substring(0, 100), // Limitar longitud
+      error_stack: errorStack?.substring(0, 500),
+      context: context ? JSON.stringify(context) : undefined,
+    });
+  }
+
+  /**
+   * Registra un error fatal (crash-level).
+   */
+  logFatalError(error: Error, context?: Record<string, string>): void {
+    this.logError(error, { ...context, severity: 'fatal' });
+  }
+
+  // ===========================================================================
+  // CONSENT MODE (GDPR)
+  // ===========================================================================
+
+  /**
+   * Actualiza el estado de consentimiento del usuario.
+   * Afecta qué datos se recolectan y envían.
+   *
+   * @param consent - Settings de consentimiento
+   *
+   * @example
+   * ```typescript
+   * // Usuario acepta todo
+   * analytics.updateConsent({ analytics: true, advertising: true });
+   *
+   * // Usuario rechaza publicidad
+   * analytics.updateConsent({ analytics: true, advertising: false });
+   * ```
+   */
+  updateConsent(consent: ConsentSettings): void {
+    const newState: ConsentState = {
+      settings: { ...this._consentState().settings, ...consent },
+      updatedAt: new Date(),
+      hasDecided: true,
+    };
+
+    this._consentState.set(newState);
+    this.saveConsentToStorage(newState);
+    this.applyConsentToGtag(newState.settings);
+
+    this.addToDebugHistory('consent', 'update', consent as unknown as Record<string, unknown>, false);
+  }
+
+  /**
+   * Deniega todo consentimiento.
+   */
+  denyAllConsent(): void {
+    this.updateConsent({
+      analytics: false,
+      advertising: false,
+      functionality: false,
+      security: true, // Siempre permitido
+    });
+  }
+
+  /**
+   * Acepta todo consentimiento.
+   */
+  grantAllConsent(): void {
+    this.updateConsent({
+      analytics: true,
+      advertising: true,
+      functionality: true,
+      security: true,
+    });
+  }
+
+  /**
+   * Obtiene el estado actual de consentimiento.
+   */
+  getConsentState(): ConsentState {
+    return this._consentState();
+  }
+
+  /**
+   * Aplica consent settings a gtag (GA4 Consent Mode v2)
+   */
+  private applyConsentToGtag(settings: ConsentSettings): void {
+    if (!isPlatformBrowser(this.platformId)) {
+      return;
+    }
+
+    const gtag = (window as any).gtag;
+    if (typeof gtag !== 'function') {
+      return;
+    }
+
+    try {
+      gtag('consent', 'update', {
+        analytics_storage: settings.analytics ? 'granted' : 'denied',
+        ad_storage: settings.advertising ? 'granted' : 'denied',
+        ad_user_data: settings.advertising ? 'granted' : 'denied',
+        ad_personalization: settings.advertising ? 'granted' : 'denied',
+        functionality_storage: settings.functionality ? 'granted' : 'denied',
+        security_storage: settings.security !== false ? 'granted' : 'denied',
+      });
+    } catch (error) {
+      console.warn('[Analytics] Error aplicando consent a gtag:', error);
+    }
+  }
+
+  /**
+   * Carga consent desde localStorage
+   */
+  private loadConsentFromStorage(): void {
+    if (!isPlatformBrowser(this.platformId)) {
+      return;
+    }
+
+    try {
+      const stored = localStorage.getItem(this.consentStorageKey);
+      if (stored) {
+        const parsed = JSON.parse(stored) as ConsentState;
+        this._consentState.set({
+          ...parsed,
+          updatedAt: parsed.updatedAt ? new Date(parsed.updatedAt) : null,
+        });
+      } else if (this.analyticsConfig.defaultConsentGranted) {
+        // Auto-grant all consent para desarrollo/testing
+        this._consentState.set({
+          settings: {
+            analytics: true,
+            advertising: true,
+            functionality: true,
+            security: true,
+          },
+          updatedAt: new Date(),
+          hasDecided: true,
+        });
+      } else if (this.analyticsConfig.defaultConsent) {
+        // Aplicar consent por defecto si no hay guardado
+        this._consentState.set({
+          settings: this.analyticsConfig.defaultConsent,
+          updatedAt: null,
+          hasDecided: false,
+        });
+      }
+    } catch (error) {
+      console.warn('[Analytics] Error cargando consent:', error);
+    }
+  }
+
+  /**
+   * Guarda consent en localStorage
+   */
+  private saveConsentToStorage(state: ConsentState): void {
+    if (!isPlatformBrowser(this.platformId)) {
+      return;
+    }
+
+    try {
+      localStorage.setItem(this.consentStorageKey, JSON.stringify(state));
+    } catch (error) {
+      console.warn('[Analytics] Error guardando consent:', error);
+    }
+  }
+
+  // ===========================================================================
+  // TIMING / PERFORMANCE
+  // ===========================================================================
+
+  /**
+   * Registra una métrica de timing/performance.
+   *
+   * @param name - Nombre de la métrica
+   * @param valueMs - Valor en milisegundos
+   * @param params - Parámetros adicionales
+   *
+   * @example
+   * ```typescript
+   * const start = performance.now();
+   * await loadData();
+   * analytics.logTiming('data_load', performance.now() - start, {
+   *   category: 'api',
+   *   endpoint: '/products'
+   * });
+   * ```
+   */
+  logTiming(name: string, valueMs: number, params?: Record<string, string>): void {
+    this.logEvent('performance_metric', {
+      metric_name: name,
+      value: Math.round(valueMs),
+      unit: 'ms',
+      ...params,
+    });
+  }
+
+  // ===========================================================================
+  // DEBUG
+  // ===========================================================================
+
+  /**
+   * Habilita/deshabilita modo debug.
+   * En debug: logea eventos a consola además de enviarlos a Firebase.
+   */
+  setDebugMode(enabled: boolean): void {
+    this._isDebugMode.set(enabled);
+    console.log(`[Analytics] Debug mode: ${enabled ? 'ON' : 'OFF'}`);
+  }
+
+  /**
+   * Obtiene historial de eventos (solo en debug mode).
+   * Útil para testing y desarrollo.
+   */
+  getDebugHistory(): AnalyticsDebugEvent[] {
+    return this._debugHistory();
+  }
+
+  /**
+   * Limpia historial de debug.
+   */
+  clearDebugHistory(): void {
+    this._debugHistory.set([]);
+  }
+
+  /**
+   * Agrega evento al historial de debug
+   */
+  private addToDebugHistory(
+    type: DebugEventType,
+    name: string,
+    params?: Record<string, unknown>,
+    sent = false
+  ): void {
+    if (!this._isDebugMode()) {
+      return;
+    }
+
+    const event: AnalyticsDebugEvent = {
+      timestamp: new Date(),
+      type,
+      name,
+      params,
+      sent,
+    };
+
+    this._debugHistory.update((history) => {
+      const newHistory = [event, ...history];
+      return newHistory.slice(0, MAX_DEBUG_HISTORY);
+    });
+  }
+}