utmrescue.js

UtmRescue is a lightweight browser library for capturing, storing, and retrieving UTM parameters in browser environments. It maintains first-party attribution while allowing for the addition of new UTM parameters.

Features

Extracts UTM parameters from URLs
Stores UTM parameters in cookies on the parent domain
Maintains first-party attribution (doesn't overwrite existing UTM parameters)
Case-insensitive parameter handling
Works across subdomains
Easy to integrate into any web project

Installation

You can install UtmRescue via npm:

npm i utmrescue.js

Or include it directly in your HTML using a CDN:

<script src="https://unpkg.com/utmrescue.js/dist/utmrescue.min.js"></script>

Usage

In a TypeScript/JavaScript project

import UtmRescue from "utmrescue";

// Initialize UtmRescue
const utmRescue = new UtmRescue();

// Get UTM parameters
const utmParams = utmRescue.getUtmParams();
console.log(utmParams);

In an HTML file

<!doctype html>
<html lang="en">
  <head>
    <script src="https://unpkg.com/utmrescue.js/dist/utmrescue.min.js"></script>
    <script>
      document.addEventListener("DOMContentLoaded", function () {
        // Initialize UtmRescue
        var utmRescue = new UtmRescue();

        // Get UTM parameters
        var utmParams = utmRescue.getUtmParams();
      });
    </script>
  </head>
  <body>
    <!-- Your content here -->
  </body>
</html>

How It Works

When initialized, UtmRescue checks the current URL for UTM parameters.
It also checks for previously stored UTM parameters in cookies.
If a UTM parameter exists in the URL and is not already stored, it's captured.
If a UTM parameter is already stored, the stored value is kept (maintaining first-party attribution).
The combined set of UTM parameters (stored + new) is saved in a cookie on the parent domain.
You can retrieve the current set of UTM parameters at any time using getUtmParams() or accessing the cookie __utmrescue_data which should available to every domain underneath and including the parent.

API

Constructor

new UtmRescue();

Creates a new instance of UtmRescue, automatically extracting and storing UTM parameters.

Methods

getUtmParams()

utmRescue.getUtmParams(): { [key: string]: string }

Returns an object containing the current UTM parameters. This includes both stored parameters and any new parameters from the current URL.

Supported UTM Parameters

UtmRescue supports the following UTM parameters:

utm_source
utm_medium
utm_campaign
utm_term
utm_content

All parameters are stored and returned in lowercase for consistency.

Browser Compatibility

UtmRescue is compatible with all modern browsers that support ES5 and cookies.

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

If you encounter any problems or have any questions, please open an issue on the GitHub repository.

justinsoong / utmrescue.js