generateUTMUrl

Paquete: @tiendana/utils

Genera una URL con parámetros UTM para tracking de campañas de marketing en Google Analytics y otras herramientas de analytics.

Características

✅ Agrega parámetros UTM estándar
✅ Preserva query params existentes
✅ URLSearchParams para encoding seguro
✅ Compatibilidad con Google Analytics
✅ Soporte para Analytics 360

Firma

function generateUTMUrl(
  url: string,
  utm: {
    source: string;
    medium: string;
    campaign: string;
  }
): string

Parámetros

Parámetro	Tipo	Descripción	Requerido
url	string	URL base a la que agregar parámetros UTM	✅
utm.source	string	Fuente del tráfico (google, facebook, newsletter)	✅
utm.medium	string	Medio (cpc, email, social, organic)	✅
utm.campaign	string	Nombre de la campaña	✅

Retorno

Tipo: string

URL completa con parámetros UTM agregados. Se exporta como const flecha (export const generateUTMUrl = ...).

Ejemplos de Uso

Campaña de Email

import { generateUTMUrl } from '@tiendana/utils';

const emailLink = generateUTMUrl(
  'https://tienda.com/productos',
  {
    source: 'newsletter',
    medium: 'email',
    campaign: 'verano_2024'
  }
);

// https://tienda.com/productos?utm_source=newsletter&utm_medium=email&utm_campaign=verano_2024

Campaña de Redes Sociales

const facebookAd = generateUTMUrl(
  'https://app.com/registro',
  {
    source: 'facebook',
    medium: 'cpc',
    campaign: 'black_friday_2024'
  }
);

// Para usar en Facebook Ads Manager

Link en Blog Post

const blogCTA = generateUTMUrl(
  'https://producto.com/demo',
  {
    source: 'blog',
    medium: 'organic',
    campaign: 'content_marketing_q1'
  }
);

Google Ads

const googleAd = generateUTMUrl(
  'https://landing.com',
  {
    source: 'google',
    medium: 'cpc',
    campaign: 'search_brand_campaign'
  }
);

Preservar Query Params Existentes

const existingParams = generateUTMUrl(
  'https://shop.com/product?color=red&size=m',
  {
    source: 'instagram',
    medium: 'social',
    campaign: 'influencer_promo'
  }
);

// https://shop.com/product?color=red&size=m&utm_source=instagram&utm_medium=social&utm_campaign=influencer_promo

Comportamiento con Casos Límite

// Si ya existe un utm_* se reemplaza (no se duplica) y conserva su posición
generateUTMUrl('https://a.com/?utm_source=old&x=1', { source: 'g', medium: 'c', campaign: 'k' });
// 'https://a.com/?utm_source=g&x=1&utm_medium=c&utm_campaign=k'

// Sin query no se agrega barra: se concatena `?` directamente
generateUTMUrl('https://a.com', { source: 'g', medium: 'c', campaign: 'k' });
// 'https://a.com?utm_source=g&utm_medium=c&utm_campaign=k'

No soporta fragmentos (#)

La función parte la URL en el primer ? y no entiende #fragmento. Un fragmento después de la query termina codificado dentro de un valor:

generateUTMUrl('https://a.com/p?x=1#frag', { source: 'g', medium: 'c', campaign: 'k' });
// 'https://a.com/p?x=1%23frag&utm_source=g&utm_medium=c&utm_campaign=k'

Quita el fragmento antes de llamar y agrégalo después.

Casos de Uso Comunes

• Email marketing: Newsletters, secuencias automatizadas, promociones
• Redes sociales: Posts orgánicos, anuncios pagados, stories
• Google Ads: Search, Display, Shopping campaigns
• Affiliates: Links de afiliados con tracking
• Content marketing: Blog posts, ebooks, webinars

Parámetros UTM Estándar

Parámetro	Valores Comunes	Descripción
utm_source	google, facebook, newsletter, twitter	Fuente del tráfico
utm_medium	cpc, email, social, organic, referral	Medio de marketing
utm_campaign	nombre_campaña	Identificador de campaña específica

Valores Recomendados por Medium

• cpc: Cost-per-click (anuncios pagados)
• email: Email marketing
• social: Redes sociales orgánicas
• organic: Búsqueda orgánica
• referral: Links de referencia
• affiliate: Marketing de afiliados

Ver También

• guid - Generar IDs únicos
• Cookies - Almacenar parámetros UTM