From 973fc8e076c77e58acd8ec3a634fa9991a1a1021 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sadjow=20Le=C3=A3o?= <sadjow@gmail.com>
Date: Wed, 11 Feb 2026 11:55:13 -0300
Subject: [PATCH 1/4] feat: add hooks mechanism for extensible tracking
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Luis David Barrera Díaz <dbarrera@stackbuilders.com>
---
 README.md                                     | 122 ++++++++++++-
 eslint.config.mjs                             |   1 +
 src/module.ts                                 |  18 +-
 src/runtime/composables.ts                    |  10 +-
 src/runtime/plugin.ts                         |  22 ++-
 test/fixtures/hooks/app.vue                   |  13 ++
 test/fixtures/hooks/nuxt.config.ts            |   5 +
 test/fixtures/hooks/package.json              |   5 +
 .../hooks/plugins/hooks-helper.client.ts      |  57 ++++++
 test/integration-hooks.test.ts                | 171 ++++++++++++++++++
 types/index.d.ts                              |   9 +
 11 files changed, 417 insertions(+), 16 deletions(-)
 create mode 100644 test/fixtures/hooks/app.vue
 create mode 100644 test/fixtures/hooks/nuxt.config.ts
 create mode 100644 test/fixtures/hooks/package.json
 create mode 100644 test/fixtures/hooks/plugins/hooks-helper.client.ts
 create mode 100644 test/integration-hooks.test.ts

diff --git a/README.md b/README.md
index f80033c..f494979 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,7 @@ If a visitor arrives at a website that uses the Nuxt UTM module and a UTM parame
 - **📍 UTM Tracking**: Easily capture UTM parameters to gain insights into traffic sources and campaign performance.
 - **🔍 Intelligent De-duplication**: Smart recognition of page refreshes to avoid data duplication, ensuring each visit is uniquely accounted for.
 - **🔗 Comprehensive Data Collection**: Alongside UTM parameters, gather additional context such as referrer details, user agent, landing page url, browser language, and screen resolution. This enriched data empowers your marketing strategies with a deeper understanding of campaign impact.
+- **🔌 Hooks & Extensibility**: Three runtime hooks (`utm:before-track`, `utm:before-persist`, `utm:tracked`) let you skip tracking, enrich data with custom parameters, or trigger side effects after tracking completes.
 
 ## Quick Setup
 
@@ -86,6 +87,9 @@ const utm = useNuxtUTM()
 // - enableTracking(): Enable UTM tracking
 // - disableTracking(): Disable UTM tracking
 // - clearData(): Clear all stored UTM data
+// - onBeforeTrack(cb): Hook called before data collection
+// - onBeforePersist(cb): Hook called to enrich/modify collected data before saving
+// - onTracked(cb): Hook called after data is saved
 </script>
 ```
 
@@ -125,11 +129,7 @@ const rejectTracking = () => {
   <div class="privacy-settings">
     <h3>Privacy Settings</h3>
     <label>
-      <input 
-        type="checkbox" 
-        :checked="utm.trackingEnabled.value"
-        @change="toggleTracking"
-      />
+      <input type="checkbox" :checked="utm.trackingEnabled.value" @change="toggleTracking" />
       Enable UTM tracking
     </label>
     <button @click="utm.clearData" v-if="utm.data.value.length > 0">
@@ -195,6 +195,9 @@ The `data` property contains an array of UTM parameters collected. Each element
     "gclidParams": {
       "gclid": "CjklsefawEFRfeafads",
       "gad_source": "1"
+    },
+    "customParams": {
+      "fbclid": "abc123"
     }
   }
 ]
@@ -210,6 +213,115 @@ Each entry provides a `timestamp` indicating when the UTM parameters were collec
 - **Data Clearing**: Ability to completely remove all collected data
 - **Session Management**: Automatically manages sessions to avoid duplicate tracking
 
+### Hooks
+
+The module provides three runtime hooks that let you extend the tracking pipeline. You can use them to skip tracking, enrich data with custom parameters, or trigger side effects after tracking completes. Hooks can be registered via a Nuxt plugin or through the `useNuxtUTM` composable.
+
+#### Available Hooks
+
+| Hook               | When it fires                          | Receives                                        | Purpose                                              |
+| ------------------ | -------------------------------------- | ----------------------------------------------- | ---------------------------------------------------- |
+| `utm:before-track` | Before data collection                 | `BeforeTrackContext` (`{ route, query, skip }`) | Conditionally skip tracking by setting `skip = true` |
+| `utm:before-persist` | After data is collected, before saving | `DataObject` (mutable)                        | Enrich or modify the data, add `customParams`        |
+| `utm:tracked`      | After data is saved to localStorage    | `DataObject` (final)                            | Side effects: send to API, fire analytics, log       |
+
+#### Registering Hooks via Plugin
+
+Create a Nuxt plugin to register hooks that run on every page visit:
+
+```typescript
+// plugins/utm-hooks.client.ts
+export default defineNuxtPlugin((nuxtApp) => {
+  // Skip tracking on admin pages
+  nuxtApp.hook('utm:before-track', (context) => {
+    if (context.route.path.startsWith('/admin')) {
+      context.skip = true
+    }
+  })
+
+  // Add custom marketing parameters
+  nuxtApp.hook('utm:before-persist', (data) => {
+    const query = nuxtApp._route.query
+    if (query.fbclid) {
+      data.customParams = {
+        ...data.customParams,
+        fbclid: String(query.fbclid),
+      }
+    }
+    if (query.msclkid) {
+      data.customParams = {
+        ...data.customParams,
+        msclkid: String(query.msclkid),
+      }
+    }
+  })
+
+  // Send data to your backend after tracking
+  nuxtApp.hook('utm:tracked', async (data) => {
+    await $fetch('/api/marketing/track', {
+      method: 'POST',
+      body: data,
+    })
+  })
+})
+```
+
+#### Registering Hooks via Composable
+
+The `useNuxtUTM` composable provides convenience methods for registering hooks. Each method returns a cleanup function to unregister the hook.
+
+```vue
+<script setup>
+const utm = useNuxtUTM()
+
+// Register a before-persist hook
+const cleanup = utm.onBeforePersist((data) => {
+  data.customParams = { ...data.customParams, source: 'vue-component' }
+})
+
+// Unregister when no longer needed
+// cleanup()
+</script>
+```
+
+#### Hook: `utm:before-track`
+
+Called before any data collection begins. The handler receives a `BeforeTrackContext` object with `route`, `query`, and a `skip` flag. Set `skip = true` to prevent tracking for the current page visit.
+
+```typescript
+nuxtApp.hook('utm:before-track', (context) => {
+  // context.route - the current route object
+  // context.query - the current URL query parameters
+  // context.skip  - set to true to skip tracking
+})
+```
+
+#### Hook: `utm:before-persist`
+
+Called after the `DataObject` is built but before it is checked for duplicates and saved. The handler receives the `DataObject` directly and can mutate it to add or modify fields. This is the primary hook for adding `customParams`.
+
+```typescript
+nuxtApp.hook('utm:before-persist', (data) => {
+  // Add any custom tracking parameters
+  data.customParams = {
+    ...data.customParams,
+    myCustomField: 'value',
+  }
+})
+```
+
+> Note: `customParams` are not included in the de-duplication check. Only UTM parameters, GCLID parameters, and session ID are compared.
+
+#### Hook: `utm:tracked`
+
+Called after data is saved to localStorage. The handler receives the final `DataObject`. Use this for side effects like sending data to a backend or triggering analytics events.
+
+```typescript
+nuxtApp.hook('utm:tracked', async (data) => {
+  console.log('Tracked:', data.utmParams, data.customParams)
+})
+```
+
 ## Development
 
 ```bash
diff --git a/eslint.config.mjs b/eslint.config.mjs
index ad56c89..4f44f47 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -17,6 +17,7 @@ export default createConfigForNuxt({
     '@stylistic/quotes': ['error', 'single', { avoidEscape: true }],
     '@stylistic/semi': ['error', 'never'],
     '@stylistic/comma-dangle': ['error', 'always-multiline'],
+    '@stylistic/arrow-parens': ['error', 'always'],
     '@stylistic/operator-linebreak': 'off',
     '@stylistic/brace-style': 'off',
     '@stylistic/indent-binary-ops': 'off',
diff --git a/src/module.ts b/src/module.ts
index 2264bda..8d1145a 100644
--- a/src/module.ts
+++ b/src/module.ts
@@ -1,4 +1,4 @@
-import { defineNuxtModule, addPlugin, addImports, createResolver } from '@nuxt/kit'
+import { defineNuxtModule, addPlugin, addImports, addTypeTemplate, createResolver } from '@nuxt/kit'
 
 export interface ModuleOptions {
   trackingEnabled?: boolean
@@ -27,5 +27,21 @@ export default defineNuxtModule<ModuleOptions>({
       name: 'useNuxtUTM',
       from: resolver.resolve('runtime/composables'),
     })
+
+    addTypeTemplate({
+      filename: 'types/utm-hooks.d.ts',
+      getContents: () =>
+        [
+          'import type { DataObject, BeforeTrackContext } from "nuxt-utm"',
+          '',
+          'declare module "#app" {',
+          '  interface RuntimeNuxtHooks {',
+          '    "utm:before-track": (context: BeforeTrackContext) => void | Promise<void>',
+          '    "utm:before-persist": (data: DataObject) => void | Promise<void>',
+          '    "utm:tracked": (data: DataObject) => void | Promise<void>',
+          '  }',
+          '}',
+        ].join('\n'),
+    })
   },
 })
diff --git a/src/runtime/composables.ts b/src/runtime/composables.ts
index c1838ac..e398965 100644
--- a/src/runtime/composables.ts
+++ b/src/runtime/composables.ts
@@ -1,13 +1,18 @@
 import type { Ref } from 'vue'
-import type { DataObject } from 'nuxt-utm'
+import type { DataObject, BeforeTrackContext } from 'nuxt-utm'
 import { useNuxtApp } from '#imports'
 
+type HookCleanup = () => void
+
 export interface UseNuxtUTMReturn {
   data: Readonly<Ref<readonly DataObject[]>>
   trackingEnabled: Readonly<Ref<boolean>>
   enableTracking: () => void
   disableTracking: () => void
   clearData: () => void
+  onBeforeTrack: (cb: (context: BeforeTrackContext) => void | Promise<void>) => HookCleanup
+  onBeforePersist: (cb: (data: DataObject) => void | Promise<void>) => HookCleanup
+  onTracked: (cb: (data: DataObject) => void | Promise<void>) => HookCleanup
 }
 
 export const useNuxtUTM = (): UseNuxtUTMReturn => {
@@ -19,5 +24,8 @@ export const useNuxtUTM = (): UseNuxtUTMReturn => {
     enableTracking: nuxtApp.$utmEnableTracking,
     disableTracking: nuxtApp.$utmDisableTracking,
     clearData: nuxtApp.$utmClearData,
+    onBeforeTrack: (cb) => nuxtApp.hook('utm:before-track', cb),
+    onBeforePersist: (cb) => nuxtApp.hook('utm:before-persist', cb),
+    onTracked: (cb) => nuxtApp.hook('utm:tracked', cb),
   }
 }
diff --git a/src/runtime/plugin.ts b/src/runtime/plugin.ts
index 59af109..8450945 100644
--- a/src/runtime/plugin.ts
+++ b/src/runtime/plugin.ts
@@ -1,4 +1,4 @@
-import type { DataObject } from 'nuxt-utm'
+import type { DataObject, BeforeTrackContext } from 'nuxt-utm'
 import { ref, readonly } from 'vue'
 import {
   readLocalData,
@@ -19,7 +19,6 @@ export default defineNuxtPlugin((nuxtApp) => {
   const config = useRuntimeConfig()
   const data = ref<DataObject[]>([])
 
-  // Initialize tracking enabled state from config or localStorage
   const getInitialTrackingState = (): boolean => {
     if (typeof window === 'undefined') return config.public.utm?.trackingEnabled ?? true
 
@@ -32,15 +31,20 @@ export default defineNuxtPlugin((nuxtApp) => {
 
   const trackingEnabled = ref(getInitialTrackingState())
 
-  const processUtmData = () => {
+  const processUtmData = async () => {
     if (typeof window === 'undefined') return
     if (!trackingEnabled.value) return
 
     data.value = readLocalData(LOCAL_STORAGE_KEY)
 
-    const sessionId = getSessionID(SESSION_ID_KEY)
-
     const query = nuxtApp._route.query
+    const route = nuxtApp._route
+
+    const beforeTrackContext: BeforeTrackContext = { route, query, skip: false }
+    await nuxtApp.callHook('utm:before-track', beforeTrackContext)
+    if (beforeTrackContext.skip) return
+
+    const sessionId = getSessionID(SESSION_ID_KEY)
     const utmParams = getUtmParams(query)
     const additionalInfo = getAdditionalInfo()
     const timestamp = new Date().toISOString()
@@ -56,19 +60,20 @@ export default defineNuxtPlugin((nuxtApp) => {
       dataObject.gclidParams = getGCLID(query)
     }
 
-    // Exit if the last entry is the same as the new entry
+    await nuxtApp.callHook('utm:before-persist', dataObject)
+
     if (isRepeatedEntry(data, dataObject)) return
 
-    // Add the new item to the data array
     data.value.unshift(dataObject)
     localStorage.setItem(LOCAL_STORAGE_KEY, JSON.stringify(data.value))
+
+    await nuxtApp.callHook('utm:tracked', dataObject)
   }
 
   const enableTracking = () => {
     trackingEnabled.value = true
     if (typeof window !== 'undefined') {
       localStorage.setItem(TRACKING_ENABLED_KEY, 'true')
-      // Process current page data when enabling
       processUtmData()
     }
   }
@@ -88,7 +93,6 @@ export default defineNuxtPlugin((nuxtApp) => {
     }
   }
 
-  // Load existing data on initialization
   if (typeof window !== 'undefined') {
     data.value = readLocalData(LOCAL_STORAGE_KEY)
   }
diff --git a/test/fixtures/hooks/app.vue b/test/fixtures/hooks/app.vue
new file mode 100644
index 0000000..cc11a3a
--- /dev/null
+++ b/test/fixtures/hooks/app.vue
@@ -0,0 +1,13 @@
+<template>
+  <div>
+    <h1>UTM Tracker</h1>
+    <p>Tracking: {{ utm.trackingEnabled.value ? 'Enabled' : 'Disabled' }}</p>
+    <pre>{{ utm.data.value }}</pre>
+  </div>
+</template>
+
+<script setup>
+import { useNuxtUTM } from '#imports'
+
+const utm = useNuxtUTM()
+</script>
diff --git a/test/fixtures/hooks/nuxt.config.ts b/test/fixtures/hooks/nuxt.config.ts
new file mode 100644
index 0000000..c412069
--- /dev/null
+++ b/test/fixtures/hooks/nuxt.config.ts
@@ -0,0 +1,5 @@
+import UtmModule from '../../../src/module'
+
+export default defineNuxtConfig({
+  modules: [UtmModule],
+})
diff --git a/test/fixtures/hooks/package.json b/test/fixtures/hooks/package.json
new file mode 100644
index 0000000..088cb33
--- /dev/null
+++ b/test/fixtures/hooks/package.json
@@ -0,0 +1,5 @@
+{
+  "private": true,
+  "name": "hooks",
+  "type": "module"
+}
diff --git a/test/fixtures/hooks/plugins/hooks-helper.client.ts b/test/fixtures/hooks/plugins/hooks-helper.client.ts
new file mode 100644
index 0000000..1680fdb
--- /dev/null
+++ b/test/fixtures/hooks/plugins/hooks-helper.client.ts
@@ -0,0 +1,57 @@
+import type { DataObject, BeforeTrackContext } from 'nuxt-utm'
+import { defineNuxtPlugin } from '#app'
+import { useNuxtUTM } from '#imports'
+
+declare global {
+  interface Window {
+    useNuxtUTM: typeof useNuxtUTM
+    __utmHookResults: {
+      beforeTrackCalled: boolean
+      beforeTrackContext: BeforeTrackContext | null
+      beforePersistCalled: boolean
+      beforePersistData: DataObject | null
+      trackedCalled: boolean
+      trackedData: DataObject | null
+    }
+  }
+}
+
+export default defineNuxtPlugin((nuxtApp) => {
+  if (typeof window === 'undefined') return
+
+  window.useNuxtUTM = useNuxtUTM
+
+  window.__utmHookResults = {
+    beforeTrackCalled: false,
+    beforeTrackContext: null,
+    beforePersistCalled: false,
+    beforePersistData: null,
+    trackedCalled: false,
+    trackedData: null,
+  }
+
+  nuxtApp.hook('utm:before-track', (context) => {
+    window.__utmHookResults.beforeTrackCalled = true
+    window.__utmHookResults.beforeTrackContext = { ...context }
+
+    if (context.query._skip_tracking === '1') {
+      context.skip = true
+    }
+  })
+
+  nuxtApp.hook('utm:before-persist', (data) => {
+    window.__utmHookResults.beforePersistCalled = true
+    window.__utmHookResults.beforePersistData = { ...data }
+
+    data.customParams = {
+      ...data.customParams,
+      hooked: true,
+      fbclid: data.additionalInfo?.landingPageUrl?.includes('fbclid') ? 'from-hook' : undefined,
+    }
+  })
+
+  nuxtApp.hook('utm:tracked', (data) => {
+    window.__utmHookResults.trackedCalled = true
+    window.__utmHookResults.trackedData = JSON.parse(JSON.stringify(data))
+  })
+})
diff --git a/test/integration-hooks.test.ts b/test/integration-hooks.test.ts
new file mode 100644
index 0000000..14a3e9c
--- /dev/null
+++ b/test/integration-hooks.test.ts
@@ -0,0 +1,171 @@
+import { fileURLToPath } from 'node:url'
+import type { DataObject } from 'nuxt-utm'
+import { describe, it, expect } from 'vitest'
+import { setup, createPage } from '@nuxt/test-utils'
+import type { Page } from 'playwright-core'
+
+interface BeforeTrackResult {
+  route: unknown
+  query: Record<string, string>
+  skip: boolean
+}
+
+interface HookResults {
+  beforeTrackCalled: boolean
+  beforeTrackContext: BeforeTrackResult | null
+  beforePersistCalled: boolean
+  beforePersistData: DataObject | null
+  trackedCalled: boolean
+  trackedData: DataObject | null
+}
+
+const getHookResults = (page: Page): Promise<HookResults> =>
+  page.evaluate(() => (window as unknown as { __utmHookResults: HookResults }).__utmHookResults)
+
+const getStoredEntries = async (page: Page): Promise<DataObject[]> => {
+  const raw = await page.evaluate(() => window.localStorage.getItem('nuxt-utm-data'))
+  return JSON.parse(raw ?? '[]')
+}
+
+describe('Hooks mechanism', async () => {
+  await setup({
+    rootDir: fileURLToPath(new URL('./fixtures/hooks', import.meta.url)),
+    server: true,
+    browser: true,
+  })
+
+  describe('utm:before-track', () => {
+    it('is called with route and query context', async () => {
+      const page = await createPage('/?utm_source=hook_test&utm_medium=test')
+      await page.waitForFunction(
+        () =>
+          (window as unknown as { __utmHookResults: HookResults }).__utmHookResults
+            ?.beforeTrackCalled,
+      )
+
+      const results = await getHookResults(page)
+      expect(results.beforeTrackCalled).toBe(true)
+      expect(results.beforeTrackContext).toBeDefined()
+      expect(results.beforeTrackContext!.query.utm_source).toBe('hook_test')
+      expect(results.beforeTrackContext!.skip).toBe(false)
+
+      await page.close()
+    })
+
+    it('skips tracking when skip is set to true', async () => {
+      const page = await createPage('/?utm_source=skipped&_skip_tracking=1')
+      await page.waitForFunction(
+        () =>
+          (window as unknown as { __utmHookResults: HookResults }).__utmHookResults
+            ?.beforeTrackCalled,
+      )
+
+      const results = await getHookResults(page)
+      expect(results.beforeTrackCalled).toBe(true)
+      expect(results.beforePersistCalled).toBe(false)
+      expect(results.trackedCalled).toBe(false)
+
+      const entries = await getStoredEntries(page)
+      const hasSkipped = entries.some((e: DataObject) => e.utmParams?.utm_source === 'skipped')
+      expect(hasSkipped).toBe(false)
+
+      await page.close()
+    })
+  })
+
+  describe('utm:before-persist', () => {
+    it('is called after data collection', async () => {
+      const page = await createPage('/?utm_source=persist_test&utm_medium=test')
+      await page.waitForFunction(
+        () =>
+          (window as unknown as { __utmHookResults: HookResults }).__utmHookResults
+            ?.beforePersistCalled,
+      )
+
+      const results = await getHookResults(page)
+      expect(results.beforePersistCalled).toBe(true)
+      expect(results.beforePersistData).toBeDefined()
+      expect(results.beforePersistData!.utmParams.utm_source).toBe('persist_test')
+
+      await page.close()
+    })
+
+    it('allows adding customParams to the data object', async () => {
+      const page = await createPage('/?utm_source=custom_test&utm_medium=test')
+      await page.waitForFunction(() => window.localStorage.getItem('nuxt-utm-data'))
+
+      const entries = await getStoredEntries(page)
+      expect(entries[0]?.customParams).toBeDefined()
+      expect(entries[0]?.customParams?.hooked).toBe(true)
+
+      await page.close()
+    })
+  })
+
+  describe('utm:tracked', () => {
+    it('is called after data is saved', async () => {
+      const page = await createPage('/?utm_source=tracked_test&utm_medium=test')
+      await page.waitForFunction(
+        () =>
+          (window as unknown as { __utmHookResults: HookResults }).__utmHookResults?.trackedCalled,
+      )
+
+      const results = await getHookResults(page)
+      expect(results.trackedCalled).toBe(true)
+      expect(results.trackedData).toBeDefined()
+      expect(results.trackedData!.utmParams.utm_source).toBe('tracked_test')
+      expect(results.trackedData!.customParams?.hooked).toBe(true)
+
+      await page.close()
+    })
+
+    it('receives the same data that was saved to localStorage', async () => {
+      const page = await createPage('/?utm_source=verify_save&utm_medium=test')
+      await page.waitForFunction(
+        () =>
+          (window as unknown as { __utmHookResults: HookResults }).__utmHookResults?.trackedCalled,
+      )
+
+      const results = await getHookResults(page)
+      const entries = await getStoredEntries(page)
+
+      expect(results.trackedData!.utmParams).toEqual(entries[0]?.utmParams)
+      expect(results.trackedData!.sessionId).toEqual(entries[0]?.sessionId)
+
+      await page.close()
+    })
+  })
+
+  describe('hook ordering', () => {
+    it('calls hooks in order: before-track, before-persist, tracked', async () => {
+      const page = await createPage('/?utm_source=order_test&utm_medium=test')
+      await page.waitForFunction(
+        () =>
+          (window as unknown as { __utmHookResults: HookResults }).__utmHookResults?.trackedCalled,
+      )
+
+      const results = await getHookResults(page)
+      expect(results.beforeTrackCalled).toBe(true)
+      expect(results.beforePersistCalled).toBe(true)
+      expect(results.trackedCalled).toBe(true)
+
+      await page.close()
+    })
+
+    it('does not call before-persist or tracked when before-track skips', async () => {
+      const page = await createPage('/?utm_source=skip_order&_skip_tracking=1')
+      await page.waitForFunction(
+        () =>
+          (window as unknown as { __utmHookResults: HookResults }).__utmHookResults
+            ?.beforeTrackCalled,
+      )
+
+      const results = await getHookResults(page)
+      expect(results.beforeTrackCalled).toBe(true)
+      expect(results.beforePersistCalled).toBe(false)
+      expect(results.trackedCalled).toBe(false)
+
+      await page.close()
+    })
+  })
+})
diff --git a/types/index.d.ts b/types/index.d.ts
index 3829484..abc907d 100644
--- a/types/index.d.ts
+++ b/types/index.d.ts
@@ -1,4 +1,6 @@
 declare module 'nuxt-utm' {
+  import type { RouteLocationNormalized, LocationQuery } from 'vue-router'
+
   interface UTMParams {
     utm_source?: string
     utm_medium?: string
@@ -29,5 +31,12 @@ declare module 'nuxt-utm' {
     additionalInfo: AdditionalInfo
     sessionId: string
     gclidParams?: GCLIDParams
+    customParams?: Record<string, unknown>
+  }
+
+  interface BeforeTrackContext {
+    route: RouteLocationNormalized
+    query: LocationQuery
+    skip: boolean
   }
 }

From c9fafe536d6b3c01254c4ff62bfb6e0d4d43f5cd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sadjow=20Le=C3=A3o?= <sadjow@gmail.com>
Date: Thu, 26 Feb 2026 11:17:49 -0300
Subject: [PATCH 2/4] fix: harden hook pipeline and validate execution order

---
 src/runtime/plugin.ts                         | 41 ++++++++++-
 .../hooks/plugins/hooks-helper.client.ts      | 19 +++++
 test/integration-hooks.test.ts                | 73 +++++++++++++++++++
 3 files changed, 129 insertions(+), 4 deletions(-)

diff --git a/src/runtime/plugin.ts b/src/runtime/plugin.ts
index 8450945..a5e7a5f 100644
--- a/src/runtime/plugin.ts
+++ b/src/runtime/plugin.ts
@@ -19,6 +19,38 @@ export default defineNuxtPlugin((nuxtApp) => {
   const config = useRuntimeConfig()
   const data = ref<DataObject[]>([])
 
+  const logHookError = (hookName: string, error: unknown): boolean => {
+    console.error(`[nuxt-utm] Hook "${hookName}" failed`, error)
+    return false
+  }
+
+  const runBeforeTrackHook = async (context: BeforeTrackContext): Promise<boolean> => {
+    try {
+      await nuxtApp.callHook('utm:before-track', context)
+      return true
+    } catch (error) {
+      return logHookError('utm:before-track', error)
+    }
+  }
+
+  const runBeforePersistHook = async (dataObject: DataObject): Promise<boolean> => {
+    try {
+      await nuxtApp.callHook('utm:before-persist', dataObject)
+      return true
+    } catch (error) {
+      return logHookError('utm:before-persist', error)
+    }
+  }
+
+  const runTrackedHook = async (dataObject: DataObject): Promise<boolean> => {
+    try {
+      await nuxtApp.callHook('utm:tracked', dataObject)
+      return true
+    } catch (error) {
+      return logHookError('utm:tracked', error)
+    }
+  }
+
   const getInitialTrackingState = (): boolean => {
     if (typeof window === 'undefined') return config.public.utm?.trackingEnabled ?? true
 
@@ -41,8 +73,8 @@ export default defineNuxtPlugin((nuxtApp) => {
     const route = nuxtApp._route
 
     const beforeTrackContext: BeforeTrackContext = { route, query, skip: false }
-    await nuxtApp.callHook('utm:before-track', beforeTrackContext)
-    if (beforeTrackContext.skip) return
+    const beforeTrackSucceeded = await runBeforeTrackHook(beforeTrackContext)
+    if (!beforeTrackSucceeded || beforeTrackContext.skip) return
 
     const sessionId = getSessionID(SESSION_ID_KEY)
     const utmParams = getUtmParams(query)
@@ -60,14 +92,15 @@ export default defineNuxtPlugin((nuxtApp) => {
       dataObject.gclidParams = getGCLID(query)
     }
 
-    await nuxtApp.callHook('utm:before-persist', dataObject)
+    const beforePersistSucceeded = await runBeforePersistHook(dataObject)
+    if (!beforePersistSucceeded) return
 
     if (isRepeatedEntry(data, dataObject)) return
 
     data.value.unshift(dataObject)
     localStorage.setItem(LOCAL_STORAGE_KEY, JSON.stringify(data.value))
 
-    await nuxtApp.callHook('utm:tracked', dataObject)
+    await runTrackedHook(dataObject)
   }
 
   const enableTracking = () => {
diff --git a/test/fixtures/hooks/plugins/hooks-helper.client.ts b/test/fixtures/hooks/plugins/hooks-helper.client.ts
index 1680fdb..fb2a79b 100644
--- a/test/fixtures/hooks/plugins/hooks-helper.client.ts
+++ b/test/fixtures/hooks/plugins/hooks-helper.client.ts
@@ -12,6 +12,7 @@ declare global {
       beforePersistData: DataObject | null
       trackedCalled: boolean
       trackedData: DataObject | null
+      callOrder: string[]
     }
   }
 }
@@ -28,21 +29,33 @@ export default defineNuxtPlugin((nuxtApp) => {
     beforePersistData: null,
     trackedCalled: false,
     trackedData: null,
+    callOrder: [],
   }
 
   nuxtApp.hook('utm:before-track', (context) => {
+    window.__utmHookResults.callOrder.push('before-track')
     window.__utmHookResults.beforeTrackCalled = true
     window.__utmHookResults.beforeTrackContext = { ...context }
 
+    if (context.query._throw_before_track === '1') {
+      throw new Error('before-track hook error')
+    }
+
     if (context.query._skip_tracking === '1') {
       context.skip = true
     }
   })
 
   nuxtApp.hook('utm:before-persist', (data) => {
+    window.__utmHookResults.callOrder.push('before-persist')
     window.__utmHookResults.beforePersistCalled = true
     window.__utmHookResults.beforePersistData = { ...data }
 
+    const url = new URL(data.additionalInfo.landingPageUrl)
+    if (url.searchParams.get('_throw_before_persist') === '1') {
+      throw new Error('before-persist hook error')
+    }
+
     data.customParams = {
       ...data.customParams,
       hooked: true,
@@ -51,7 +64,13 @@ export default defineNuxtPlugin((nuxtApp) => {
   })
 
   nuxtApp.hook('utm:tracked', (data) => {
+    window.__utmHookResults.callOrder.push('tracked')
     window.__utmHookResults.trackedCalled = true
     window.__utmHookResults.trackedData = JSON.parse(JSON.stringify(data))
+
+    const url = new URL(data.additionalInfo.landingPageUrl)
+    if (url.searchParams.get('_throw_tracked') === '1') {
+      throw new Error('tracked hook error')
+    }
   })
 })
diff --git a/test/integration-hooks.test.ts b/test/integration-hooks.test.ts
index 14a3e9c..33dc82d 100644
--- a/test/integration-hooks.test.ts
+++ b/test/integration-hooks.test.ts
@@ -17,6 +17,7 @@ interface HookResults {
   beforePersistData: DataObject | null
   trackedCalled: boolean
   trackedData: DataObject | null
+  callOrder: string[]
 }
 
 const getHookResults = (page: Page): Promise<HookResults> =>
@@ -148,6 +149,7 @@ describe('Hooks mechanism', async () => {
       expect(results.beforeTrackCalled).toBe(true)
       expect(results.beforePersistCalled).toBe(true)
       expect(results.trackedCalled).toBe(true)
+      expect(results.callOrder).toEqual(['before-track', 'before-persist', 'tracked'])
 
       await page.close()
     })
@@ -164,6 +166,77 @@ describe('Hooks mechanism', async () => {
       expect(results.beforeTrackCalled).toBe(true)
       expect(results.beforePersistCalled).toBe(false)
       expect(results.trackedCalled).toBe(false)
+      expect(results.callOrder).toEqual(['before-track'])
+
+      await page.close()
+    })
+  })
+
+  describe('hook errors', () => {
+    it('stops tracking when before-track throws', async () => {
+      const page = await createPage('/?utm_source=throw_before_track&_throw_before_track=1')
+      await page.waitForFunction(
+        () =>
+          (window as unknown as { __utmHookResults: HookResults }).__utmHookResults
+            ?.beforeTrackCalled,
+      )
+
+      const results = await getHookResults(page)
+      expect(results.beforeTrackCalled).toBe(true)
+      expect(results.beforePersistCalled).toBe(false)
+      expect(results.trackedCalled).toBe(false)
+      expect(results.callOrder).toEqual(['before-track'])
+
+      const entries = await getStoredEntries(page)
+      const hasTrackedEntry = entries.some(
+        (entry: DataObject) => entry.utmParams?.utm_source === 'throw_before_track',
+      )
+      expect(hasTrackedEntry).toBe(false)
+
+      await page.close()
+    })
+
+    it('stops tracking when before-persist throws', async () => {
+      const page = await createPage('/?utm_source=throw_before_persist&_throw_before_persist=1')
+      await page.waitForFunction(
+        () =>
+          (window as unknown as { __utmHookResults: HookResults }).__utmHookResults
+            ?.beforePersistCalled,
+      )
+
+      const results = await getHookResults(page)
+      expect(results.beforeTrackCalled).toBe(true)
+      expect(results.beforePersistCalled).toBe(true)
+      expect(results.trackedCalled).toBe(false)
+      expect(results.callOrder).toEqual(['before-track', 'before-persist'])
+
+      const entries = await getStoredEntries(page)
+      const hasTrackedEntry = entries.some(
+        (entry: DataObject) => entry.utmParams?.utm_source === 'throw_before_persist',
+      )
+      expect(hasTrackedEntry).toBe(false)
+
+      await page.close()
+    })
+
+    it('keeps stored data when tracked throws', async () => {
+      const page = await createPage('/?utm_source=throw_tracked&_throw_tracked=1')
+      await page.waitForFunction(
+        () =>
+          (window as unknown as { __utmHookResults: HookResults }).__utmHookResults?.trackedCalled,
+      )
+
+      const results = await getHookResults(page)
+      expect(results.beforeTrackCalled).toBe(true)
+      expect(results.beforePersistCalled).toBe(true)
+      expect(results.trackedCalled).toBe(true)
+      expect(results.callOrder).toEqual(['before-track', 'before-persist', 'tracked'])
+
+      const entries = await getStoredEntries(page)
+      const savedEntry = entries.find(
+        (entry: DataObject) => entry.utmParams?.utm_source === 'throw_tracked',
+      )
+      expect(savedEntry).toBeDefined()
 
       await page.close()
     })

From 31cc021cd259dcc648fd32bdaa012961c762eb54 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sadjow=20Le=C3=A3o?= <sadjow@gmail.com>
Date: Thu, 26 Feb 2026 11:30:48 -0300
Subject: [PATCH 3/4] feat(playground): add page category hook testing flow

---
 playground/app.vue                            | 46 +++++++++++++++----
 playground/plugins/page-category.client.ts    | 16 +++++++
 .../hooks/plugins/page-category.client.ts     | 19 ++++++++
 test/integration-hooks.test.ts                | 16 +++++++
 4 files changed, 87 insertions(+), 10 deletions(-)
 create mode 100644 playground/plugins/page-category.client.ts
 create mode 100644 test/fixtures/hooks/plugins/page-category.client.ts

diff --git a/playground/app.vue b/playground/app.vue
index d4865da..4b1f42a 100644
--- a/playground/app.vue
+++ b/playground/app.vue
@@ -6,22 +6,18 @@
       <h2>Tracking Controls</h2>
       <p>
         Tracking is currently:
-        <strong :class="{ enabled: utm.trackingEnabled.value, disabled: !utm.trackingEnabled.value }">
+        <strong
+          :class="{ enabled: utm.trackingEnabled.value, disabled: !utm.trackingEnabled.value }"
+        >
           {{ utm.trackingEnabled.value ? 'ENABLED' : 'DISABLED' }}
         </strong>
       </p>
 
       <div class="buttons">
-        <button
-          :disabled="utm.trackingEnabled.value"
-          @click="utm.enableTracking"
-        >
+        <button @click="utm.enableTracking">
           Enable Tracking
         </button>
-        <button
-          :disabled="!utm.trackingEnabled.value"
-          @click="utm.disableTracking"
-        >
+        <button @click="utm.disableTracking">
           Disable Tracking
         </button>
         <button
@@ -32,11 +28,25 @@
         </button>
       </div>
 
+      <h2>Custom Hook Testing</h2>
+      <div class="buttons">
+        <button @click="visitWithPageCategory('pricing')">
+          Track pageCategory: pricing
+        </button>
+        <button @click="visitWithPageCategory('features')">
+          Track pageCategory: features
+        </button>
+      </div>
+
       <div class="info">
         <p>Try visiting with UTM parameters:</p>
         <a href="/?utm_source=test&utm_medium=demo&utm_campaign=playground">
           Add UTM params to URL
         </a>
+        <p class="hint">
+          Then click a custom hook button above and check
+          <code>customParams.pageCategory</code> in collected data.
+        </p>
       </div>
     </div>
 
@@ -51,6 +61,15 @@
 import { useNuxtUTM } from '#imports'
 
 const utm = useNuxtUTM()
+
+const visitWithPageCategory = (pageCategory) => {
+  const url = new URL(window.location.href)
+  url.searchParams.set('utm_source', 'playground')
+  url.searchParams.set('utm_medium', 'manual-test')
+  url.searchParams.set('utm_campaign', 'custom-hook')
+  url.searchParams.set('page_category', pageCategory)
+  window.location.href = `${url.pathname}?${url.searchParams.toString()}`
+}
 </script>
 
 <style scoped>
@@ -58,7 +77,10 @@ const utm = useNuxtUTM()
   max-width: 1200px;
   margin: 0 auto;
   padding: 2rem;
-  font-family: system-ui, -apple-system, sans-serif;
+  font-family:
+    system-ui,
+    -apple-system,
+    sans-serif;
 }
 
 h1 {
@@ -129,6 +151,10 @@ button.danger:hover {
   text-decoration: underline;
 }
 
+.hint {
+  margin-top: 0.75rem;
+}
+
 .data {
   background: #f8f9fa;
   padding: 1.5rem;
diff --git a/playground/plugins/page-category.client.ts b/playground/plugins/page-category.client.ts
new file mode 100644
index 0000000..7818f9a
--- /dev/null
+++ b/playground/plugins/page-category.client.ts
@@ -0,0 +1,16 @@
+import { defineNuxtPlugin } from '#app'
+import { useNuxtUTM } from '#imports'
+
+export default defineNuxtPlugin(() => {
+  const utm = useNuxtUTM()
+
+  utm.onBeforePersist((data) => {
+    const pageCategory = new URL(data.additionalInfo.landingPageUrl).searchParams.get('page_category')
+    if (!pageCategory) return
+
+    data.customParams = {
+      ...data.customParams,
+      pageCategory,
+    }
+  })
+})
diff --git a/test/fixtures/hooks/plugins/page-category.client.ts b/test/fixtures/hooks/plugins/page-category.client.ts
new file mode 100644
index 0000000..0611dfb
--- /dev/null
+++ b/test/fixtures/hooks/plugins/page-category.client.ts
@@ -0,0 +1,19 @@
+import { defineNuxtPlugin } from '#app'
+import { useNuxtUTM } from '#imports'
+
+export default defineNuxtPlugin(() => {
+  const utm = useNuxtUTM()
+
+  utm.onBeforePersist((data) => {
+    const landingPageUrl = data.additionalInfo?.landingPageUrl
+    if (!landingPageUrl) return
+
+    const pageCategory = new URL(landingPageUrl).searchParams.get('page_category')
+    if (!pageCategory) return
+
+    data.customParams = {
+      ...data.customParams,
+      pageCategory,
+    }
+  })
+})
diff --git a/test/integration-hooks.test.ts b/test/integration-hooks.test.ts
index 33dc82d..1e7b879 100644
--- a/test/integration-hooks.test.ts
+++ b/test/integration-hooks.test.ts
@@ -101,6 +101,22 @@ describe('Hooks mechanism', async () => {
 
       await page.close()
     })
+
+    it('supports consumer hooks for custom pageCategory tracking', async () => {
+      const page = await createPage(
+        '/?utm_source=page_category_test&utm_medium=test&page_category=pricing',
+      )
+      await page.waitForFunction(() => window.localStorage.getItem('nuxt-utm-data'))
+
+      const entries = await getStoredEntries(page)
+      const trackedEntry = entries.find(
+        (entry: DataObject) => entry.utmParams?.utm_source === 'page_category_test',
+      )
+
+      expect(trackedEntry?.customParams?.pageCategory).toBe('pricing')
+
+      await page.close()
+    })
   })
 
   describe('utm:tracked', () => {

From 12d4f6b418d0e5763dfe4649fcee5e4af52a46b8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sadjow=20Le=C3=A3o?= <sadjow@gmail.com>
Date: Thu, 26 Feb 2026 11:35:33 -0300
Subject: [PATCH 4/4] docs: add pageCategory hook example to README

---
 README.md | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/README.md b/README.md
index f494979..398754e 100644
--- a/README.md
+++ b/README.md
@@ -217,6 +217,8 @@ Each entry provides a `timestamp` indicating when the UTM parameters were collec
 
 The module provides three runtime hooks that let you extend the tracking pipeline. You can use them to skip tracking, enrich data with custom parameters, or trigger side effects after tracking completes. Hooks can be registered via a Nuxt plugin or through the `useNuxtUTM` composable.
 
+This keeps your tracking strategy flexible: enrich once in your app, then forward the same enriched payload wherever you need it.
+
 #### Available Hooks
 
 | Hook               | When it fires                          | Receives                                        | Purpose                                              |
@@ -284,6 +286,38 @@ const cleanup = utm.onBeforePersist((data) => {
 </script>
 ```
 
+#### Example: add `pageCategory`
+
+Use `utm:before-persist` to enrich every tracked event with a normalized `pageCategory`. This pattern is useful when you want one internal taxonomy that can be reused across your app and backend.
+
+```typescript
+// plugins/utm-page-category.client.ts
+export default defineNuxtPlugin((nuxtApp) => {
+  nuxtApp.hook('utm:before-persist', (data) => {
+    const url = new URL(data.additionalInfo.landingPageUrl)
+    const explicitCategory = url.searchParams.get('page_category')
+
+    // Optional fallback categorization from pathname
+    const fallbackCategory = url.pathname.startsWith('/pricing') ? 'pricing' : 'general'
+
+    data.customParams = {
+      ...data.customParams,
+      pageCategory: explicitCategory ?? fallbackCategory,
+    }
+  })
+})
+```
+
+Tracked data will include:
+
+```json
+{
+  "customParams": {
+    "pageCategory": "pricing"
+  }
+}
+```
+
 #### Hook: `utm:before-track`
 
 Called before any data collection begins. The handler receives a `BeforeTrackContext` object with `route`, `query`, and a `skip` flag. Set `skip = true` to prevent tracking for the current page visit.