valtech-components 2.0.691 → 2.0.692

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

@@ -1,707 +0,0 @@
-/**
- * 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);
-    });
-  }
-}