# UTM Tracking System Documentation

**Last Updated:** 2026-01-10

Complete documentation for the comprehensive UTM parameter tracking system used across all pages.

## Overview

The UTM tracking system (`v2/js/utm-tracking.js`) provides comprehensive UTM parameter extraction, cookie management, Google Ads correction, traffic source detection, and proper attribution tracking for HubSpot form submissions.

## File Location

- **Source:** `v2/js/utm-tracking.js`
- **Minified:** `v2/js/utm-tracking.min.js`
- **Global Class:** `window.UTMTracker`
- **Global Object:** `window.utmTracking` (legacy access)

## Features

### 1. UTM Parameter Extraction

- Extracts all standard UTM parameters from URL
- Handles duplicate parameters with smart selection
- Supports Google Ads `hsa_*` parameters
- Cookie-based persistence (30 days)
- Fallback to cookies when URL parameters missing

### 2. Google Ads UTM Correction

- Automatically corrects `google` → `adwords` for paid traffic
- Corrects `utm_medium` to `ppc` for Google Ads
- Preserves original parameters for debugging
- Handles `gclid` parameter detection

### 3. Traffic Source Detection

- Detects paid traffic sources (Google Ads, Meta, LinkedIn)
- Detects organic traffic sources (Google, Bing)
- Detects referral traffic (ChatGPT, Perplexity, etc.)
- Detects direct traffic
- Non-UTM traffic classification

### 4. Lead Source Attribution

- Automatic lead source detection based on UTM parameters
- Maps UTM combinations to lead source values
- Supports custom lead source values
- Referrer-based validation

### 5. Cookie Management

- Stores UTM parameters in cookies (30 days)
- Clears conflicting cookies when traffic source changes
- Supports cookie fallback for multi-page sessions
- Handles cookie quota exceeded gracefully

## API Reference

### Initialization

The tracker automatically initializes on page load:

```javascript
// Automatic initialization
const tracker = new UTMTracker();
```

### Methods

#### `getUTMDataForAPI()`

Get UTM data formatted for API submission.

**Returns:** `Object` - UTM data object

**Example:**

```javascript
const utmData = window.utmTracker.getUTMDataForAPI();
// Use in API call
```

**Returned Object:**

```javascript
{
    utm_source: string,
    utm_medium: string,
    utm_campaign: string,
    utm_term: string,
    utm_content: string,
    gclid: string,
    leadSource: string,
    partner: string,
    signuptype: string,
    page_url: string,
    referrer: string,
    hubspotutk: string
}
```

#### `getAllUTMData()`

Get all UTM data including processed values.

**Returns:** `Object` - Complete UTM data object

**Example:**

```javascript
const allData = window.utmTracker.getAllUTMData();
```

#### `addUTMToForm(form)`

Add UTM parameters to form submission.

**Parameters:**

- `form` (HTMLElement): Form element

**Example:**

```javascript
const form = document.getElementById("my-form");
window.utmTracker.addUTMToForm(form);
```

## UTM Parameter Processing

### Parameter Priority

1. **URL Parameters** (highest priority)
2. **Cookies** (fallback)
3. **Referrer Detection** (fallback)
4. **Default Values** (lowest priority)

### Google Ads Detection

The system detects Google Ads traffic using multiple indicators:

- `gclid` parameter present
- `utm_source=google` or `utm_source=adwords`
- `utm_medium=cpc` or `utm_medium=ppc`
- `hsa_src=g` parameter

**Correction Applied:**

- `utm_source`: `google` → `adwords`
- `utm_medium`: `cpc` → `ppc` (if needed)
- `leadSource`: Set to `Paid Search` or `Google`

### Meta Traffic Detection

Detects Meta (Facebook/Instagram) paid traffic:

- `utm_source=fb` or `utm_source=facebook` or `utm_source=instagram`
- `utm_medium=paid` or `utm_medium=cpc`
- Meta campaign ID pattern (`utm_campaign` starts with `120`)

**Correction Applied:**

- `utm_source`: Normalized to `fb` for paid traffic
- `leadSource`: Set to `meta`

### Referral Traffic Detection

Detects referral traffic from AI tools and other sources:

- Domain patterns in `utm_source` (contains `.`)
- Known AI referral patterns (ChatGPT, Perplexity, Claude, etc.)
- `utm_medium=referral`

**Classification:**

- `utm_source`: Preserved or set to domain name
- `utm_medium`: Set to `referral`
- `leadSource`: Set to `referral`

## Cookie Management

### Cookie Names

- `utm_source`
- `utm_medium`
- `utm_campaign`
- `utm_term`
- `utm_content`
- `gclid`
- `leadSource`
- `partner`
- `signuptype`

### Cookie Expiration

- **Default:** 30 days
- **Configurable:** Via `setUTMCookies()` method

### Cookie Cleanup

- Clears conflicting cookies when traffic source changes
- Prevents cookie contamination across sessions
- Handles cookie quota exceeded gracefully

## Lead Source Mapping

### Standard Mappings

| UTM Combination                             | Lead Source           |
| ------------------------------------------- | --------------------- |
| `utm_source=google` + `utm_medium=organic`  | `Organic Search`      |
| `utm_source=adwords` + `gclid` present      | `Paid Search`         |
| `utm_source=fb` + `utm_medium=paid`         | `meta`                |
| `utm_source=facebook` + `utm_medium=social` | `Organic Social`      |
| `utm_medium=email`                          | `Email Marketing`     |
| `utm_medium=affiliate`                      | `Affiliate`           |
| `utm_medium=referral`                       | `referral`            |
| `utm_medium=display`                        | `Display Advertising` |

### Custom Lead Sources

- `partner` parameter → Custom partner lead source
- `signuptype` parameter → Custom signup type
- Referrer-based detection → Custom lead source

## Integration Pattern

### 1. Load Script

```html
<script src="/v2/js/utm-tracking.min.js?v=<?php echo filemtime(__DIR__ . '/../js/utm-tracking.min.js'); ?>"></script>
```

### 2. Access UTM Data

```javascript
// Via tracker instance
const utmData = window.utmTracker.getUTMDataForAPI();

// Via legacy global object
const utmData = window.utmTracking;
```

### 3. Use in Form Submission

```javascript
// Automatic form enhancement
window.utmTracker.addUTMToForm(document.getElementById("my-form"));

// Manual data inclusion
const formData = {
  email: email,
  name: name,
  ...window.utmTracker.getUTMDataForAPI(),
};
```

## Browser Compatibility

- Modern browsers (Chrome, Firefox, Safari, Edge)
- Requires `URLSearchParams` support (with legacy fallback)
- Requires `document.cookie` support
- Gracefully handles missing features

## Related Documentation

- [Email Modal Utils](EMAIL_MODAL_UTILS.md) - Uses UTM tracking
- [GTM Form Tracking](GTM_FORM_TRACKING.md) - Uses UTM tracking
- [HubSpot API Reference](../apis/HUBSPOT_API_REFERENCE.md) - UTM parameter usage