Browser Compatibility

Complete browser compatibility information for Dash0 Web SDK.

Required Browser APIs

The SDK requires the following browser APIs:

• fetch API: For telemetry transmission
• localStorage or sessionStorage: For session persistence (falls back to in-memory if unavailable)
• Performance API: For navigation timing and web vitals
• Promise: For asynchronous operations
• URL and URLSearchParams: For URL parsing

Browser Support Matrix

Feature Support by Browser

Modern Browsers (Chrome 90+, Firefox 88+, Safari 14+, Edge 90+)

✅ Full Support:

• All automatic instrumentations
• Session management
• Custom events
• Error reporting
• User identification
• Signal attributes
• Trace propagation
• Web Vitals collection

Older Browsers (Pre-ES6)

❌ Limited Support:

• Missing Promise support prevents SDK initialization
• Missing fetch API prevents telemetry transmission
• Missing Performance API prevents navigation timing

Browser-Specific Behaviors

Private Browsing Mode

Impact: Storage APIs may be unavailable

Behavior:

• Sessions reset on each page load
• Attributes don't persist across page loads
• SDK continues to operate with in-memory storage

Detection:

function isPrivateBrowsing() {
  try {
    localStorage.setItem("test", "test");
    localStorage.removeItem("test");
    return false;
  } catch {
    return true;
  }
}

Ad Blockers

Impact: May block telemetry transmission

Behavior:

• SDK continues to operate
• Telemetry may not be transmitted
• No errors are thrown

Mitigation: Use first-party endpoints when possible

Content Security Policy (CSP)

Impact: May block inline scripts or external resources

Required CSP Directives:

script-src 'self' 'unsafe-inline' https://unpkg.com;
connect-src 'self' https://ingress.dash0.com;

Browser Extensions

Impact: Extensions may interfere with telemetry collection

Common Issues:

• Privacy extensions may block storage
• Ad blockers may block network requests
• Developer tools may affect Performance API

API Availability Detection

Check Required APIs

function checkBrowserSupport() {
  const required = {
    fetch: typeof fetch !== "undefined",
    storage: typeof localStorage !== "undefined",
    performance: typeof Performance !== "undefined",
    promise: typeof Promise !== "undefined",
    url: typeof URL !== "undefined",
  };
  
  const allSupported = Object.values(required).every(Boolean);
  
  if (!allSupported) {
    console.warn("Some required browser APIs are not available:", required);
  }
  
  return allSupported;
}

Graceful Degradation

if (checkBrowserSupport()) {
  init({
    serviceName: "my-website",
    endpoint: { url: "...", authToken: "..." },
  });
} else {
  // Fallback behavior or show warning
  console.warn("Dash0 SDK not supported in this browser");
}

Mobile Browser Considerations

iOS Safari

Notes:

• Full support on iOS 14+
• Private browsing mode disables storage
• Background tabs may throttle JavaScript

Android Chrome

Notes:

• Full support on Chrome 90+
• Data saver mode may affect network requests
• Battery optimization may affect background telemetry

Performance Considerations

Browser Throttling

Some browsers throttle JavaScript in background tabs:

• Telemetry collection may be delayed
• Network requests may be queued
• Storage operations may be slower

Memory Constraints

Mobile browsers have stricter memory limits:

• Large telemetry payloads may cause issues
• Many queued events may impact performance
• Storage quota may be lower

Testing Recommendations

1. Test in Target Browsers: Verify behavior in all supported browsers
2. Test Private Browsing: Ensure graceful degradation
3. Test with Ad Blockers: Verify behavior when requests are blocked
4. Test Mobile Devices: Verify on actual mobile devices
5. Test Network Conditions: Test with slow/unreliable networks
6. Test Storage Scenarios: Test with storage disabled/quota exceeded

Troubleshooting

SDK Not Initializing

Possible Causes:

• Missing required browser APIs
• CSP blocking scripts
• JavaScript errors in page

Solutions:

• Check browser console for errors
• Verify CSP configuration
• Check browser API availability

Telemetry Not Sending

Possible Causes:

• Ad blocker blocking requests
• CORS configuration issues
• Network connectivity issues
• Invalid endpoint URL

Solutions:

• Check browser network tab
• Verify CORS headers
• Test endpoint accessibility
• Check for ad blockers

Sessions Not Persisting

Possible Causes:

• Private browsing mode
• Storage disabled
• Storage quota exceeded
• Browser clearing storage

Solutions:

• Check storage availability
• Verify storage quota
• Check browser settings
• Test in normal browsing mode

See Edge Cases for more troubleshooting scenarios.