Skip to content

Commit c58c790

Browse files
sadjowsadjow
committed
chore: support enable disable
1 parent b05e9bf commit c58c790

File tree

12 files changed

+518
-45
lines changed

12 files changed

+518
-45
lines changed

‎README.md‎

Lines changed: 170 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,78 +1,169 @@
11
# Nuxt UTM
22

3-
[![CI](https://github.com/stackbuilders/nuxt-utm/actions/workflows/main.yml/badge.svg)](https://github.com/stackbuilders/nuxt-utm/actions/workflows/main.yml)
43
[![npm version][npm-version-src]][npm-version-href]
54
[![npm downloads][npm-downloads-src]][npm-downloads-href]
65
[![License][license-src]][license-href]
76
[![Nuxt][nuxt-src]][nuxt-href]
7+
[![CI](https://github.com/stackbuilders/nuxt-utm/actions/workflows/main.yml/badge.svg)](https://github.com/stackbuilders/nuxt-utm/actions/workflows/main.yml)
88

9-
**Built in collaboration with The Durst Organization**
10-
11-
---
12-
13-
A Nuxt 3 module for tracking UTM parameters.
9+
A [Nuxt 3](https://nuxt.com) module for tracking UTM parameters.
1410

1511
- [✨  Release Notes](/CHANGELOG.md)
16-
<!-- - [🏀 Online playground](https://stackblitz.com/github/stackbuilders/nuxt-utm?file=playground%2Fapp.vue) -->
17-
<!-- - [📖 &nbsp;Documentation](https://example.com) -->
18-
19-
## How it works / motivation / purpose
20-
21-
If a visitor arrives at a website that uses the Nuxt UTM module and a UTM parameter is present in the URL, the module will collect the UTM parameters along with additional information. This information is saved in the device's local storage within the user's browser. This is especially useful for static generated websites that can later integrate with the backend to save this data. For example, when a visitor or lead submits a form, you can send this data alongside the form data. Later, this information can be especially useful for evaluating the effectiveness of ad campaigns and assessing their impact.
12+
<!-- - [🏀 Online playground](https://stackblitz.com/github/your-org/my-module?file=playground%2Fapp.vue) -->
13+
<!-- - [📖 &nbsp;Documentation](https://example.com) -->
2214

2315
## Features
2416

25-
- **📍 UTM Tracking**: Easily capture UTM parameters to gain insights into traffic sources and campaign performance.
26-
- **🔍 Intelligent De-duplication**: Smart recognition of page refreshes to avoid data duplication, ensuring each visit is uniquely accounted for.
27-
- **🔗 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.
17+
- ✅ Automatically capture UTM parameters from URL query strings
18+
- ✅ Store UTM data persistently in localStorage with session tracking
19+
- ✅ Support for Google Ads parameters (gclid, gad_source)
20+
- ✅ Additional context (referrer, user agent, screen size, landing page)
21+
- ✅ TypeScript support
22+
- ✅ **Enable/disable tracking via configuration or runtime**
23+
- ✅ Composable API for easy access
2824

2925
## Quick Setup
3026

3127
1. Add `nuxt-utm` dependency to your project
3228

3329
```bash
34-
# Using pnpm
35-
pnpm add -D nuxt-utm
30+
# Using npm
31+
npm install --save-dev nuxt-utm
3632

3733
# Using yarn
3834
yarn add --dev nuxt-utm
3935

40-
# Using npm
41-
npm install --save-dev nuxt-utm
36+
# Using pnpm
37+
pnpm add -D nuxt-utm
4238
```
4339

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

4642
```js
4743
export default defineNuxtConfig({
4844
modules: ['nuxt-utm'],
45+
utm: {
46+
enabled: true, // Set to false to disable capturing UTM parameters
47+
},
4948
})
5049
```
5150

52-
That's it! You can now use Nuxt UTM in your Nuxt app ✨
51+
## Configuration
52+
53+
### Module Options
54+
55+
| Option | Type | Default | Description |
56+
|--------|------|---------|-------------|
57+
| `enabled` | `boolean` | `true` | Enable or disable UTM parameter tracking |
58+
59+
Example configurations:
60+
61+
```js
62+
// Disable UTM tracking completely
63+
export default defineNuxtConfig({
64+
modules: ['nuxt-utm'],
65+
utm: {
66+
enabled: false,
67+
},
68+
})
69+
70+
// Enable UTM tracking (default behavior)
71+
export default defineNuxtConfig({
72+
modules: ['nuxt-utm'],
73+
utm: {
74+
enabled: true,
75+
},
76+
})
77+
```
5378

5479
## Usage
5580

81+
### Basic Usage
82+
5683
You can use `useNuxtUTM` composable to access the UTM object:
5784

5885
```vue
5986
<script setup>
60-
const utm = useNuxtUTM()
87+
const { data, enabled, clear } = useNuxtUTM()
88+
89+
// Access UTM data
90+
console.log(data.value) // Array of UTM data objects
91+
92+
// Check if tracking is enabled
93+
console.log(enabled.value) // boolean
94+
95+
// Disable tracking at runtime (e.g., when user opts out)
96+
enabled.value = false
97+
98+
// Re-enable tracking
99+
enabled.value = true
100+
101+
// Clear all UTM data
102+
clear()
61103
</script>
62104
```
63105

64-
> Remember: You don't need to import the composable because nuxt imports it automatically.
106+
### Alternative Access via Nuxt App
65107

66-
Alternatively, you can get the UTM information through the Nuxt App with the following instructions:
108+
Alternatively, you can get the UTM information through the Nuxt App:
67109

68110
```vue
69111
<script setup>
70112
import { useNuxtApp } from 'nuxt/app'
71113
const { $utm } = useNuxtApp()
114+
const { data, enabled, clear } = $utm
115+
116+
// Disable tracking
117+
$utm.enabled.value = false
118+
119+
// Clear all data
120+
$utm.clear()
72121
</script>
73122
```
74123

75-
Regardless of the option you choose to use the module, the `utm' object 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
124+
### Runtime Tracking Control
125+
126+
The module provides runtime control over UTM tracking, which is useful for implementing user consent flows:
127+
128+
```vue
129+
<template>
130+
<div>
131+
<h1>Privacy Settings</h1>
132+
<label>
133+
<input
134+
type="checkbox"
135+
v-model="trackingEnabled"
136+
@change="handleTrackingToggle"
137+
>
138+
Allow UTM tracking
139+
</label>
140+
141+
<div v-if="trackingEnabled">
142+
<h2>Current UTM Data</h2>
143+
<pre>{{ utmData }}</pre>
144+
</div>
145+
</div>
146+
</template>
147+
148+
<script setup>
149+
const { data: utmData, enabled, clear } = useNuxtUTM()
150+
151+
const trackingEnabled = ref(enabled.value)
152+
153+
const handleTrackingToggle = () => {
154+
enabled.value = trackingEnabled.value
155+
156+
// Optionally clear existing data when disabled
157+
if (!trackingEnabled.value) {
158+
clear()
159+
}
160+
}
161+
</script>
162+
```
163+
164+
## Data Structure
165+
166+
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:
76167

77168
```json
78169
[
@@ -104,7 +195,60 @@ Regardless of the option you choose to use the module, the `utm' object will con
104195
]
105196
```
106197

107-
In the `$utm` array, each entry provides a `timestamp` indicating when the UTM parameters were collected, the `utmParams` object containing the UTM parameters, `additionalInfo` object with more context about the visit, and a `sessionId` to differentiate visits in different sessions.
198+
In the `data` array, each entry provides:
199+
- **timestamp**: When the UTM parameters were collected
200+
- **utmParams**: The UTM parameters from the URL
201+
- **additionalInfo**: Context about the visit (referrer, user agent, etc.)
202+
- **sessionId**: Unique identifier for the user session
203+
- **gclidParams**: Google Ads click identifier and source (if present)
204+
205+
## Common Use Cases
206+
207+
### GDPR/Privacy Compliance
208+
209+
```vue
210+
<script setup>
211+
const { enabled, clear } = useNuxtUTM()
212+
213+
// Check user's consent from your privacy management system
214+
const hasConsent = await checkUserConsent()
215+
enabled.value = hasConsent
216+
217+
// Listen for consent changes
218+
onConsentChange((newConsent) => {
219+
enabled.value = newConsent
220+
if (!newConsent) {
221+
// Clear existing UTM data using the built-in clear function
222+
clear()
223+
}
224+
})
225+
</script>
226+
```
227+
228+
### Conditional Tracking by Environment
229+
230+
```js
231+
// nuxt.config.ts
232+
export default defineNuxtConfig({
233+
modules: ['nuxt-utm'],
234+
utm: {
235+
// Only enable in production
236+
enabled: process.env.NODE_ENV === 'production',
237+
},
238+
})
239+
```
240+
241+
### A/B Testing with Tracking Control
242+
243+
```vue
244+
<script setup>
245+
const { enabled } = useNuxtUTM()
246+
247+
// Enable tracking only for certain user segments
248+
const userSegment = await getUserSegment()
249+
enabled.value = userSegment === 'tracking-enabled'
250+
</script>
251+
```
108252

109253
## Development
110254

@@ -160,5 +304,5 @@ Do you want to contribute to this project? Please take a look at our [contributi
160304

161305
---
162306

163-
<img src="https://www.stackbuilders.com/media/images/Sb-supports.original.png" alt="Stack Builders" width="50%"></img>
307+
<img src="https://www.stackbuilders.com/media/images/Sb-supports.original.png" alt="Stack Builders" width="50%"></img>
164308
[Check out our libraries](https://github.com/stackbuilders/) | [Join our team](https://www.stackbuilders.com/join-us/)

‎package.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,7 @@
7474
"prettier": "^3.5.3",
7575
"typescript": "~5.8.3",
7676
"vitest": "^3.1.2",
77-
"vue-tsc": "^2.2.10"
77+
"vue-tsc": "^2.2.10",
78+
"defu": "^6.1.5"
7879
}
7980
}

‎playground/app.vue‎

Lines changed: 67 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,75 @@
11
<template>
2-
<div>Nuxt 3 UTM module playground!</div>
3-
<pre>{{ utm }}</pre>
2+
<div style="padding: 20px; font-family: sans-serif;">
3+
<h1>Nuxt 3 UTM Module Playground!</h1>
4+
5+
<div style="margin: 20px 0; padding: 15px; background: #f5f5f5; border-radius: 8px;">
6+
<h2>UTM Tracking Controls</h2>
7+
<label style="display: flex; align-items: center; gap: 10px; margin: 10px 0;">
8+
<input
9+
type="checkbox"
10+
v-model="isTrackingEnabled"
11+
@change="toggleTracking"
12+
>
13+
<span>Enable UTM Tracking</span>
14+
</label>
15+
<p><strong>Status:</strong> {{ isTrackingEnabled ? 'Enabled' : 'Disabled' }}</p>
16+
17+
<button
18+
@click="clearData"
19+
style="margin: 10px 5px 0 0; padding: 8px 16px; background: #dc3545; color: white; border: none; border-radius: 4px; cursor: pointer;">
20+
Clear UTM Data
21+
</button>
22+
23+
<button
24+
@click="addTestData"
25+
style="margin: 10px 0 0 0; padding: 8px 16px; background: #007bff; color: white; border: none; border-radius: 4px; cursor: pointer;"
26+
:disabled="!isTrackingEnabled"
27+
>
28+
Add Test UTM Data
29+
</button>
30+
</div>
31+
32+
<div style="margin: 20px 0;">
33+
<h2>Current UTM Data ({{ utm.data.length }} entries)</h2>
34+
<pre style="background: #f8f9fa; padding: 15px; border-radius: 8px; overflow-x: auto; font-size: 12px;">{{ JSON.stringify(utm.data.value, null, 2) }}</pre>
35+
</div>
36+
37+
<div style="margin: 20px 0; padding: 15px; background: #e7f3ff; border-radius: 8px;">
38+
<h3>Test URLs</h3>
39+
<p>Try visiting these URLs to test UTM tracking:</p>
40+
<ul>
41+
<li><a href="/?utm_source=google&amp;utm_medium=cpc&amp;utm_campaign=test">Google CPC Campaign</a></li>
42+
<li><a href="/?utm_source=facebook&amp;utm_medium=social&amp;utm_campaign=promo&amp;utm_content=video">Facebook Social Promo</a></li>
43+
<li><a href="/?utm_source=newsletter&amp;utm_medium=email&amp;utm_campaign=weekly&amp;gclid=test123">Newsletter with GCLID</a></li>
44+
</ul>
45+
</div>
46+
</div>
447
</template>
548

649
<script setup>
50+
import { ref, watch } from 'vue'
751
import { useNuxtUTM } from '#imports'
852
953
const utm = useNuxtUTM()
54+
const isTrackingEnabled = ref(utm.enabled.value)
55+
56+
const toggleTracking = () => {
57+
utm.enabled.value = isTrackingEnabled.value
58+
}
59+
60+
const clearData = () => {
61+
utm.clear()
62+
}
63+
64+
const addTestData = () => {
65+
if (utm.enabled.value) {
66+
// Simulate a UTM visit by navigating to a test URL
67+
window.location.href = '/?utm_source=manual_test&utm_medium=playground&utm_campaign=demo'
68+
}
69+
}
70+
71+
// Watch for changes in UTM enabled state
72+
watch(() => utm.enabled.value, (newValue) => {
73+
isTrackingEnabled.value = newValue
74+
})
1075
</script>

‎src/module.ts‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,23 @@
11
import { defineNuxtModule, addPlugin, addImports, createResolver } from '@nuxt/kit'
2+
import defu from 'defu'
23

34
// Module options TypeScript interface definition
4-
/* eslint-disable @typescript-eslint/no-empty-object-type */
5-
export interface ModuleOptions {}
6-
/* eslint-enable @typescript-eslint/no-empty-object-type */
5+
export interface ModuleOptions {
6+
enabled?: boolean
7+
}
78

89
export default defineNuxtModule<ModuleOptions>({
910
meta: {
1011
name: 'utm',
1112
configKey: 'utm',
1213
},
1314
// Default configuration options of the Nuxt module
14-
defaults: {},
15-
setup() {
15+
defaults: { enabled: true },
16+
setup(options, nuxt) {
17+
nuxt.options.runtimeConfig.public.utm = defu(nuxt.options.runtimeConfig.public.utm || {}, {
18+
enabled: options.enabled,
19+
})
20+
1621
const resolver = createResolver(import.meta.url)
1722

1823
// Do not add the extension since the `.ts` will be transpiled to `.mjs` after `npm run prepack`

0 commit comments

Comments
 (0)