AlpuraMatomoTrackClick

🖱️ AlpuraMatomoTrackClick Directive – Guía de uso

Este documento explica cómo utilizar la directiva alpuraMatomoTrackClick, diseñada para rastrear interacciones de clic de los usuarios y enviar los eventos a Matomo para su análisis.

---

📁 Importaciones necesarias

Para usar la directiva, impórtala y añádela al arreglo imports de tu componente standalone.

import { AlpuraMatomoTrackClickDirective } from "@alpura/core";

@Component({
  //...
  standalone: true,
  imports: [
    AlpuraMatomoTrackClickDirective,
    // ... otros módulos y componentes
  ],
})
export class TuComponente {
  // ...
}

---

✍️ Modos de Uso

La directiva se puede utilizar de dos maneras: declarativamente en el HTML (el caso más común) o programáticamente desde TypeScript para escenarios más complejos.

1. Uso Declarativo en HTML (Recomendado)

Esta es la forma más sencilla y directa. Simplemente añade el selector alpuraMatomoTrackClick a cualquier elemento que deba ser rastreado, como un botón. La directiva se encargará automáticamente de capturar el evento de clic.

Ejemplo tomado de form-remoto.component.html:

<button
  mat-flat-button
  color="primary"
  [disabled]="formGroup.invalid"
  alpuraMatomoTrackClick
  [mfeName]="env.matomoNameMFE"
  event="Crear"
>
  mi botón
</button>

nota: la variable env.matomoNameMFE es un valor que se debe asignar en todos los environments del proyecto, el valor debe ser de tipo String, agregando como nombre el proyecto del MFE (microfrontend). ejemplos: 'Base Remote', 'Polizas', 'CRM Ranchos', etc.

2. Uso Programático en TypeScript (Ej. con SweetAlert)

Para elementos generados dinámicamente como un SweetAlert, puedes instanciar y controlar la directiva manualmente.

Ejemplo basado en remoto.component.ts:

import { AlpuraMatomoTrackClickDirective } from "@alpura/core";
import { environment } from "../../../../environments/environment";
import * as Swal from "sweetalert2";

// ...

export class RemotoComponent {
  public sweetAlert = Swal;
  private matomoTrackClickDeleteDirective?: AlpuraMatomoTrackClickDirective;

  constructor() {
    // 1. Se crea una instancia de la directiva.
    this.matomoTrackClickDeleteDirective =
      new AlpuraMatomoTrackClickDirective();

    // 2. Se configuran sus propiedades.
    this.matomoTrackClickDeleteDirective.mfeName = environment.matomoNameMFE;
    this.matomoTrackClickDeleteDirective.event = "Eliminar";
  }

  public onDelete(remoto: IRemoto) {
    this.sweetAlert.default
      .fire({
        title: `¿Eliminar ${remoto.idNombre}?`,
        // ... otras opciones del alert
      })
      .then((result) => {
        if (result.value) {
          // 3. Se llama manualmente al método onClick() para registrar el evento.
          this.matomoTrackClickDeleteDirective?.onClick();
          // Se procede con la lógica de eliminación.
          this.vmRemotoDelete.deleteRemote(remoto.id);
        }
      });
  }
}

---

⚙️ Inputs

Nombre	Tipo	Descripción
mfeName	string	(Requerido) El nombre del Micro-Frontend que origina el evento.
event	string	(Requerido) El nombre específico del evento (ej. 'Crear', 'Eliminar').

---

📞 Métodos Públicos

Nombre	Retorna	Descripción
onClick()	void	Dispara manualmente el evento de tracking a Matomo. Útil solo para el uso programático desde TypeScript.

---

🚀 Resultado esperado

Cuando la directiva se utiliza correctamente:

1. Al hacer clic en el elemento (ej. un botón), se enviará un evento de seguimiento a Matomo.
2. En el panel de Matomo, podrás ver el evento registrado con la categoría mfeName y la acción event que hayas configurado.
3. Esto permite un análisis detallado del comportamiento del usuario sin necesidad de añadir lógica de seguimiento en el componente.

---

📬 Soporte

Para dudas o mantenimiento del componente alpuraMatomoTrackClick, contactar al equipo de arquitectura.