Web SDK: UTM & Attribution

This page covers UTM tracking and campaign attribution in the Joryio Web SDK. For installation, configuration, and the full API reference, see the Web SDK guide.

The SDK automatically captures UTM parameters from URLs for campaign attribution and marketing analytics. This enables you to track which campaigns drive conversions and analyze the user funnel.

Automatic UTM Capture

By default, the SDK captures all standard UTM parameters when present in the URL:

utm_source - Campaign source (e.g., "google", "newsletter")
utm_medium - Marketing medium (e.g., "email", "cpc", "social")
utm_campaign - Campaign name (e.g., "summer_sale", "product_launch")
utm_content - Ad content or variant (e.g., "banner_v1", "link_in_bio")
utm_term - Paid search keywords (e.g., "running+shoes")

Additionally captured:

referrer - HTTP referrer (e.g., "https://google.com")
landing_page - Full landing page URL with query parameters

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

// All events will automatically include:
{
  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"
}

First Touch & Last Touch Attribution

The SDK tracks both first touch (lifetime attribution) and last touch (recent attribution):

First Touch - Captured on the user's very first visit and never overwritten:

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"

Last Touch - Updated whenever new UTM parameters are detected:

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"

This dual attribution model helps answer:

First Touch: "Where did this user originally come from?"
Last Touch: "What was the final touchpoint before conversion?"

Configuration Options

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

  // UTM tracking is enabled by default
  captureUTM: true,

  // Start new session when campaign changes
  resetSessionOnNewCampaign: false,

});

Configuration details:

captureUTM (default: true) - Automatically capture UTM parameters from URL
resetSessionOnNewCampaign (default: false) - Start a new session when UTM parameters change (similar to Amplitude)
Referrer and landing page are included in event properties by default.

Session-Level UTM Tracking

UTM parameters are stored at the session level, allowing you to analyze the entire user journey:

// User arrives from Google Ads campaign
// URL: ?utm_source=google&utm_medium=cpc&utm_campaign=spring_sale

// First event in session
joryio.track('Page Viewed', { page: '/landing' });
// Includes: utm_source, utm_medium, utm_campaign, referrer, landing_page

// User navigates to pricing (no UTM in URL)
joryio.track('Page Viewed', { page: '/pricing' });
// Still includes: utm_source="google", utm_medium="cpc", utm_campaign="spring_sale"

// All events in this session will carry the campaign attribution
joryio.track('Trial Started');
// Includes: utm_source="google", utm_medium="cpc", utm_campaign="spring_sale"

Reset Session on New Campaign

Enable resetSessionOnNewCampaign to start fresh sessions when users arrive from different campaigns:

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

// Session 1: User from Facebook
// URL: ?utm_source=facebook&utm_medium=social
// session_id: "sess_123"

// Session 2: Same user returns from Google (new session starts)
// URL: ?utm_source=google&utm_medium=cpc
// session_id: "sess_456" (new session ID)

This is useful for:

Accurate campaign-level session analytics
Preventing attribution confusion when users arrive from multiple campaigns
Analyzing campaign-specific user behavior

Manual UTM Updates (SPAs)

For Single Page Applications that change URLs without page reload:

// When URL changes in your SPA
window.addEventListener('popstate', () => {
  joryio.updateUTM();
});

// Or in your router
router.on('route-change', () => {
  joryio.updateUTM();
});

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

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

  useEffect(() => {
    // Update UTM on route change
    joryio.updateUTM();
  }, [location]);
}

Access UTM Data

Get current UTM data programmatically:

// Get all UTM data
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
//   }
// }

// Use in your application
const { current, firstTouch, lastTouch } = joryio.getUTMData();

if (current?.utm_source === 'google') {
  // Show special offer for Google traffic
}

Use Cases

1. Campaign Performance Analysis

// Track conversions with full attribution
joryio.track('Order Completed', {
  order_id: 'order_123',
  revenue: 99.99
});
// Automatically includes UTM parameters for attribution

2. A/B Test Campaign Variants

// Track which ad creative drives conversions
// URL: ?utm_content=banner_v1
joryio.track('Signup Completed');
// Can analyze: which utm_content value has highest conversion rate

3. Multi-Touch Attribution

// See the full user journey
const { firstTouch, lastTouch } = joryio.getUTMData();

joryio.track('Purchase', {
  order_value: 299.99,
  // First touch: where they came from originally
  discovered_via: firstTouch?.utm_source,
  // Last touch: what drove the final conversion
  converted_via: lastTouch?.utm_source
});

4. Funnel Analysis

// Analyze drop-off by campaign
joryio.track('Checkout Started');  // Auto-includes UTM
joryio.track('Payment Info Added'); // Same UTM
joryio.track('Order Completed'); // Same UTM

// Now you can segment funnel by utm_campaign to see which campaigns
// have the best conversion rates through each step

Privacy Considerations

UTM parameters and referrer information are stored in localStorage and cleared when:

User calls joryio.reset() (logout)
User clears browser data

First touch and last touch attribution persists across sessions for the same user until they clear their data or logout - localStorage has no built-in expiry.

Automatic UTM Capture​

First Touch & Last Touch Attribution​

Configuration Options​

Session-Level UTM Tracking​

Reset Session on New Campaign​

Manual UTM Updates (SPAs)​

Access UTM Data​

Use Cases​

Privacy Considerations​