SDK web: UTM y atribución

Esta página explica el seguimiento de UTM y la atribución de campañas en el SDK web de Joryio. Para la instalación, la configuración y la referencia completa de la API, consulta la guía del SDK web.

El SDK captura automáticamente parámetros UTM de las URL para la atribución de campañas y la analítica de marketing. Así puedes saber qué campañas generan conversiones y analizar el embudo de usuarios.

Captura automática de UTM

De forma predeterminada, el SDK captura todos los parámetros UTM estándar cuando están presentes en la URL:

utm_source: origen de la campaña (por ejemplo, "google", "newsletter").
utm_medium: medio de marketing (por ejemplo, "email", "cpc", "social").
utm_campaign: nombre de la campaña (por ejemplo, "summer_sale", "product_launch").
utm_content: contenido o variante del anuncio (por ejemplo, "banner_v1", "link_in_bio").
utm_term: palabras clave de búsqueda de pago (por ejemplo, "running+shoes").

También se capturan:

referrer: referente HTTP (por ejemplo, "https://google.com").
landing_page: URL completa de la página de destino con parámetros de consulta.

// URL de ejemplo:
// https://example.com/pricing?utm_source=google&utm_medium=cpc&utm_campaign=spring_sale

// Todos los eventos incluirán automáticamente:
{
  utm_source: "google",
  utm_medium: "cpc",
  utm_campaign: "spring_sale",
  referrer: "https://google.com/search?q=...",
  landing_page: "https://example.com/pricing?utm_source=google&utm_medium=cpc&utm_campaign=spring_sale"
}

Atribución del primer y último contacto

El SDK registra tanto el primer contacto (atribución de toda la vida) como el último contacto (atribución reciente):

Primer contacto: se captura en la primera visita del usuario y nunca se sobrescribe.

first_touch_utm_source: "facebook"
first_touch_utm_medium: "social"
first_touch_utm_campaign: "awareness_campaign"
first_touch_landing_page: "https://example.com/?utm_source=facebook..."
first_touch_captured_at: "2024-01-15T10:30:00Z"

Último contacto: se actualiza cada vez que se detectan nuevos parámetros UTM.

last_touch_utm_source: "google"
last_touch_utm_medium: "cpc"
last_touch_utm_campaign: "conversion_campaign"
last_touch_landing_page: "https://example.com/pricing?utm_source=google..."
last_touch_captured_at: "2024-02-20T15:45:00Z"

Este modelo de atribución doble permite responder:

Primer contacto: «¿De dónde llegó originalmente este usuario?»
Último contacto: «¿Cuál fue el último punto de contacto antes de la conversión?»

Opciones de configuración

const joryio = new JoryioSDK({
  sdkKey: 'jry_sdk_web_...',

  // El seguimiento de UTM está activado de forma predeterminada
  captureUTM: true,

  // Inicia una sesión nueva cuando cambia la campaña
  resetSessionOnNewCampaign: false,

});

Detalles de configuración:

captureUTM (predeterminado: true): captura automáticamente los parámetros UTM de la URL.
resetSessionOnNewCampaign (predeterminado: false): inicia una sesión nueva cuando cambian los parámetros UTM (de forma similar a Amplitude).
El referente y la página de destino se incluyen de forma predeterminada en las propiedades del evento.

Seguimiento de UTM a nivel de sesión

Los parámetros UTM se almacenan a nivel de sesión, lo que te permite analizar todo el recorrido del usuario:

// El usuario llega desde una campaña de Google Ads
// URL: ?utm_source=google&utm_medium=cpc&utm_campaign=spring_sale

// Primer evento de la sesión
joryio.track('Page Viewed', { page: '/landing' });
// Incluye: utm_source, utm_medium, utm_campaign, referrer, landing_page

// El usuario navega a precios (sin UTM en la URL)
joryio.track('Page Viewed', { page: '/pricing' });
// Sigue incluyendo: utm_source="google", utm_medium="cpc", utm_campaign="spring_sale"

// Todos los eventos de esta sesión llevarán la atribución de campaña
joryio.track('Trial Started');
// Incluye: utm_source="google", utm_medium="cpc", utm_campaign="spring_sale"

Restablecer la sesión con una campaña nueva

Activa resetSessionOnNewCampaign para iniciar sesiones nuevas cuando los usuarios lleguen desde campañas diferentes:

const joryio = new JoryioSDK({
  sdkKey: 'jry_sdk_web_...',
  resetSessionOnNewCampaign: true,
});

// Sesión 1: usuario procedente de Facebook
// URL: ?utm_source=facebook&utm_medium=social
// session_id: "sess_123"

// Sesión 2: el mismo usuario vuelve desde Google (comienza una sesión nueva)
// URL: ?utm_source=google&utm_medium=cpc
// session_id: "sess_456" (ID de sesión nuevo)

Esto es útil para:

Obtener analítica de sesiones precisa a nivel de campaña.
Evitar confusiones de atribución cuando los usuarios llegan desde varias campañas.
Analizar el comportamiento de los usuarios específico de cada campaña.

Actualizaciones manuales de UTM (SPA)

Para aplicaciones de una sola página que cambian la URL sin recargar la página:

// Cuando cambie la URL en tu SPA
window.addEventListener('popstate', () => {
  joryio.updateUTM();
});

// O en tu router
router.on('route-change', () => {
  joryio.updateUTM();
});

// Ejemplo con React Router
import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';

function App() {
  const location = useLocation();

  useEffect(() => {
    // Actualiza los UTM al cambiar de ruta
    joryio.updateUTM();
  }, [location]);
}

Acceder a los datos UTM

Obtén los datos UTM actuales mediante programación:

// Obtiene todos los datos UTM
const utmData = joryio.getUTMData();

console.log(utmData);
// {
//   current: {
//     utm_source: "google",
//     utm_medium: "cpc",
//     utm_campaign: "spring_sale",
//     referrer: "https://google.com",
//     landing_page: "https://example.com/?utm_source=google...",
//     captured_at: 1705319400000
//   },
//   firstTouch: {
//     utm_source: "facebook",
//     utm_medium: "social",
//     utm_campaign: "awareness",
//     captured_at: 1704715200000
//   },
//   lastTouch: {
//     utm_source: "google",
//     utm_medium: "cpc",
//     utm_campaign: "spring_sale",
//     captured_at: 1705319400000
//   }
// }

// Úsalo en tu aplicación
const { current, firstTouch, lastTouch } = joryio.getUTMData();

if (current?.utm_source === 'google') {
  // Muestra una oferta especial al tráfico de Google
}

Casos de uso

1. Análisis del rendimiento de campañas

// Registra conversiones con atribución completa
joryio.track('Order Completed', {
  order_id: 'order_123',
  revenue: 99.99
});
// Incluye automáticamente parámetros UTM para la atribución

2. Variantes de campañas de pruebas A/B

// Registra qué creatividad publicitaria genera conversiones
// URL: ?utm_content=banner_v1
joryio.track('Signup Completed');
// Permite analizar qué valor de utm_content tiene la mayor tasa de conversión

3. Atribución multitoque

// Consulta todo el recorrido del usuario
const { firstTouch, lastTouch } = joryio.getUTMData();

joryio.track('Purchase', {
  order_value: 299.99,
  // Primer contacto: de dónde llegó originalmente
  discovered_via: firstTouch?.utm_source,
  // Último contacto: qué impulsó la conversión final
  converted_via: lastTouch?.utm_source
});

4. Análisis de embudos

// Analiza el abandono por campaña
joryio.track('Checkout Started');  // Incluye UTM automáticamente
joryio.track('Payment Info Added'); // Mismo UTM
joryio.track('Order Completed'); // Mismo UTM

// Ahora puedes segmentar el embudo por utm_campaign para ver qué campañas
// tienen las mejores tasas de conversión en cada paso

Consideraciones de privacidad

Los parámetros UTM y la información del referente se almacenan en localStorage y se eliminan cuando:

el usuario llama a joryio.reset() (cierre de sesión);
el usuario borra los datos del navegador.

La atribución del primer y último contacto se mantiene entre sesiones para el mismo usuario hasta que borre sus datos o cierre sesión; localStorage no tiene caducidad integrada.

Captura automática de UTM​

Atribución del primer y último contacto​

Opciones de configuración​

Seguimiento de UTM a nivel de sesión​

Restablecer la sesión con una campaña nueva​

Actualizaciones manuales de UTM (SPA)​

Acceder a los datos UTM​

Casos de uso​

Consideraciones de privacidad​