UTM Parameters

UTM (Urchin Tracking Module) parameters allow you to track the source, medium, campaign, and other details of traffic coming to your Practice Growth Suite widget.

Overview

UTM parameters are automatically captured from the URL when users visit your page with the scheduler. These parameters help you understand where your traffic is coming from and measure the effectiveness of your marketing campaigns.

UTM Parameter Attribution Methods

The scheduler supports two primary methods for UTM parameter attribution:

Method 1: Direct UTM Attribution

New Enhanced Support: UTM parameters can now be passed directly to the booking URL for immediate, dynamic attribution. This is the most straightforward approach for campaigns that link directly to booking pages.

Example: User clicks campaign → Direct to booking URL

https://yoursite.com/appointments?utm_source=google&utm_campaign=summer-sale

Method 2: Referrer Pass-Through Attribution

When users first land on a referrer page (like a marketing landing page) before navigating to the booking interface, UTM parameters must be passed through from the referrer URL to the booking URL.

Example Flow:

1. User clicks ad: https://yoursite.com/landing?utm_source=google&utm_campaign=summer-sale
2. Landing page link to scheduler: https://yoursite.com/appointments?utm_source=google&utm_campaign=summer-sale
3. UTM parameters are captured from the booking URL

Important: UTM Parameter Parsing Location

Critical Note: UTM parameters are always parsed from the patient booking URL, regardless of which attribution method you use. The scheduler will not automatically inherit UTM parameters from referrer URLs.

• Patient Booking URL: The direct URL to the scheduler/booking interface (where UTM parsing occurs)
• Referrer URL: The page where users initially land (requires pass-through implementation)

Key Takeaway: For Method 2 (referrer pass-through), you must implement the pass-through mechanisms shown in the Implementation section below to ensure UTM parameters reach the booking URL where they can be properly captured.

Supported UTM Parameters

The Jarvis Analytics Scheduler supports these UTM parameters for tracking marketing campaigns:

Parameter	Description	Example
utm_source	Traffic source	google, facebook, email, rwg
utm_campaign	Campaign name	summer-sale, back-to-school
utm_term	Paid search keywords	dental cleaning, appointment booking
utm_content	Ad content identifier	banner-ad, text-link, video-ad

Reserve with Google (RWG) Integration

When a rwg_token is present in the URL, the utm_source is automatically set to rwg:

// URL with RWG token
https://yoursite.com/appointments?rwg_token=abc123&utm_campaign=summer-sale&utm_term=dental+cleaning&utm_content=banner-ad

// Event data automatically includes:
{
  event: "scheduling-step",
  locationID: "1881",
  mode: "normal",
  value: 2,
  utm_source: "rwg",        // Automatically set from rwg_token
  utm_campaign: "summer-sale",
  utm_term: "dental cleaning",
  utm_content: "banner-ad"
}

Google Click ID (gclid)

The Google Click ID (gclid) parameter is automatically appended by Google Ads when users click on your ads. The scheduler automatically captures gclid from the URL and includes it in event data for Google Ads conversion tracking.

Note: Unlike rwg_token, the presence of gclid does not automatically set utm_source. You should still include utm_source=google in your URLs for proper attribution.

// URL with Google Click ID from Google Ads
https://yoursite.com/appointments?gclid=CjwKCAjw...&utm_source=google&utm_campaign=summer-sale&utm_term=dental+cleaning&utm_content=banner-ad

// Event data automatically includes:
{
  event: "scheduling-step",
  locationID: "1881",
  mode: "normal",
  value: 2,
  gclid: "CjwKCAjw...",        // Automatically captured from URL
}

The gclid parameter is used by Google Ads for conversion tracking and attribution. When present in the URL, it's automatically captured and included in all scheduler events, allowing you to track which Google Ads clicks led to successful bookings.

Implementation

UTM Parameter Pass-Through

To ensure proper UTM tracking, you need to pass UTM parameters from your referrer pages to the booking interface. The implementation approach depends on how you're integrating the scheduler:

Method 1: Direct Booking Links

For websites that use direct links to booking pages, append UTM parameters to all booking links:

// Function to extract UTM parameters from current URL
function getUTMParameters() {
  const urlParams = new URLSearchParams(window.location.search);
  const utmParams = {};
  
  ['utm_source', 'utm_campaign', 'utm_term', 'utm_content', 'gclid'].forEach(param => {
    if (urlParams.has(param)) {
      utmParams[param] = urlParams.get(param);
    }
  });
  
  return utmParams;
}

// Function to append UTM parameters to booking links
function appendUTMToBookingLinks() {
  const utmParams = getUTMParameters();
  
  if (Object.keys(utmParams).length > 0) {
    // Update all booking links on the page
    document.querySelectorAll('a[href*="/appointments"], a[href*="/book"], a[href*="/schedule"]').forEach(link => {
      const url = new URL(link.href);
      Object.keys(utmParams).forEach(param => {
        url.searchParams.set(param, utmParams[param]);
      });
      link.href = url.toString();
    });
  }
}

// Call on page load
document.addEventListener('DOMContentLoaded', appendUTMToBookingLinks);

Example Usage:

<!-- Landing page with UTM parameters -->
<!-- URL: https://yoursite.com/landing?utm_source=google&utm_campaign=summer-sale -->

<!-- Booking links will automatically get UTM parameters appended -->
<a href="/appointments" class="book-now-btn">Book Appointment</a>
<!-- Becomes: /appointments?utm_source=google&utm_campaign=summer-sale -->

Method 2: Iframe Integration

For iframe-embedded schedulers, pass UTM parameters when initializing the scheduler:

// Extract UTM parameters and pass to iframe scheduler
function initializeSchedulerWithUTMs() {
  const utmParams = getUTMParameters();
  
  // Build the iframe URL with UTM parameters
  let iframeUrl = 'https://your-scheduler-domain.com/widget';
  
  if (Object.keys(utmParams).length > 0) {
    const utmString = new URLSearchParams(utmParams).toString();
    iframeUrl += '?' + utmString;
  }
  
  // Create or update iframe
  const iframe = document.getElementById('scheduler-iframe');
  if (iframe) {
    iframe.src = iframeUrl;
  }
}

// Alternative: Pass UTM parameters via postMessage to iframe
function passUTMsToIframe() {
  const utmParams = getUTMParameters();
  const iframe = document.getElementById('scheduler-iframe');
  
  if (iframe && Object.keys(utmParams).length > 0) {
    // Send UTM data to iframe via postMessage
    iframe.onload = function() {
      iframe.contentWindow.postMessage({
        type: 'utm_parameters',
        data: utmParams
      }, '*');
    };
  }
}

// Initialize on page load
document.addEventListener('DOMContentLoaded', initializeSchedulerWithUTMs);

Example Iframe Implementation:

<!-- Landing page with UTM parameters -->
<!-- URL: https://yoursite.com/landing?utm_source=google&utm_campaign=summer-sale -->

<iframe 
  id="scheduler-iframe" 
  src="https://your-scheduler-domain.com/widget"
  width="100%" 
  height="600"
  frameborder="0">
</iframe>

<script>
// UTM parameters will be automatically passed to iframe URL
// Final iframe src: https://your-scheduler-domain.com/widget?utm_source=google&utm_campaign=summer-sale
</script>

Method 3: Widget Mode Integration

For JavaScript widget implementations, pass UTM parameters during widget initialization:

// Initialize Jarvis scheduler with UTM parameters
function initializeJarvisWithUTMs() {
  const utmParams = getUTMParameters();
  
  const jarvis = new JarvisAnalyticsScheduler({
    token: "YOUR_TOKEN",
    companyId: "YOUR_COMPANY_ID",
    locationId: "YOUR_LOCATION_ID",
    // UTM parameters are automatically captured from the current URL
    // No additional configuration needed - they'll be included in all events
  });
  
  // Optional: Log UTM parameters for verification
  if (Object.keys(utmParams).length > 0) {
    console.log('UTM parameters captured:', utmParams);
  }
}

// Initialize widget
document.addEventListener('DOMContentLoaded', initializeJarvisWithUTMs);

Configuration

Basic UTM Tracking

UTM parameters are automatically captured from the booking URL and set as properties on the scheduler instance. No additional configuration is required for the scheduler itself:

const jarvis = new JarvisAnalyticsScheduler({
  token: "YOUR_TOKEN",
  companyId: "YOUR_COMPANY_ID",
  locationId: "YOUR_LOCATION_ID"
});

// UTM parameters are automatically available as properties
console.log(jarvis.utm_source);    // "google"
console.log(jarvis.utm_campaign);  // "summer-sale"
console.log(jarvis.utm_term);      // "dental cleaning"
console.log(jarvis.utm_content);   // "banner-ad"

URL Examples

Complete UTM Parameter Flow

Step 1: User clicks marketing campaign

https://yoursite.com/landing?utm_source=google&utm_campaign=summer-sale&utm_term=dental+cleaning&utm_content=banner-ad

Step 2: UTM parameters passed to booking interface

For Direct Links:

https://yoursite.com/appointments?utm_source=google&utm_campaign=summer-sale&utm_term=dental+cleaning&utm_content=banner-ad

For Iframe Integration:

https://your-scheduler-domain.com/widget?utm_source=google&utm_campaign=summer-sale&utm_term=dental+cleaning&utm_content=banner-ad

For Widget Mode:

https://yoursite.com/appointments?utm_source=google&utm_campaign=summer-sale&utm_term=dental+cleaning&utm_content=banner-ad

Important: The UTM parameters must be present in the final booking URL for proper tracking. The scheduler will not automatically inherit UTM parameters from the referrer URL - they must be explicitly passed through using one of the implementation methods above.

Event Integration

Automatic UTM Capture

UTM parameters are automatically captured from the URL and available as properties on the scheduler instance:

jarvis.onload(() => {
  // Access UTM parameters from the scheduler instance
  console.log('UTM Source:', jarvis.utm_source);
  console.log('UTM Campaign:', jarvis.utm_campaign);
  console.log('UTM Term:', jarvis.utm_term);
  console.log('UTM Content:', jarvis.utm_content);
  console.log('Google Click ID:', jarvis.gclid);
});

jarvis.onNextStep((event) => {
  console.log('Event data:', event);
  // UTM parameters are available on the scheduler instance
  console.log('Campaign:', jarvis.utm_campaign);
});

Google Tag Manager Integration

jarvis.onNextStep((event) => {
  window.dataLayer.push({
    'event': 'jarvis_event',
    'jarvis_event_type': event.event,
    'jarvis_step_number': event.value,
    'jarvis_location_id': event.locationID,
    'jarvis_mode': event.mode,
    // UTM parameters from scheduler instance
    'utm_source': jarvis.utm_source,
    'utm_campaign': jarvis.utm_campaign,
    'utm_term': jarvis.utm_term,
    'utm_content': jarvis.utm_content,
    'gclid': jarvis.gclid
  });
});

Use Cases

Marketing Campaign Tracking

Track the effectiveness of different marketing channels:

// Google Ads campaign
https://yoursite.com/appointments?gclid=CjwKCAjw...&utm_source=google&utm_campaign=summer-sale&utm_term=dental+cleaning&utm_content=banner-ad

// Facebook campaign
https://yoursite.com/appointments?utm_source=facebook&utm_campaign=summer-sale&utm_content=video-ad

// Email campaign
https://yoursite.com/appointments?utm_source=newsletter&utm_campaign=monthly-promo&utm_content=cta-button

// Reserve with Google (RWG)
https://yoursite.com/appointments?rwg_token=abc123&utm_campaign=summer-sale&utm_term=dental+cleaning&utm_content=banner-ad

A/B Testing

Test different ad creatives and placements:

// Version A
https://yoursite.com/appointments?utm_source=google&utm_campaign=test&utm_content=version-a

// Version B
https://yoursite.com/appointments?utm_source=google&utm_campaign=test&utm_content=version-b

Content Marketing

Track content performance:

// Blog post
https://yoursite.com/appointments?utm_source=blog&utm_campaign=health-tips&utm_content=article-link

// Social media post
https://yoursite.com/appointments?utm_source=instagram&utm_campaign=health-tips&utm_content=story-link

Analytics Integration

Google Analytics 4

jarvis.onNextStep((event) => {
  // Send to GA4
  gtag('event', 'jarvis_step_change', {
    'step_number': event.value,
    'location_id': event.locationID,
    'utm_source': jarvis.utm_source,
    'utm_campaign': jarvis.utm_campaign,
    'utm_term': jarvis.utm_term,
    'utm_content': jarvis.utm_content,
    'gclid': jarvis.gclid
  });
});

Custom Analytics

jarvis.onNextStep((event) => {
  // Send to your analytics platform
  analytics.track('Scheduler Step', {
    step: event.value,
    location: event.locationID,
    utm_source: jarvis.utm_source,
    utm_campaign: jarvis.utm_campaign,
    utm_term: jarvis.utm_term,
    utm_content: jarvis.utm_content,
    gclid: jarvis.gclid
  });
});

Best Practices

Naming Conventions

• utm_source: Use consistent source names (e.g., google, facebook, email, rwg)
• utm_campaign: Use descriptive campaign names (e.g., summer-sale-2024)
• utm_term: Use relevant keywords for paid search
• utm_content: Use descriptive content identifiers

URL Structure

https://yoursite.com/appointments?
  utm_source=google&
  utm_campaign=summer-sale&
  utm_term=dental+cleaning&
  utm_content=banner-ad

Campaign Planning

1. Define Campaign Structure - Plan your UTM parameters before launching
2. Use Consistent Naming - Maintain consistent naming across all campaigns
3. Document Parameters - Keep a record of your UTM parameter usage
4. Test URLs - Verify UTM parameters are working correctly
5. Monitor Performance - Track campaign performance using UTM data

Common Examples

Google Ads Campaign

// URL
https://yoursite.com/appointments?gclid=CjwKCAjw...&utm_source=google&utm_campaign=summer-sale&utm_term=dental+cleaning&utm_content=banner-ad

// Event data
{
  event: "scheduling-step",
  locationID: "1881",
  mode: "normal",
  value: 2,
  gclid: "CjwKCAjw...",
  utm_source: "google",
  utm_campaign: "summer-sale",
  utm_term: "dental cleaning",
  utm_content: "banner-ad"
}

Facebook Campaign

// URL
https://yoursite.com/appointments?utm_source=facebook&utm_campaign=summer-sale&utm_content=video-ad

// Event data
{
  event: "scheduling-success",
  locationID: "1881",
  mode: "normal",
  value: 4,
  utm_source: "facebook",
  utm_campaign: "summer-sale",
  utm_content: "video-ad"
}

Email Campaign

// URL
https://yoursite.com/appointments?utm_source=newsletter&utm_campaign=monthly-promo&utm_content=cta-button

// Event data
{
  event: "scheduling-step",
  locationID: "1881",
  mode: "normal",
  value: 1,
  utm_source: "newsletter",
  utm_campaign: "monthly-promo",
  utm_content: "cta-button"
}

Reserve with Google (RWG) Campaign

// URL with RWG token
https://yoursite.com/appointments?rwg_token=abc123&utm_campaign=summer-sale&utm_term=dental+cleaning&utm_content=banner-ad

// Event data (utm_source automatically set to "rwg")
{
  event: "scheduling-step",
  locationID: "1881",
  mode: "normal",
  value: 2,
  utm_source: "rwg",        // Automatically set from rwg_token
  utm_campaign: "summer-sale",
  utm_term: "dental cleaning",
  utm_content: "banner-ad"
}

Troubleshooting

Common Issues

1. UTM Parameters Not Captured

   • Most Common: UTM parameters are on referrer URL but not passed to booking URL
   • Check URL format and parameter names on the booking page specifically
   • Ensure parameters are properly encoded
   • Verify the scheduler is initialized after page load

2. UTM Pass-Through Problems

   • Direct Links: Landing page has UTMs but booking links don't include them
     • Implement the appendUTMToBookingLinks() function
     • Ensure the function runs after page load
     • Check that all booking links have the correct href patterns
   • Iframe Integration: UTM parameters not passed to iframe
     • Verify iframe URL is built with UTM parameters
     • Check iframe src attribute in browser dev tools
     • Consider using postMessage as alternative approach
   • Widget Mode: UTM parameters not captured by widget
     • Ensure UTM parameters are in the page URL where widget is embedded
     • Verify widget initialization occurs after page load

3. Inconsistent Data

   • Use consistent naming conventions across all pages
   • Avoid special characters in parameter values
   • Test URLs before launching campaigns
   • Ensure UTM parameters are consistent from referrer to booking URL

4. Missing Parameters

   • Check if parameters are being stripped by redirects
   • Verify parameter names are correct on the booking URL
   • Ensure parameters are URL-encoded properly
   • Confirm UTM parameters are not lost during page transitions

Testing UTM Parameters

Test UTM Parameter Capture

// Test UTM parameter capture on booking page
jarvis.onload(() => {
  // Method 1: Direct URL parameter access
  const urlParams = new URLSearchParams(window.location.search);
  console.log('UTM parameters from URL:', {
    utm_source: urlParams.get('utm_source'),
    utm_campaign: urlParams.get('utm_campaign'),
    utm_term: urlParams.get('utm_term'),
    utm_content: urlParams.get('utm_content'),
    gclid: urlParams.get('gclid')
  });
  
  // Method 2: Scheduler instance properties
  console.log('UTM parameters from scheduler:', {
    utm_source: jarvis.utm_source,
    utm_campaign: jarvis.utm_campaign,
    utm_term: jarvis.utm_term,
    utm_content: jarvis.utm_content,
    gclid: jarvis.gclid
  });
});

Test UTM Pass-Through

For Direct Booking Links:

// Test UTM pass-through from referrer to booking links
function testDirectLinkPassThrough() {
  const currentUTMs = getUTMParameters();
  console.log('Current page UTMs:', currentUTMs);
  
  // Check if booking links include UTM parameters
  document.querySelectorAll('a[href*="/appointments"], a[href*="/book"], a[href*="/schedule"]').forEach((link, index) => {
    const linkUrl = new URL(link.href);
    const linkUTMs = {};
    
    ['utm_source', 'utm_campaign', 'utm_term', 'utm_content', 'gclid'].forEach(param => {
      if (linkUrl.searchParams.has(param)) {
        linkUTMs[param] = linkUrl.searchParams.get(param);
      }
    });
    
    console.log(`Booking link ${index + 1}:`, link.href);
    console.log(`Link UTMs:`, linkUTMs);
  });
}

// Run test
testDirectLinkPassThrough();

For Iframe Integration:

// Test UTM parameters in iframe URL
function testIframeUTMPassThrough() {
  const iframe = document.getElementById('scheduler-iframe');
  if (iframe) {
    console.log('Iframe src:', iframe.src);
    
    const iframeUrl = new URL(iframe.src);
    const iframeUTMs = {};
    
    ['utm_source', 'utm_campaign', 'utm_term', 'utm_content', 'gclid'].forEach(param => {
      if (iframeUrl.searchParams.has(param)) {
        iframeUTMs[param] = iframeUrl.searchParams.get(param);
      }
    });
    
    console.log('Iframe UTM parameters:', iframeUTMs);
  } else {
    console.log('No scheduler iframe found');
  }
}

// Run test
testIframeUTMPassThrough();

For Widget Mode:

// Test UTM parameters available to widget
function testWidgetUTMCapture() {
  const currentUTMs = getUTMParameters();
  console.log('UTMs available to widget:', currentUTMs);
  
  // Test if widget events include UTM data
  if (typeof jarvis !== 'undefined') {
    jarvis.onNextStep((event) => {
      console.log('Widget event with UTMs:', {
        event: event.event,
        utm_source: event.utm_source,
        utm_campaign: event.utm_campaign,
        utm_term: event.utm_term,
        utm_content: event.utm_content,
        gclid: event.gclid
      });
    });
  }
}

// Run test
testWidgetUTMCapture();

Next Steps

• Event Types - Learn about available events
• Google Tag Manager Integration - Analytics setup