Saltar al contenido principal

Tracking

Paquete: @tiendana/ngx-core/tracking

El punto de entrada @tiendana/ngx-core/tracking ofrece analítica de producto declarativa: una directiva para registrar clics, un servicio que reparte los eventos a uno o varios proveedores y un proveedor de Amplitude listo para usar.

Características​

✅ Declarativo - La directiva tdnTrack registra clics sin escribir código en el componente
✅ Multi-proveedor - TrackingService reparte cada evento a todos los proveedores configurados
✅ PageView automático - Tras initialize(), cada NavigationEnd del router genera un evento con module y feature leídos de data.tracking
✅ Extensible - Cualquier clase que implemente TrackingProvider se registra como proveedor
✅ Amplitude incluido - AmplitudeProvider con dependencia opcional
✅ Apagable - Con enabled: false no se inicializa ningún proveedor y no se envía nada

Instalación​

El paquete base ya trae el punto de entrada. El SDK de Amplitude es una peer dependency opcional del paquete, pero el bundle de @tiendana/ngx-core/tracking lo importa de forma estática: instálalo en cualquier aplicación que importe desde este punto de entrada, aunque no use AmplitudeProvider:

npm install @amplitude/analytics-browser

El servicio inyecta Router, por lo que la aplicación necesita @angular/router.

Piezas del Punto de Entrada​

SímboloTipoDescripción
TdnTrackDirectiveDirectiva ([tdnTrack])Registra un evento al hacer clic en el elemento anfitrión
TrackingServiceServicio (providedIn: 'root')Inicializa proveedores, envía eventos y escucha las rutas
provideTracking(config)FunciónRegistra el TrackingConfig en los providers de la aplicación
TRACKING_CONFIGInjectionToken<TrackingConfig>Token de la configuración. Usa provideTracking en vez de proveerlo directamente
TrackingProviderInterfazContrato que debe cumplir todo proveedor de analítica
TdnTrackPropsTipoMetadatos del evento: module y feature obligatorios, más propiedades libres
RouteTrackingDataTipoForma de data.tracking en las rutas
AmplitudeProviderClaseImplementación de TrackingProvider sobre @amplitude/analytics-browser

Configuración Mínima​

app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideTracking, AmplitudeProvider } from '@tiendana/ngx-core/tracking';
import { environment } from '../environments/environment';
import { routes } from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideTracking({
      enabled: environment.production,
      providers: environment.amplitude_api_key
        ? [new AmplitudeProvider(environment.amplitude_api_key)]
        : [],
    }),
  ],
};
app.component.ts
import { Component, OnInit, inject } from '@angular/core';
import { RouterOutlet } from '@angular/router';
import { TrackingService } from '@tiendana/ngx-core/tracking';

@Component({ selector: 'app-root', imports: [RouterOutlet], template: '<router-outlet />' })
export class AppComponent implements OnInit {
  private readonly tracking = inject(TrackingService);

  ngOnInit() {
    this.tracking.initialize();
  }
}
<button type="button" [tdnTrack]="{ module: 'Catalog', feature: 'Products.Export', format: 'excel' }">
  Exportar
</button>
info

Hasta que se llama a initialize(), los métodos track, identify y reset no hacen nada. El contexto fijado con setContext antes de inicializar sí se conserva y se aplica al terminar.

Eventos de PageView por Ruta​

Define data.tracking en las rutas. El servicio lee la ruta hija más profunda activa en cada navegación:

export const routes: Routes = [
  { path: 'products', component: ProductsPage, data: { tracking: { module: 'Catalog' } } },
  { path: 'products/:id', component: ProductForm, data: { tracking: { module: 'Catalog', feature: 'Form' } } },
];
nota

Las navegaciones que terminan antes de que los proveedores acaben su inicialización no se registran, por ejemplo la navegación inicial mientras Amplitude sigue arrancando.

Siguientes Pasos​