Vercel Analytics Integration

Overview

Conformo integrates Vercel Analytics for page view tracking exclusively in the Production environment. This document describes the implementation, environment detection, compliance considerations, and testing guidelines.

Implementation

Package

Package: @vercel/analytics (v1.4.1)
Installation: npm install @vercel/analytics

Components

AnalyticsWrapper Component

Location: frontend/src/components/analytics/AnalyticsWrapper.tsx

The AnalyticsWrapper component conditionally renders the Vercel Analytics component based on the deployment environment:

const deploymentEnv =
  (import.meta.env as Record<string, string | undefined>).VITE_VERCEL_ENV ??
  process.env.VERCEL_ENV ??
  process.env.ENVIRONMENT;

const isProductionHostname = () =>
  typeof window !== 'undefined' &&
  (window.location.hostname === 'www.getconformo.ai' ||
    window.location.hostname === 'getconformo.ai' ||
    window.location.hostname.endsWith('.getconformo.ai'));

if (deploymentEnv !== 'production' && !isProductionHostname()) {
  return null;
}

return <Analytics />;

Integration in App.tsx

The AnalyticsWrapper component is included in all route renderers in App.tsx, ensuring analytics tracking across all pages when in production:

import AnalyticsWrapper from './components/analytics/AnalyticsWrapper';

// In each return statement:
return (
  <>
    {/* Page content */}
    <CookieBanner />
    <AnalyticsWrapper />
  </>
);

Environment Detection

Vercel Environment Variables

Vercel automatically sets environment variables based on the deployment context:

Environment	Signals	Analytics Enabled
Production	`VERCEL_ENV=production`, fallback to `ENVIRONMENT=production`, or production hostname (`*.getconformo.ai`, `conformo.vercel.app`)	✅ YES
Preview	`VERCEL_ENV=preview` (or explicit preview override)	❌ NO
Development	`VERCEL_ENV=development`, `ENVIRONMENT` not set, or non-production hostname	❌ NO

Production Environment

According to the Vercel environment configuration (see issue screenshot), the Production environment includes:

Primary domain: www.getconformo.ai
Additional aliases (4 total domains)
Branch: production

Only deployments to these production domains will have analytics enabled.

Preview Environment

Preview deployments (typically from pull requests or non-production branches) will:

Have VERCEL_ENV=preview
NOT load the Analytics component
NOT track page views

Development Environment

Local development will:

Have VERCEL_ENV=development or no environment metadata
Run on localhost (non-production hostname)
NOT load the Analytics component
NOT track page views

Privacy & Compliance

Vercel Analytics is designed with privacy in mind:

Cookieless Tracking: Vercel Analytics does not use cookies for tracking
Data Minimization: Only page views and basic navigation data are collected
No Personal Data: No personally identifiable information (PII) is collected
EU Compliant: Data processing aligns with GDPR requirements

The existing CookieBanner component is already implemented and appears on all pages. Since Vercel Analytics does not use cookies, no additional cookie consent is required for analytics tracking.

Privacy Policy

The Privacy Policy should be updated to include:

Reference to Vercel as a data processor
Description of analytics data collected (page views, navigation)
Data retention policies
User rights (access, deletion, etc.)

Data Processing Agreement

Vercel provides a Data Processing Agreement (DPA) that covers:

Lawful basis for processing (legitimate interest)
Data location (EU/US with appropriate safeguards)
Sub-processors
Security measures

Action Required: Review and sign Vercel’s DPA if not already completed.

Accessibility

Impact Assessment

The Analytics integration has zero impact on accessibility:

No Visual Elements: Analytics component does not render any visible UI
No Focus Order Changes: Does not add focusable elements
No Keyboard Navigation Impact: Does not interfere with keyboard navigation
No ARIA Pattern Changes: Does not modify ARIA attributes or roles
No Screen Reader Impact: Provides no content to screen readers

Testing

Accessibility testing confirms:

All existing WCAG 2.1 AA compliance maintained
Keyboard navigation unchanged
Screen reader functionality unaffected
Focus management preserved

Security

Security Considerations

Script Injection: Vercel Analytics uses a secure, CSP-compliant script
Content Security Policy (CSP):
- Add https://va.vercel-scripts.com to script-src directive
- Add https://va.vercel-analytics.com to connect-src directive
Data Minimization: Only essential page view data is collected
HTTPS Only: All analytics data is transmitted over secure HTTPS
No Third-Party Access: Data is only accessible to authorized Vercel Analytics users

CSP Configuration

If using Content Security Policy headers, update the configuration:

Content-Security-Policy: 
  script-src 'self' https://va.vercel-scripts.com;
  connect-src 'self' https://va.vercel-analytics.com;

Testing

Manual Testing

Testing in Production

Deploy to production branch
Open browser DevTools > Network tab
Navigate to www.getconformo.ai
Verify requests to va.vercel-analytics.com
Check Vercel Analytics dashboard for page view data

Testing in Preview

Create a pull request
Deploy to preview environment
Open browser DevTools > Network tab
Navigate to preview URL
Verify NO requests to va.vercel-analytics.com

Testing in Development

Run npm run dev --prefix frontend
Open browser DevTools > Network tab
Navigate to http://localhost:5173
Verify NO requests to va.vercel-analytics.com

Automated Testing

Unit tests are located in:

frontend/src/components/analytics/__tests__/AnalyticsWrapper.test.tsx

Run tests:

cd frontend
npm test

Test coverage includes:

✅ Analytics renders when VERCEL_ENV (or fallback ENVIRONMENT) equals production
✅ Analytics does not render when VERCEL_ENV=preview
✅ Hostname fallback enables analytics for *.getconformo.ai when no env metadata exists
✅ Environment metadata takes precedence over hostname detection
✅ No document structure impact when analytics is disabled
✅ No accessibility impact

Test Scenarios

Scenario	Signals	Expected Behavior
Production deployment	`VERCEL_ENV=production` (default on Vercel)	Analytics loaded, page views tracked
Privacy-preserving fallback	Production hostname (`www.getconformo.ai`, `*.getconformo.ai`) with no env metadata	Analytics loaded
Preview deployment	`VERCEL_ENV=preview`	Analytics not loaded
Local development	`VERCEL_ENV=development` or `localhost` hostname	Analytics not loaded
Keyboard navigation	All environments	No impact on keyboard navigation
Screen reader	All environments	No impact on screen reader

Monitoring

Vercel Analytics Dashboard

Access the analytics dashboard:

Log in to Vercel
Navigate to the Conformo project
Click “Analytics” in the sidebar
View page views, top pages, and visitor data

Key Metrics

Monitor these metrics in the dashboard:

Page Views: Total number of page views
Top Pages: Most visited pages
Visitors: Unique visitors (anonymized)
Referrers: Traffic sources
Devices: Desktop vs. mobile breakdown

Troubleshooting

Analytics Not Showing Data

Verify Production Deployment: Ensure deployment is to production environment
- Check Vercel dashboard for environment type
- Verify domain is production domain (www.getconformo.ai)
Check Browser DevTools: Look for network requests to va.vercel-analytics.com
- If no requests, analytics component may not be loading
- Check environment variables in Vercel dashboard
Wait for Data: Analytics data may take a few minutes to appear in dashboard

Analytics Loading in Preview/Development

Check Environment Variables: Verify VERCEL_ENV/ENVIRONMENT is not set to production
Clear Cache: Clear browser cache and rebuild application
Review Code: Ensure AnalyticsWrapper logic is correct

Maintenance

Updating Analytics Package

To update the @vercel/analytics package:

Check for security vulnerabilities:
```
npm audit
```

Update package:

cd frontend
npm update @vercel/analytics

Run tests:
```
npm test
```
Test manually in all environments (dev, preview, production)

Reviewing Analytics Data

Recommended Schedule: Review analytics data monthly to:

Identify most-visited pages
Understand user navigation patterns
Detect potential usability issues
Inform feature prioritization

References

Official Documentation

Conformo Documentation

Compliance Resources

Summary

✅ Implemented: Vercel Analytics integrated with environment-based conditional loading
✅ Production Only: Analytics only active in production environment
✅ Privacy Compliant: Cookieless tracking, no PII collected
✅ Accessible: Zero impact on accessibility features
✅ Tested: Comprehensive unit tests and manual testing procedures
✅ Documented: Complete documentation for implementation and compliance

Next Steps:

Review and update Privacy Policy with Vercel Analytics reference
Sign Vercel DPA if not already completed
Monitor analytics data in Vercel dashboard post-deployment
Schedule monthly analytics review meetings

Vercel Analytics Integration

Overview

Implementation

Package

Components

AnalyticsWrapper Component

Integration in App.tsx

Environment Detection

Vercel Environment Variables

Production Environment

Preview Environment

Development Environment

Privacy & Compliance

GDPR Compliance

Cookie Banner

Privacy Policy

Data Processing Agreement

Accessibility

Impact Assessment

Testing

Security

Security Considerations

CSP Configuration

Testing

Manual Testing

Testing in Production

Testing in Preview

Testing in Development

Automated Testing

Test Scenarios

Monitoring

Vercel Analytics Dashboard

Key Metrics

Troubleshooting

Analytics Not Showing Data

Analytics Loading in Preview/Development

Maintenance

Updating Analytics Package

Reviewing Analytics Data

References

Official Documentation

Conformo Documentation

Compliance Resources

Summary