Nuxt UTM

[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[![License][license-src]][license-href]
[![Nuxt][nuxt-src]][nuxt-href]

Built in collaboration with The Durst Organization

---

A Nuxt 3/4 module for tracking UTM parameters.

- ✨  Release Notes

How it works / motivation / purpose

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.

Features

- 📍 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.

Quick Setup

1. Add nuxt-utm dependency to your project

``bash


Using pnpm

pnpm add -D nuxt-utm

Using yarn

yarn add --dev nuxt-utm

Using npm

npm install --save-dev nuxt-utm
`

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

`js
export default defineNuxtConfig({
modules: ['nuxt-utm'],
})
`

That's it! You can now use Nuxt UTM in your Nuxt app ✨

Usage

$3

You can configure the module by passing options in your nuxt.config.ts:

`js
export default defineNuxtConfig({
modules: ['nuxt-utm'],
utm: {
trackingEnabled: true, // defaults to true - initial tracking state
},
})
`

#### Options

- trackingEnabled: Boolean (default: true) - Sets the initial state for UTM tracking. This can be changed at runtime.

$3

The module provides runtime control over tracking, perfect for implementing cookie consent banners or user privacy preferences.

#### Using the Composable

`vue

`

#### Example: Cookie Banner Integration

`vue



`

#### Privacy Controls

`vue



`

$3

You can use useNuxtUTM composable to access the UTM data:

`vue

`

> Remember: You don't need to import the composable because Nuxt imports it automatically.

$3

The data property contains an array of UTM parameters collected. Each element in the array represents a set of UTM parameters collected from a URL visit, and is structured as follows

`json
[
{
"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"
}
}
]
`

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.

$3

- Runtime Control: Enable/disable tracking dynamically based on user consent
- Privacy Friendly: Respects user preferences and provides clear data management
- Persistent Preferences: Tracking preferences are saved and persist across sessions
- Data Clearing: Ability to completely remove all collected data
- Session Management: Automatically manages sessions to avoid duplicate tracking

Development

`bash


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.

[npm-version-src]: https://img.shields.io/npm/v/nuxt-utm/latest.svg?style=flat&colorA=18181B&colorB=28CF8D
[npm-version-href]: https://npmjs.com/package/nuxt-utm
[npm-downloads-src]: https://img.shields.io/npm/dm/nuxt-utm.svg?style=flat&colorA=18181B&colorB=28CF8D
[npm-downloads-href]: https://npmjs.com/package/nuxt-utm
[license-src]: https://img.shields.io/npm/l/nuxt-utm.svg?style=flat&colorA=18181B&colorB=28CF8D
[license-href]: https://npmjs.com/package/nuxt-utm
[nuxt-src]: https://img.shields.io/badge/Nuxt-18181B?logo=nuxt.js
[nuxt-href]: https://nuxt.com

---

Check out our libraries | Join our team