https://github.com/stackbuilders/nuxt-utm
Nuxt 3 module for capturing and tracking UTM parameters from URLs, with additional contextual data collection.
https://github.com/stackbuilders/nuxt-utm
nuxt nuxt-module nuxt-modules nuxt3 utm utm-parameters
Last synced: 9 months ago
JSON representation
Nuxt 3 module for capturing and tracking UTM parameters from URLs, with additional contextual data collection.
- Host: GitHub
- URL: https://github.com/stackbuilders/nuxt-utm
- Owner: stackbuilders
- License: mit
- Created: 2023-10-18T15:59:15.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-03-19T20:02:33.000Z (10 months ago)
- Last Synced: 2025-04-21T06:51:48.434Z (9 months ago)
- Topics: nuxt, nuxt-module, nuxt-modules, nuxt3, utm, utm-parameters
- Language: TypeScript
- Homepage:
- Size: 1.02 MB
- Stars: 4
- Watchers: 16
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: docs/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: docs/CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Nuxt UTM
[](https://github.com/stackbuilders/nuxt-utm/actions/workflows/main.yml)
[![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 module for tracking UTM parameters.
- [✨ Release Notes](/CHANGELOG.md)
## 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
You can use `useNuxtUTM` composable to access the UTM object:
```vue
const utm = useNuxtUTM();
```
> Remember: You don't need to import the composable because nuxt imports it automatically.
Alternatively, you can get the UTM information through the Nuxt App with the following instructions:
```vue
import { useNuxtApp } from "nuxt/app";
const { $utm } = useNuxtApp();
```
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
```js
[
{
timestamp: "2023-11-02T10:11:17.219Z", // Timestamp of the URL visit
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", // Referrer URL
userAgent: "User-Agent String", // User-Agent string of the browser
language: "en-GB", // Language setting of the browser
landingPageUrl: "http://landingpage.url", // The URL of the page the user landed on
screen: {
width: 1728,
height: 1117,
},
},
sessionId: "beai1gx7dg",
gclidParams: {
gclid: "CjklsefawEFRfeafads",
gad_source: "1",
},
}, // the first item in this array is the most recent
// ... old items
];
```
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.
## 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](/docs/RELEASING.md).
## License
MIT, see [the LICENSE file](LICENSE).
## Contributing
Do you want to contribute to this project? Please take a look at our [contributing guideline](/docs/CONTRIBUTING.md) 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](https://github.com/stackbuilders/) | [Join our team](https://www.stackbuilders.com/join-us/)