feat: track run/abort annotation event to Matomo

CHANGELOG.md

@@ -13,6 +13,10 @@ As this project is a user-facing application, the places in the semantic version
 
 ## [Unreleased]
 
+### Added
+
+- Track some events to Matomo (run/abort annotation) [#166](https://github.com/spraakbanken/mink-frontend/issues/166)
+
 ### Fixed
 
 - Show loading spinners on the custom config page

index.d.ts

@@ -1 +1,33 @@
-declare module "vue-matomo";
+declare module "vue-matomo" {
+  // See https://github.com/AmazingDreams/vue-matomo/blob/master/src/utils.js
+
+  /**
+   * The default export is the Vue plugin.
+   * Usage:
+   *   import matomo from "vue-matomo";
+   *   app.use(matomo, {...})
+   */
+  export default import("vue").Plugin;
+
+  /**
+   * Inject `matomoKey` to use the Matomo object.
+   * Usage:
+   *   const matomo = inject<Matomo>(matomoKey);
+   *   matomo?.trackEvent("Vote", "Up")
+   */
+  export const matomoKey: string;
+
+  /**
+   * This thing is returned when injecting `matomoKey`.
+   * Extend as needed.
+   * Fully described on https://developer.matomo.org/api-reference/tracking-javascript
+   */
+  export type Matomo = {
+    trackEvent: (
+      category: string,
+      action: string,
+      name?: string,
+      value?: number,
+    ) => void;
+  };
+}

src/corpus/analysis/AnalysisPanel.vue

@@ -6,13 +6,15 @@ import useExports from "../exports/exports.composable";
 import useJob from "../job/job.composable";
 import ActionButton from "@/components/ActionButton.vue";
 import PendingContent from "@/spin/PendingContent.vue";
+import { useMatomo } from "@/matomo";
 
 const corpusId = useCorpusIdParam();
 const { runJob, jobState, isJobRunning } = useJob(corpusId);
 const { canBeReady } = useCorpusState(corpusId);
 const { exports, loadExports, downloadResult, getDownloadFilename } =
   useExports(corpusId);
 const { isDone } = useCorpusState(corpusId);
+const matomo = useMatomo();
 
 const isPending = ref(false);
 const canRun = computed(
@@ -23,6 +25,7 @@ loadExports();
 
 async function doRunJob() {
   isPending.value = true;
+  matomo?.trackEvent("Corpus", "Run annotation", corpusId);
   await runJob();
   isPending.value = false;
 }

src/corpus/job/JobStatus.vue

@@ -1,26 +1,32 @@
 <script setup lang="ts">
 import { computed } from "vue";
+import { useMatomo } from "@/matomo";
 import useJob from "@/corpus/job/job.composable";
 import JobStatusMessage from "@/corpus/job/JobStatusMessage.vue";
 import { formatDate } from "@/util";
 import PendingContent from "@/spin/PendingContent.vue";
 import useCorpusIdParam from "@/corpus/corpusIdParam.composable";
 import { useCorpusState } from "@/corpus/corpusState.composable";
 import ActionButton from "@/components/ActionButton.vue";
-import TerminalOutput from "@/components/TerminalOutput.vue";
 import ProgressBar from "@/components/ProgressBar.vue";
 import TextData from "@/components/TextData.vue";
 
 const corpusId = useCorpusIdParam();
 const { abortJob, jobStatus, isJobRunning } = useJob(corpusId);
 const { isFailed } = useCorpusState(corpusId);
+const matomo = useMatomo();
 
 const hasStarted = computed(
   () =>
     Object.values(jobStatus.value?.status || {}).some(
       (status) => status != "none",
     ) || jobStatus.value?.priority,
 );
+
+async function doAbortJob() {
+  matomo?.trackEvent("Corpus", "Abort annotation", corpusId);
+  await abortJob();
+}
 </script>
 
 <template>
@@ -39,7 +45,7 @@ const hasStarted = computed(
       <ActionButton
         v-if="isJobRunning"
         class="button-danger ml-2"
-        @click="abortJob"
+        @click="doAbortJob"
       >
         {{ $t("job.abort") }}
       </ActionButton>

src/matomo.ts

@@ -0,0 +1,19 @@
+import { inject } from "vue";
+import { matomoKey, type Matomo } from "vue-matomo";
+
+/** Use this to call Matomo methods in the context of a setup function. */
+export function useMatomo(): Matomo | undefined {
+  // Specifying the default value avoids console warnings, even if it's just `undefined`.
+  return inject<Matomo | undefined>(matomoKey, undefined);
+}
+
+/**
+ * Exposes supported Matomo commands as methods, which then use `window._paq`.
+ * If the queue is not loaded, nothing happens.
+ */
+export const MatomoProxy = new Proxy<Matomo>({} as Matomo, {
+  get:
+    <F extends keyof Matomo>(target: {}, prop: F) =>
+    (...args: Parameters<Matomo[F]>) =>
+      (window as any)._paq?.push([prop, ...args]),
+});