Nuxt UTM

A Nuxt 3 module for tracking UTM parameters.

• ✨  Release Notes

Features

• ✅ Automatically capture UTM parameters from URL query strings
• ✅ Store UTM data persistently in localStorage with session tracking
• ✅ Support for Google Ads parameters (gclid, gad_source)
• ✅ Additional context (referrer, user agent, screen size, landing page)
• ✅ TypeScript support
• ✅ Enable/disable tracking via configuration or runtime
• ✅ Composable API for easy access

Quick Setup

1. Add nuxt-utm dependency to your project

# Using npm
npm install --save-dev nuxt-utm

# Using yarn
yarn add --dev nuxt-utm

# Using pnpm
pnpm add -D nuxt-utm

2. Add nuxt-utm to the modules section of nuxt.config.ts

export default defineNuxtConfig({
  modules: ['nuxt-utm'],
  utm: {
    enabled: true, // Set to false to disable capturing UTM parameters
  },
})

Configuration

Module Options

Option	Type	Default	Description
enabled	boolean	true	Enable or disable UTM parameter tracking

Example configurations:

// Disable UTM tracking completely
export default defineNuxtConfig({
  modules: ['nuxt-utm'],
  utm: {
    enabled: false,
  },
})

// Enable UTM tracking (default behavior)
export default defineNuxtConfig({
  modules: ['nuxt-utm'],
  utm: {
    enabled: true,
  },
})

Usage

Basic Usage

You can use useNuxtUTM composable to access the UTM object:

<script setup>
const { data, enabled, clear } = useNuxtUTM()

// Access UTM data
console.log(data.value) // Array of UTM data objects

// Check if tracking is enabled
console.log(enabled.value) // boolean

// Disable tracking at runtime (e.g., when user opts out)
enabled.value = false

// Re-enable tracking
enabled.value = true

// Clear all UTM data
clear()
</script>

Alternative Access via Nuxt App

Alternatively, you can get the UTM information through the Nuxt App:

<script setup>
import { useNuxtApp } from 'nuxt/app'
const { $utm } = useNuxtApp()
const { data, enabled, clear } = $utm

// Disable tracking
$utm.enabled.value = false

// Clear all data
$utm.clear()
</script>

Runtime Tracking Control

The module provides runtime control over UTM tracking, which is useful for implementing user consent flows:

<template>
  <div>
    <h1>Privacy Settings</h1>
    <label>
      <input 
        type="checkbox" 
        v-model="trackingEnabled"
        @change="handleTrackingToggle"
      >
      Allow UTM tracking
    </label>
    
    <div v-if="trackingEnabled">
      <h2>Current UTM Data</h2>
      <pre>{{ utmData }}</pre>
    </div>
  </div>
</template>

<script setup>
const { data: utmData, enabled, clear } = useNuxtUTM()

const trackingEnabled = ref(enabled.value)

const handleTrackingToggle = () => {
  enabled.value = trackingEnabled.value
  
  // Optionally clear existing data when disabled
  if (!trackingEnabled.value) {
    clear()
  }
}
</script>

Data Structure

Regardless of the option you choose to use the module, the data will contain an array of UTM parameters collected for use. Each element in the array represents a set of UTM parameters collected from a URL visit, and is structured as follows:

[
  {
    "timestamp": "2023-11-02T10:11:17.219Z",
    "utmParams": {
      "utm_source": "test_source",
      "utm_medium": "test_medium",
      "utm_campaign": "test_campaign",
      "utm_term": "test_term",
      "utm_content": "test_content"
    },
    "additionalInfo": {
      "referrer": "http://referrer.url",
      "userAgent": "User-Agent String",
      "language": "en-GB",
      "landingPageUrl": "http://landingpage.url",
      "screen": {
        "width": 1728,
        "height": 1117
      }
    },
    "sessionId": "beai1gx7dg",
    "gclidParams": {
      "gclid": "CjklsefawEFRfeafads",
      "gad_source": "1"
    }
  }
]

In the data array, each entry provides:

• timestamp: When the UTM parameters were collected
• utmParams: The UTM parameters from the URL
• additionalInfo: Context about the visit (referrer, user agent, etc.)
• sessionId: Unique identifier for the user session
• gclidParams: Google Ads click identifier and source (if present)

Common Use Cases

GDPR/Privacy Compliance

<script setup>
const { enabled, clear } = useNuxtUTM()

// Check user's consent from your privacy management system
const hasConsent = await checkUserConsent()
enabled.value = hasConsent

// Listen for consent changes
onConsentChange((newConsent) => {
  enabled.value = newConsent
  if (!newConsent) {
    // Clear existing UTM data using the built-in clear function
    clear()
  }
})
</script>

Conditional Tracking by Environment

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-utm'],
  utm: {
    // Only enable in production
    enabled: process.env.NODE_ENV === 'production',
  },
})

A/B Testing with Tracking Control

<script setup>
const { enabled } = useNuxtUTM()

// Enable tracking only for certain user segments
const userSegment = await getUserSegment()
enabled.value = userSegment === 'tracking-enabled'
</script>

Development

# Install dependencies
yarn install

# Generate type stubs
yarn dev:prepare

# Develop with the playground
yarn dev

# Build the playground
yarn dev:build

# Run ESLint
yarn lint

# Install Playwright Browsers
npx playwright install --with-deps

# Run Vitest
yarn test
yarn test:watch

# Release new version
yarn release

For detailed information about the release process, please refer to our Release Documentation.

License

MIT, see the LICENSE file.

Contributing

Do you want to contribute to this project? Please take a look at our contributing guideline to know how you can help us build it.

---

Check out our libraries | Join our team