@bernierllc/validators-tracking-params

Tracking parameter validation - UTM/PII leakage policy enforcement for privacy compliance.

Overview

A primitive validator package that provides comprehensive validation of tracking parameters in URLs, ensuring privacy compliance (GDPR, CCPA) and marketing attribution best practices. Detects personally identifiable information (PII) in URL parameters, validates UTM parameter standards, and checks for unauthorized third-party trackers.

Installation

npm install @bernierllc/validators-tracking-params

Features

• PII Detection - Identifies emails, SSNs, phone numbers, credit cards, and custom patterns in URL parameters
• UTM Parameter Validation - Ensures UTM tracking follows standard naming conventions
• Third-Party Tracker Detection - Detects unauthorized tracking pixels from major ad networks
• Tracking Parameter Standards - Validates organizational tracking parameter policies
• UTM Attribution Completeness - Warns when required UTM parameters are missing

Usage

Basic Validation

import { noPIIInUrlParams, validUtmParams } from '@bernierllc/validators-tracking-params';
import { createRuleContext } from '@bernierllc/validators-core';

// Create a context for validation
const problems: Problem[] = [];
const ctx = createRuleContext(
  'no-pii-in-url-params',
  {},
  mockUtils,
  {},
  (p) => problems.push(p)
);

// Validate content for PII in URLs
const rule = noPIIInUrlParams.create(ctx as any);
const content = 'Visit https://[email protected]';
rule(content);

// Check for problems
console.log(problems); // Will contain detected PII violations

Custom PII Patterns

import { noPIIInUrlParams } from '@bernierllc/validators-tracking-params';

const customPattern = /CUSTOM-\d{3}-[A-Z]{3}/;
const ctx = createRuleContext(
  'no-pii-in-url-params',
  { piiPatterns: [customPattern] },
  mockUtils,
  {},
  (p) => problems.push(p)
);

const rule = noPIIInUrlParams.create(ctx as any);
rule('Visit https://example.com?id=CUSTOM-123-ABC');

UTM Parameter Validation

import { validUtmParams } from '@bernierllc/validators-tracking-params';

const ctx = createRuleContext(
  'valid-utm-params',
  { allowedUtmParams: ['utm_source', 'utm_medium', 'utm_campaign', 'utm_custom'] },
  mockUtils,
  {},
  (p) => problems.push(p)
);

const rule = validUtmParams.create(ctx as any);
rule('Visit https://example.com?utm_source=google&utm_custom=value');

Third-Party Tracker Detection

import { noUnauthorizedTrackers } from '@bernierllc/validators-tracking-params';

const ctx = createRuleContext(
  'no-unauthorized-trackers',
  {
    allowedDomains: ['google-analytics.com'],
    allowThirdPartyTrackers: false
  },
  mockUtils,
  {},
  (p) => problems.push(p)
);

const rule = noUnauthorizedTrackers.create(ctx as any);
rule('Tracking via https://www.google-analytics.com/collect?v=1');

Strict Tracking Parameter Standards

import { trackingParamStandards } from '@bernierllc/validators-tracking-params';

const ctx = createRuleContext(
  'tracking-param-standards',
  {
    strictMode: true,
    allowedTrackingParams: ['fbclid', 'gclid', 'custom_tracking']
  },
  mockUtils,
  {},
  (p) => problems.push(p)
);

const rule = trackingParamStandards.create(ctx as any);
rule('Visit https://example.com?custom_tracking=test');

API Reference

Rules

noPIIInUrlParams

Detects personally identifiable information in URL parameters.

Options:

• piiPatterns?: RegExp[] - Custom PII detection patterns

Detects:

• Email addresses
• Social Security Numbers (SSN)
• Phone numbers
• Credit card numbers
• IPv4 addresses
• Custom patterns

validUtmParams

Validates UTM tracking parameters follow standard naming conventions.

Options:

• allowedUtmParams?: string[] - Allowed UTM parameter names (default: standard UTM params)

Standard UTM Parameters:

• utm_source
• utm_medium
• utm_campaign
• utm_term
• utm_content
• utm_id

noUnauthorizedTrackers

Detects tracking pixels and parameters from unauthorized third-party services.

Options:

• allowThirdPartyTrackers?: boolean - Allow all third-party trackers (default: false)
• allowedDomains?: string[] - Allowlist of authorized tracking domains

Detected Vendors:

• Google Analytics
• DoubleClick
• Facebook
• LinkedIn
• Twitter

trackingParamStandards

Validates tracking parameters against organizational standards.

Options:

• strictMode?: boolean - Enable strict parameter checking (default: false)
• allowedTrackingParams?: string[] - Allowed tracking parameter names

Common Tracking Parameters:

• fbclid (Facebook Click ID)
• gclid (Google Click ID)
• msclkid (Microsoft Click ID)
• mc_cid / mc_eid (Mailchimp)
• _ga (Google Analytics)
• ref (Referrer)

completeUtmAttribution

Ensures UTM parameters are complete for proper marketing attribution.

Required Parameters:

• utm_source
• utm_medium
• utm_campaign

Utility Functions

extractUrls(content: string): string[]

Extracts all URLs from text content.

parseQueryParams(url: string): Record<string, string>

Parses query parameters from a URL.

getDomain(url: string): string

Extracts the domain from a URL.

detectPII(value: string, customPatterns?: RegExp[]): PIIDetection[]

Checks if a value matches any PII pattern.

checkParamForPII(paramName: string, paramValue: string, customPatterns?: RegExp[]): PIIDetection[]

Checks if a URL parameter contains PII.

sanitizeUrl(url: string, keysToRemove: string[]): string

Removes specified parameters from a URL.

isDomainAllowed(url: string, allowedDomains: string[]): boolean

Checks if a domain is in the allowlist.

decodeParamValue(value: string): string

Decodes URL-encoded parameter values.

Configuration

TrackingParamsConfig Interface

interface TrackingParamsConfig {
  allowedUtmParams?: string[];
  allowedTrackingParams?: string[];
  piiPatterns?: RegExp[];
  strictMode?: boolean;
  allowThirdPartyTrackers?: boolean;
  allowedDomains?: string[];
}

Testing

This package achieves 100% test coverage with comprehensive test suites for all validation rules and utility functions.

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

Integration Status

Logger Integration

Status: Not applicable - Pure validation functions with no runtime logging requirements.

This package consists of pure validation functions that don't perform any I/O operations or require runtime logging. All validation results are returned through the validators-core Problem interface, which can be logged by consuming applications using @bernierllc/logger if desired.

NeverHub Integration

Status: Not applicable - Primitive validator package with no service dependencies.

As a primitive validator in the validators ecosystem, this package provides stateless validation functions with no need for service discovery or event bus communication. The validators-runner or domain validators that compose these primitives may integrate with NeverHub for centralized validation orchestration.

Docs-Suite

Status: Ready - Complete API documentation with TypeDoc

This package includes comprehensive documentation in README format with detailed API references, usage examples, and configuration options. Documentation can be easily integrated into docs-suite for centralized technical documentation.

Privacy & Compliance

This package helps enforce:

• GDPR compliance by detecting PII in tracking parameters
• CCPA requirements for consumer data privacy
• Privacy best practices for web analytics and marketing
• Third-party tracker governance and authorization

License

Copyright (c) 2025 Bernier LLC

This file is licensed to the client under a limited-use license. The client may use and modify this code only within the scope of the project it was delivered for. Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.