TrackingService

Paquete: @tiendana/ngx-core/tracking

Servicio raíz (providedIn: 'root') que reparte los eventos a todos los proveedores de analítica configurados, y dispara un PageView en cada cambio de ruta.

Características

✅ Multi-proveedor - Cada llamada se envía a todos los proveedores activos
✅ Tolerante a fallos - Un proveedor que lanza un error no afecta a los demás
✅ Inicialización idempotente - initialize() solo se ejecuta una vez
✅ Contexto diferido - setContext() antes de inicializar se guarda y se aplica al terminar
✅ PageView por ruta - Lee data.tracking de la ruta activa más profunda

Configuración

Registra la configuración con provideTracking en app.config.ts:

app.config.ts

import { provideTracking, AmplitudeProvider } from '@tiendana/ngx-core/tracking';

provideTracking({
  enabled: environment.production || environment.enableTrackingInDev,
  debug: environment.debug,
  providers: environment.amplitude_api_key
    ? [new AmplitudeProvider(environment.amplitude_api_key)]
    : [],
})

TrackingConfig

Propiedad	Tipo	Requerido	Descripción
enabled	boolean	Sí	Activa o desactiva la analítica. Sin configuración, el servicio se comporta como desactivado
debug	boolean	No	Muestra en consola un aviso cuando la analítica está desactivada
providers	TrackingProvider[]	No	Instancias de proveedores ya construidas

TRACKING_CONFIG es el InjectionToken<TrackingConfig> asociado. Prefiere provideTracking, que devuelve EnvironmentProviders.

Inicialización

Llama a initialize() una vez al arrancar la aplicación:

export class AppComponent implements OnInit {
  private readonly tracking = inject(TrackingService);

  ngOnInit() {
    this.tracking.initialize();
  }
}

Con enabled: false el servicio se marca como inicializado, pero no registra proveedores ni escucha rutas, así que el resto de métodos no envían nada. Con enabled: true inicializa todos los proveedores en paralelo; si alguno falla, se registra el error en consola con el nombre del proveedor y el resto continúa.

API

Métodos

Método	Retorno	Descripción
initialize()	Promise<void>	Inicializa los proveedores y empieza a escuchar las rutas. Seguro de llamar varias veces
track(event, properties?)	void	Envía un evento a todos los proveedores. properties debería incluir module y feature
identify(userId, traits?)	void	Identifica al usuario. Llamar tras el inicio de sesión
setContext(userId, companyId, traits?)	void	Fija usuario y empresa como contexto global de los eventos siguientes
reset()	void	Limpia la identidad del usuario. Llamar al cerrar sesión

track, identify y reset no hacen nada antes de que initialize() termine.

this.tracking.setContext(user.sub, user.company_id, { role: user.role, plan: user.plan });
this.tracking.track('ClickedButton', { module: 'Orders', feature: 'Details', order_id: 12345 });
this.tracking.reset();

tip

setContext puede llamarse antes de initialize() (por ejemplo desde un APP_INITIALIZER): el último valor se guarda y se aplica en cuanto los proveedores arrancan. Si la analítica está desactivada, se descarta.

PageView Automático

Tras inicializar, cada NavigationEnd llama a page(path, module, feature) en los proveedores. module y feature se leen de data.tracking de la ruta hija más profunda:

export const routes: Routes = [
  { path: 'orders', component: OrdersPage, data: { tracking: { module: 'Orders' } } },
  { path: 'orders/:id', component: OrderForm, data: { tracking: { module: 'Orders', feature: 'Form' } } },
];

Tipo RouteTrackingData

export type RouteTrackingData = {
    /** Área de la entidad o funcionalidad. */
    module: string;
    /** Subtipo opcional de página. Usa 'Form' para crear o editar. */
    feature?: string;
};

Proveedores Propios

Implementa TrackingProvider para integrar otra herramienta (Mixpanel, Segment, PostHog...) y pásala en providers:

Interfaz TrackingProvider

export interface TrackingProvider {
    readonly name: string;
    initialize(): Promise<void>;
    track(event: string, properties?: Record<string, any>): void;
    page(path: string, module?: string, feature?: string): void;
    identify(userId: string, traits?: Record<string, any>): void;
    setContext(userId: string, companyId: number | string, traits?: Record<string, any>): void;
    reset(): void;
}

class ConsoleProvider implements TrackingProvider {
  readonly name = 'console';
  async initialize() {}
  track(event: string, properties?: Record<string, any>) { console.log(event, properties); }
  page(path: string, module?: string, feature?: string) { console.log('page', path, module, feature); }
  identify(userId: string) { console.log('identify', userId); }
  setContext(userId: string, companyId: number | string) { console.log('context', userId, companyId); }
  reset() { console.log('reset'); }
}

Ver También

• tdnTrack: registro declarativo de clics
• AmplitudeProvider: proveedor incluido