How to Prevent Double URL Encoding: The Complete Prevention Guide

/**
 * Clean any string to URL-safe characters only
 * Eliminates ALL encoding needs
 */
function toURLSafe(value) {
  if (!value) return '';
 
  return value
    .toLowerCase()                    // All lowercase
    .trim()                          // Remove edge whitespace
    .normalize('NFD')                // Decompose unicode
    .replace(/[\u0300-\u036f]/g, '') // Remove diacritics (é → e)
    .replace(/\s+/g, '-')           // Spaces to hyphens
    .replace(/%/g, '-percent')       // Percent to word
    .replace(/&/g, '-and-')          // Ampersand to word
    .replace(/\+/g, '-plus-')        // Plus to word
    .replace(/\//g, '-')             // Slash to hyphen
    .replace(/[^a-z0-9-_]/g, '')    // Remove all other chars
    .replace(/-+/g, '-')            // Deduplicate hyphens
    .replace(/^-|-$/g, '');          // Trim edge hyphens
}
 
// Examples
console.log(toURLSafe('Summer Sale 2024'));
// "summer-sale-2024"
 
console.log(toURLSafe('Save 50%! Limited Time'));
// "save-50-percent-limited-time"
 
console.log(toURLSafe('Q&A Webinar: Email Tips'));
// "qa-webinar-email-tips"
 
console.log(toURLSafe('Résumé Builder (Free)'));
// "resume-builder-free"
 
// NO ENCODING NEEDED FOR ANY OF THESE! 🎉

/**
 * Build UTM URLs with automatic cleaning
 * Makes double-encoding impossible
 */
class SafeURLBuilder {
  constructor(baseURL) {
    this.baseURL = baseURL;
    this.params = {};
  }
 
  setSource(value) {
    this.params.utm_source = toURLSafe(value);
    return this;
  }
 
  setMedium(value) {
    this.params.utm_medium = toURLSafe(value);
    return this;
  }
 
  setCampaign(value) {
    this.params.utm_campaign = toURLSafe(value);
    return this;
  }
 
  setContent(value) {
    this.params.utm_content = toURLSafe(value);
    return this;
  }
 
  setTerm(value) {
    this.params.utm_term = toURLSafe(value);
    return this;
  }
 
  build() {
    const url = new URL(this.baseURL);
 
    Object.keys(this.params).forEach(key => {
      if (this.params[key]) {
        url.searchParams.set(key, this.params[key]);
      }
    });
 
    // Final validation: NO ENCODING ALLOWED
    const finalURL = url.toString();
    if (finalURL.match(/\?.*%/)) {
      throw new Error(
        'URL contains encoding after cleaning! This should never happen. ' +
        'Check base URL for encoding.'
      );
    }
 
    return finalURL;
  }
}
 
// Usage
const builder = new SafeURLBuilder('https://example.com/landing');
 
const trackingURL = builder
  .setSource('Email Newsletter')
  .setMedium('Marketing Email')
  .setCampaign('Summer Sale 2024')
  .setContent('Hero Banner (Primary CTA)')
  .build();
 
console.log(trackingURL);
// https://example.com/landing?utm_source=email-newsletter&utm_medium=marketing-email&utm_campaign=summer-sale-2024&utm_content=hero-banner-primary-cta
 
// ✅ No % anywhere in URL
// ✅ Safe to pass through any system
// ✅ Double-encoding impossible

/**
 * Validation gate that blocks URLs with encoding
 * Run before any campaign launch
 */
function validateNoEncoding(url, context = '') {
  const errors = [];
 
  try {
    const urlObj = new URL(url);
 
    // Check base URL (before ?)
    if (urlObj.origin + urlObj.pathname !== urlObj.href.split('?')[0]) {
      errors.push('Malformed base URL');
    }
 
    // Check each UTM parameter
    ['utm_source', 'utm_medium', 'utm_campaign', 'utm_content', 'utm_term'].forEach(param => {
      const value = urlObj.searchParams.get(param);
      if (!value) return;
 
      // Check for ANY encoding
      if (value.includes('%')) {
        errors.push({
          param,
          value,
          issue: 'Contains percent encoding',
          recommendation: 'Use clean values without encoding'
        });
      }
 
      // Check for non-safe characters
      if (!/^[a-z0-9-_]*$/.test(value)) {
        errors.push({
          param,
          value,
          issue: 'Contains non-safe characters',
          found: value.match(/[^a-z0-9-_]/g)?.join(', '),
          recommendation: 'Use only a-z, 0-9, hyphens'
        });
      }
 
      // Check for uppercase
      if (value !== value.toLowerCase()) {
        errors.push({
          param,
          value,
          issue: 'Contains uppercase letters',
          recommendation: 'Use all lowercase'
        });
      }
    });
 
  } catch (e) {
    errors.push({
      issue: 'Invalid URL format',
      error: e.message
    });
  }
 
  if (errors.length > 0) {
    const contextStr = context ? ` [${"{"}{"{"}context{"}"}{"}"}}]` : '';
    throw new ValidationError(
      `URL validation failed${"{"}{"{"}contextStr{"}"}{"}"}}:\n` +
      errors.map(e => `  - ${e.param || 'URL'}: ${e.issue}`).join('\n') +
      '\n\nURL: ' + url
    );
  }
 
  return true;
}
 
class ValidationError extends Error {
  constructor(message) {
    super(message);
    this.name = 'ValidationError';
  }
}
 
// Usage: Integrate into deployment workflow
try {
  validateNoEncoding(campaignURL, 'Email campaign launch');
  deployEmail(campaignURL);
} catch (e) {
  if (e instanceof ValidationError) {
    console.error('❌ CAMPAIGN BLOCKED:');
    console.error(e.message);
    // Alert marketing ops team
    // Block deployment
  }
  throw e;
}

async function preLaunchChecklist(campaign) {
  const checks = {
    passed: [],
    failed: [],
    warnings: []
  };
 
  // Check 1: URL validation
  try {
    validateNoEncoding(campaign.url);
    checks.passed.push('URL encoding validation');
  } catch (e) {
    checks.failed.push({
      check: 'URL encoding validation',
      error: e.message
    });
  }
 
  // Check 2: Parameter completeness
  const url = new URL(campaign.url);
  const required = ['utm_source', 'utm_medium', 'utm_campaign'];
  const missing = required.filter(p => !url.searchParams.has(p));
 
  if (missing.length === 0) {
    checks.passed.push('Required parameters present');
  } else {
    checks.failed.push({
      check: 'Required parameters',
      error: `Missing: ${missing.join(', ')}`
    });
  }
 
  // Check 3: Naming convention
  const campaign_name = url.searchParams.get('utm_campaign');
  if (campaign_name && campaign_name.match(/^[a-z0-9-]+$/)) {
    checks.passed.push('Naming convention');
  } else {
    checks.warnings.push({
      check: 'Naming convention',
      message: 'Campaign name should use lowercase and hyphens only'
    });
  }
 
  // Check 4: Test click
  try {
    const response = await fetch(campaign.url, { method: 'HEAD' });
    if (response.ok) {
      checks.passed.push('URL accessibility');
    } else {
      checks.failed.push({
        check: 'URL accessibility',
        error: `HTTP ${response.status}`
      });
    }
  } catch (e) {
    checks.failed.push({
      check: 'URL accessibility',
      error: e.message
    });
  }
 
  // Report
  const canLaunch = checks.failed.length === 0;
 
  console.log('\n=== PRE-LAUNCH VALIDATION ===');
  console.log(`Campaign: ${campaign.name}`);
  console.log(`URL: ${campaign.url}`);
  console.log(`\n✅ Passed: ${checks.passed.length}`);
  checks.passed.forEach(p => console.log(`   - ${"{"}{"{"}p{"}"}{"}"}}`));
 
  if (checks.warnings.length > 0) {
    console.log(`\n⚠️  Warnings: ${checks.warnings.length}`);
    checks.warnings.forEach(w => console.log(`   - ${w.check}: ${w.message}`));
  }
 
  if (checks.failed.length > 0) {
    console.log(`\n❌ Failed: ${checks.failed.length}`);
    checks.failed.forEach(f => console.log(`   - ${f.check}: ${f.error}`));
  }
 
  console.log(`\n${canLaunch ? '✅ APPROVED FOR LAUNCH' : '❌ LAUNCH BLOCKED'}`);
 
  return {
    canLaunch,
    checks
  };
}
 
// Usage
const result = await preLaunchChecklist({
  name: 'Summer Sale Email',
  url: 'https://example.com?utm_source=email&utm_medium=newsletter&utm_campaign=summer-sale-2024'
});
 
if (!result.canLaunch) {
  throw new Error('Campaign failed pre-launch validation');
}

async function safelyShorten(longURL) {
  // Validate before shortening
  validateNoEncoding(longURL, 'Before Bitly');
 
  // Create short link
  const result = await bitly.shorten({
    long_url: longURL  // Clean URL, no encoding
  });
 
  // Verify destination matches
  const destination = await bitly.getDestination(result.link);
 
  if (destination !== longURL) {
    throw new Error(
      `Bitly changed URL!\n` +
      `Input: ${"{"}{"{"}longURL{"}"}{"}"}}\n` +
      `Output: ${"{"}{"{"}destination{"}"}{"}"}}`
    );
  }
 
  return result.link;
}

# UTM Encoding Prevention - Quick Reference
 
## ✅ DO
- Use lowercase letters only
- Use hyphens for word separation
- Use numbers anywhere
- Test URLs before launch
- Run validation script
 
## ❌ DON'T
- Use spaces or special characters
- Manually add %20 or encoding
- Use uppercase letters
- Pass encoded values to systems
- Skip validation
 
## Examples
 
✅ CORRECT:
utm_campaign=summer-sale-2024
utm_source=email-newsletter
utm_medium=marketing-email
 
❌ WRONG:
utm_campaign=Summer Sale 2024 (spaces, uppercase)
utm_campaign=summer%20sale (encoded)
utm_campaign=SummerSale2024 (camelCase)
 
## Emergency Contacts
If you see % in campaign names:
1. Stop the campaign
2. Contact: [marketing-ops@company.com]
3. Don't try to fix yourself

/**
 * Weekly audit for encoding issues
 * Runs every Monday at 9am
 */
async function weeklyEncodingAudit() {
  const lastWeek = {
    startDate: '7daysAgo',
    endDate: 'yesterday'
  };
 
  // Fetch GA4 data
  const campaigns = await fetchGA4Campaigns(lastWeek);
 
  // Check for encoding artifacts
  const issues = campaigns.filter(campaign =>
    campaign.name.includes('%') ||
    campaign.name.includes('+')
  );
 
  if (issues.length > 0) {
    // Send alert
    await sendAlert({
      to: 'marketing-ops@company.com',
      subject: `⚠️ Encoding Issues Detected (${issues.length} campaigns)`,
      body: `
        Weekly audit found ${issues.length} campaigns with encoding issues:
 
        ${issues.map(i => `- ${i.name} (${i.sessions} sessions)`).join('\n')}
 
        This usually means:
        1. URL was double-encoded before sending
        2. A new system is encoding URLs
        3. Team member bypassed validation
 
        Action required:
        1. Identify source of encoding
        2. Fix affected campaigns
        3. Review team training
      `
    });
 
    // Log for tracking
    await logEncodingIssues(issues);
  }
 
  return {
    checked: campaigns.length,
    issues: issues.length,
    clean: campaigns.length - issues.length
  };
}
 
// Schedule weekly
schedule.everyMonday().at('09:00').run(weeklyEncodingAudit);

/**
 * Monitor new campaigns in real-time
 * Trigger: New event in GA4
 */
async function monitorNewCampaigns(event) {
  const campaignName = event.params.campaign_name;
 
  // Check for encoding
  if (campaignName.includes('%')) {
    // Immediate alert
    await sendUrgentAlert({
      to: 'marketing-ops@company.com',
      subject: '🚨 URGENT: New campaign has encoding issues',
      body: `
        Campaign: ${"{"}{"{"}campaignName{"}"}{"}"}}
        First seen: ${new Date().toISOString()}
        Source: ${event.params.source}
        Medium: ${event.params.medium}
 
        ACTION REQUIRED:
        1. Pause this campaign immediately
        2. Fix the encoding
        3. Relaunch with clean URL
      `
    });
 
    // Log incident
    await logEncodingIncident({
      campaign: campaignName,
      source: event.params.source,
      medium: event.params.medium,
      timestamp: new Date()
    });
  }
}