Cross-Subdomain Tracking

Track users seamlessly across multiple subdomains

Overview

Cross-subdomain tracking allows you to follow a user’s journey as they navigate between different subdomains of your website. For example, tracking users moving from www.example.com to app.example.com to docs.example.com.

Vemetric automatically handles cross-subdomain tracking when configured correctly, using a single cookie domain to maintain user identity across all subdomains.

How It Works

Cookie Domain Scope

Vemetric sets the _vuid cookie with a domain scope that covers all subdomains:

// Cookie is set with domain: .example.com
// This makes it accessible from:
// - www.example.com
// - app.example.com
// - docs.example.com
// - any other subdomain of example.com

Cookie Configuration

The tracking cookie is configured with these attributes:

• Domain: Set to your base domain (e.g., .example.com)
• Path: / (accessible from all paths)
• Secure: true (requires HTTPS)
• HttpOnly: true (not accessible via JavaScript)
• SameSite: None (allows cross-site requests)

Cross-subdomain tracking requires HTTPS on all subdomains. The Secure flag prevents the cookie from being transmitted over unsecured connections.

Setup Instructions

1. Verify Domain Configuration

   Ensure all your subdomains are properly configured and use HTTPS:

   # All these should be accessible via HTTPS
   https://www.example.com
   https://app.example.com
   https://docs.example.com
   

   Use a wildcard SSL certificate (e.g., *.example.com) to cover all subdomains easily.

2. Initialize Vemetric on Each Subdomain

   Install and initialize the Vemetric SDK on every subdomain:

   <!-- On www.example.com -->
   <script src="https://cdn.vemetric.com/sdk.js"></script>
   <script>
     vemetric.init({
       token: 'your-project-token',
       allowCookies: true
     });
   </script>
   

   <!-- On app.example.com -->
   <script src="https://cdn.vemetric.com/sdk.js"></script>
   <script>
     vemetric.init({
       token: 'your-project-token', // Same token!
       allowCookies: true
     });
   </script>
   

   Use the same project token across all subdomains to ensure events are tracked under the same project.

3. Set Your Base Domain

   Configure your base domain in the Vemetric project settings:

   • Go to Project Settings in the dashboard
   • Set Domain to your base domain (e.g., example.com)
   • Save changes

   This ensures the cookie is set with the correct domain scope.

4. Test Cross-Subdomain Tracking

   Verify that tracking works across subdomains:

   1. Visit www.example.com and trigger a page view
   2. Navigate to app.example.com
   3. Check that the same user ID is used in both events
   4. Verify the journey appears as a single session in analytics

Proxy Setup for Subdomains

If you’re using different subdomains for different purposes, you can use the v-host header to proxy requests:

What is the V-Host Header?

The v-host header tells Vemetric which subdomain the event originated from, ensuring:

• Cookies are set for the correct domain
• Outbound link detection works properly
• Referrer tracking is accurate

Implementation

// When sending events from app.example.com
vemetric.init({
  token: 'your-project-token',
  host: 'app.example.com' // Explicitly set the host
});

// The SDK automatically includes the v-host header:
// v-host: app.example.com

Advanced: Manual Header Configuration

If you’re using a custom implementation, include the v-host header:

fetch('https://hub.vemetric.com/e', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'v-host': 'app.example.com' // Current subdomain
  },
  body: JSON.stringify({
    name: 'page_view',
    url: 'https://app.example.com/dashboard'
  })
});

Tracking Subdomain Navigation

Internal vs External Links

Vemetric automatically distinguishes between:

• Internal subdomain navigation: Moving from www.example.com to app.example.com
• External links: Clicking to https://google.com

// Vemetric checks if the target domain matches your project domain
const externalDomain = getNormalizedDomain(href);
if (externalDomain.endsWith(project.domain)) {
  // This is an internal subdomain link - tracked as navigation
} else {
  // This is an external link - tracked as outbound_link event
}

Session Continuity

Sessions continue across subdomains as long as:

1. The user navigates within the 30-minute session window
2. The same cookie is accessible on both subdomains
3. The user has not cleared cookies or switched browsers

Session duration resets with each page view or event, extending the session by 30 minutes from the last activity.

Common Scenarios

Marketing to Product

Scenario: Users land on your marketing site (www.example.com) and sign up for your product (app.example.com).

Tracking flow:

1. User visits www.example.com → Session starts, user ID assigned
2. User clicks “Sign Up” → Navigation tracked
3. User lands on app.example.com/signup → Same user ID, session continues
4. User completes signup → signup_completed event tracked
5. User enters dashboard → Full funnel visible in analytics

Benefits:

• Attribute signups to marketing campaigns
• Analyze conversion paths
• Track time from landing to activation

App to Documentation

Scenario: Users click help links from your app (app.example.com) to your docs (docs.example.com).

Tracking flow:

1. User is in app.example.com → Active session
2. User clicks “Help” → Internal subdomain navigation
3. User lands on docs.example.com → Same session continues
4. Doc page view tracked with same user ID

Benefits:

• Identify which features need better documentation
• Track user help-seeking behavior
• Measure doc engagement

Checkout Flow

Scenario: Multi-step checkout across subdomains (shop.example.com → checkout.example.com → payment.example.com).

Tracking flow:

1. User browses products on shop.example.com
2. User clicks “Checkout” → Redirects to checkout.example.com
3. Same user ID and session maintained
4. User completes payment on payment.example.com
5. Entire checkout funnel tracked as single journey

Benefits:

• Track checkout abandonment rates
• Identify drop-off points
• Optimize conversion funnel

Troubleshooting

Users are getting new IDs on subdomain navigation

Possible causes:

• Cookie domain not set to base domain
• Missing HTTPS on one or more subdomains
• SameSite cookie restrictions
• Third-party cookie blocking

Solutions:

1. Verify the cookie domain is set to .example.com (with leading dot)
2. Ensure all subdomains use HTTPS
3. Check browser console for cookie warnings
4. Test in an incognito window to rule out browser extensions

Sessions are breaking between subdomains

Possible causes:

• Session timeout (30-minute inactivity)
• Cookie being deleted or blocked
• Different project tokens used on different subdomains

Solutions:

1. Verify the same project token is used everywhere
2. Check that cookies are not being cleared by other scripts
3. Monitor session duration in analytics
4. Test with browser developer tools open to watch cookie behavior

Outbound links to other subdomains

Problem: Links to other subdomains are being tracked as outbound links instead of internal navigation.

Cause: The project domain setting doesn’t match your base domain.

Solution:

1. Go to Project Settings
2. Set Domain to your base domain (e.g., example.com)
3. Do not include www or protocol
4. Save and test again

Cookie not accessible across subdomains

Browser console error: Cookie "_vuid" has been rejected because it is in a cross-site context

Solutions:

1. Ensure SameSite=None and Secure=true are set
2. Verify all subdomains use HTTPS (not HTTP)
3. Check that the domain attribute is set correctly
4. Some browsers block third-party cookies by default - this is expected for privacy-focused users

Privacy Considerations

Cookie Consent

When tracking across subdomains, your cookie consent banner should:

• Clearly state that tracking occurs across all subdomains
• List all subdomains where tracking is active
• Allow users to opt out of cross-subdomain tracking

// Example consent implementation
function getUserConsent() {
  return new Promise((resolve) => {
    showConsentBanner({
      message: 'We use cookies to track your experience across www.example.com, app.example.com, and docs.example.com.',
      onAccept: () => resolve(true),
      onReject: () => resolve(false)
    });
  });
}

// Initialize only after consent
getUserConsent().then(consented => {
  vemetric.init({
    token: 'your-project-token',
    allowCookies: consented
  });
});

Data Isolation

If you need to keep certain subdomain data separate:

• Use different project tokens for different subdomain groups
• Create separate projects in Vemetric dashboard
• Filter analytics views by subdomain using custom properties

Testing Checklist

Before deploying cross-subdomain tracking to production:

1. Cookie Inspection

   • Cookie _vuid is set with domain .example.com
   • Cookie has Secure and HttpOnly flags
   • Cookie has SameSite=None
   • Cookie expires far in the future (400 days)
2. Cross-Subdomain Navigation

   • Same user ID maintained when navigating between subdomains
   • Session continues across subdomain boundaries
   • Page views tracked on all subdomains
   • Referrer information captured correctly
3. Event Tracking

   • Custom events work on all subdomains
   • User identification persists across subdomains
   • User properties sync across subdomains
   • Events appear in real-time dashboard
4. Privacy Compliance

   • Cookie consent honored across all subdomains
   • Opt-out removes cookie from all subdomains
   • Privacy policy updated to mention cross-subdomain tracking
   • HTTPS enforced on all subdomains

Advanced Configuration

Custom Cookie Domain

If you need to override the automatic domain detection:

vemetric.init({
  token: 'your-project-token',
  cookieDomain: '.example.com' // Explicitly set cookie domain
});

Subdomain-Specific Tracking

Track which subdomain each event originated from:

vemetric.track('page_view', {
  subdomain: window.location.hostname.split('.')[0],
  full_url: window.location.href
});

// Events will include:
// { subdomain: 'www', full_url: 'https://www.example.com/home' }
// { subdomain: 'app', full_url: 'https://app.example.com/dashboard' }

Then filter analytics by subdomain:

// In analytics queries
filter: {
  properties: {
    subdomain: 'app'
  }
}

Next Steps

Privacy Compliance

Learn how to manage cookies and comply with GDPR/CCPA.

Troubleshooting

Resolve common tracking issues and debugging tips.