chore: Update the README

README.md

@@ -1,90 +1,88 @@
-# Repository Name
-
-Quick summary about the repository or library. What is
-
-## How it works / motivation / purpose
-
-Promote the library/project explaining how it works. You can also add the motiviation for writing the library or explain its porpuse in this section.
-
-## Install
-
-Its a good idea to explain/show how to install the library/project. You can try to use badges of the package registry (NPM, MyPy, Stackage, Maven, etc) to always display the latest version so this section is easier to maintain.
-
-## Usage
-
-This section can show a quick start of the library/project. This helps developers quickly understand how the software is expected to be used, giving a great entry point to project as well. In this section you can also write the documentation for the end-user, or add a link to the docs if they are in some external source (the wiki, a dedicated page, the `docs/` folder, etc.).
-
-<!-- Add any other required sections here as needed -->
-
-## License
-
-<!-- NOTE: If you need a different type of licence, please check with the OSS team before changing it -->
-
-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.
-
----
-
-<img src="https://www.stackbuilders.com/media/images/Sb-supports.original.png" alt="Stack Builders" width="50%"></img>
-[Check out our libraries](https://github.com/stackbuilders/) | [Join our team](https://www.stackbuilders.com/join-us/)
-
-<!--
-Get your module up and running quickly.
-
-Find and replace all on all files (CMD+SHIFT+F):
-- Name: My Module
-- Package name: my-module
-- Description: My new Nuxt module
--->
-
-# My Module
+# 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]
 
-My new Nuxt module for doing amazing things.
+A Nuxt 3 module for tracking UTM parameters.
 
 - [✨ &nbsp;Release Notes](/CHANGELOG.md)
   <!-- - [🏀 Online playground](https://stackblitz.com/github/stackbuilders/nuxt-utm?file=playground%2Fapp.vue) -->
   <!-- - [📖 &nbsp;Documentation](https://example.com) -->
 
-## Features
+## 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.
 
-<!-- Highlight some of the features your module provide here -->
+## Features
 
-- ⛰ &nbsp;Foo
-- 🚠 &nbsp;Bar
-- 🌲 &nbsp;Baz
+- **📍 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, browser language, and screen resolution. This enriched data empowers your marketing strategies with a deeper understanding of campaign impact.
 
 ## Quick Setup
 
-1. Add `my-module` dependency to your project
+1. Add `nuxt-utm` dependency to your project
 
 ```bash
 # Using pnpm
-pnpm add -D my-module
+pnpm add -D nuxt-utm
 
 # Using yarn
-yarn add --dev my-module
+yarn add --dev nuxt-utm
 
 # Using npm
-npm install --save-dev my-module
+npm install --save-dev nuxt-utm
 ```
 
-2. Add `my-module` to the `modules` section of `nuxt.config.ts`
+2. Add `nuxt-utm` to the `modules` section of `nuxt.config.ts`
 
 ```js
 export default defineNuxtConfig({
-  modules: ["my-module"],
+  modules: ["nuxt-utm"],
 });
 ```
 
-That's it! You can now use My Module in your Nuxt app ✨
+That's it! You can now use Nuxt UTM in your Nuxt app ✨
+
+## Usage
+
+```js
+<script setup>
+  import {useNuxtApp} from "nuxt/app"; const {$utm} = useNuxtApp();
+</script>
+```
+
+The `$utm` 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
+      screen: {
+        width: 1728,
+        height: 1117,
+      },
+    },
+    sessionId: "beai1gx7dg",
+  }, // 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
 
@@ -104,6 +102,9 @@ npm run dev:build
 # Run ESLint
 npm run lint
 
+# Install Playwright Browsers
+npx playwright install --with-deps
+
 # Run Vitest
 npm run test
 npm run test:watch
@@ -112,13 +113,28 @@ npm run test:watch
 npm run release
 ```
 
+## License
+
+<!-- NOTE: If you need a different type of licence, please check with the OSS team before changing it -->
+
+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.
+
 <!-- Badges -->
 
-[npm-version-src]: https://img.shields.io/npm/v/my-module/latest.svg?style=flat&colorA=18181B&colorB=28CF8D
-[npm-version-href]: https://npmjs.com/package/my-module
-[npm-downloads-src]: https://img.shields.io/npm/dm/my-module.svg?style=flat&colorA=18181B&colorB=28CF8D
-[npm-downloads-href]: https://npmjs.com/package/my-module
-[license-src]: https://img.shields.io/npm/l/my-module.svg?style=flat&colorA=18181B&colorB=28CF8D
-[license-href]: https://npmjs.com/package/my-module
+[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
+
+---
+
+<img src="https://www.stackbuilders.com/media/images/Sb-supports.original.png" alt="Stack Builders" width="50%"></img>
+[Check out our libraries](https://github.com/stackbuilders/) | [Join our team](https://www.stackbuilders.com/join-us/)

playground/package.json

@@ -1,6 +1,6 @@
 {
   "private": true,
-  "name": "my-module-playground",
+  "name": "nuxt-utm-playground",
   "type": "module",
   "scripts": {
     "dev": "nuxi dev",