Unified Parameter Handler

Handles URL parameters (like UTM, gclid, fbclid) and cookies, reading their values and storing them into designated hidden input fields within your web forms.

This library helps ensure that tracking parameters captured on landing pages are correctly passed along with form submissions.

Features

• Reads specified URL query parameters.
• Reads specified browser cookies.
• Persists values (like UTMs) in localStorage to retain them across page navigations.
• Supports looking in URL first, then falling back to cookies, then to persisted storage.
• Sets/updates cookies based on found URL parameters (configurable expiry).
• Populates hidden HTML input fields with the found values.
• Handles asynchronous cookie setting with configurable retries.
• Supports custom formatting functions for values before storage.
• Captures User Agent and Client IP address.
• Comes with default configurations for common parameters (fbclid, fbp, gclid, wbraid, gbraid, UTMs, User Agent, Client IP).
• Allows complete configuration customization.

Installation

1. Get the code:

   • Clone the repository or download the unified-handler-dist.zip file from the GitHub Releases page. This zip file contains the built library (dist/), the README, and the license.
   • Alternatively, if using npm/yarn, you can potentially install it as a package (if published).

2. Build the project (if cloning): If you cloned the repository, run the build command specified in package.json (e.g., npm run build or yarn build). This will generate the distributable file (e.g., dist/unified-handler.min.js).

   # Using npm
   npm install
   npm run build
   
   # Using yarn
   yarn install
   yarn build

3. Include the script: Add the generated script file to your HTML page, preferably before the closing </body> tag.

   <script src="path/to/dist/unified-handler.js"></script>

Basic Usage

1. Add Hidden Fields: Ensure your HTML form includes hidden input fields with name attributes matching the targetInputName specified in your configuration (either default or custom).

   <form action="/submit" method="post">
     <!-- Other form fields -->
     <input type="hidden" name="custom FBC">
     <input type="hidden" name="custom FBP">
     <input type="hidden" name="custom GCLID">
     <input type="hidden" name="custom UTM_SOURCE">
     <!-- Add other necessary hidden fields -->
     <input type="hidden" name="userAgent"> 
     <input type="hidden" name="clientIp">
   
     <button type="submit">Submit</button>
   </form>

2. Initialize the Handler: Call the initialization function. If you want to use the default configuration, call it without arguments. To use a custom configuration, pass your configuration array.

   <script src="path/to/dist/unified-handler.js"></script>
   <script>
     // Initialize with default settings
     window.UnifiedParamHandler.init();
   
     // Or, initialize with custom settings (assuming myCustomHandlers is defined)
     // const myCustomHandlers = [ /* ... your config ... */ ];
     // window.UnifiedParamHandler.init(myCustomHandlers);
   </script>

Configuration

For detailed configuration options, default settings, and advanced examples, please see the Configuration Guide.

Development

• Install dependencies: npm install or yarn install
• Build for production: npm run build or yarn build
• Build for development: npm run build:dev or yarn build:dev
• Watch for changes: npm run watch or yarn watch
• Run tests: npm test or yarn test
• Lint code: npm run lint or yarn lint
• Format code: npm run format or yarn format

License

This project is licensed under the GNU General Public License v3.0 or later. See the COPYING file for details.