Skip to main content

Browser support

The Onramp Kit works in all modern browsers and provides fallbacks for older browsers. This page covers browser requirements, rendering modes, and security considerations.

Supported browsers​

BrowserVersionRendering mode
Chrome80+Inline or iframe
Firefox75+Inline or iframe
Safari13.1+Inline or iframe
Edge80+Inline or iframe
Edge Legacy18Iframe only
IE1111Iframe only

Mobile browsers: Chrome for Android, Safari for iOS, and Samsung Internet are fully supported.

Rendering modes​

The SDK automatically selects the best rendering mode for each browser:

Inline mode​

The configurator renders directly in your page's DOM using Shadow DOM for style isolation. This provides the best performance and tightest integration.

Requirements:

  • ES Modules (type="module")
  • Custom Elements (customElements)
  • Shadow DOM (attachShadow)
  • CSS Custom Properties (CSS variables)

Iframe mode​

The configurator renders in an isolated iframe. This provides maximum compatibility and security isolation but has slightly higher overhead.

Used when:

  • Browser doesn't support inline requirements
  • data-mode="iframe" is explicitly set
  • Site's CSP restricts inline rendering

Module loading​

The SDK uses a dual-script pattern for maximum compatibility:

<!-- Modern browsers load this -->
<script type="module" src="https://cdn.deepfathom.ai/onramp-kit/v1/widget.mjs"></script>

<!-- Legacy browsers load this instead -->
<script nomodule src="https://cdn.deepfathom.ai/onramp-kit/v1/widget.legacy.js"></script>
  • Modern browsers (ES2020+) load the module script and ignore nomodule
  • Legacy browsers (IE11, Edge Legacy) ignore type="module" and load the nomodule script

Both scripts provide identical functionality—the difference is bundling and polyfills.

Content Security Policy (CSP)​

If your site uses a Content Security Policy, you'll need to allow the Onramp Kit resources.

Required directives​

script-src: https://cdn.deepfathom.ai
frame-src: https://onramp.deepfathom.ai
connect-src: https://api.deepfathom.ai

Full CSP example​

Content-Security-Policy:
  default-src 'self';
  script-src 'self' https://cdn.deepfathom.ai;
  frame-src https://onramp.deepfathom.ai;
  connect-src 'self' https://api.deepfathom.ai;
  style-src 'self' 'unsafe-inline';
  img-src 'self' data: https:;

CSP errors​

If you see errors like these in your browser console, update your CSP:

ErrorSolution
Refused to load the scriptAdd CDN to script-src
Refused to frameAdd iframe origin to frame-src
Refused to connect toAdd API to connect-src

Iframe embedding restrictions​

Some sites restrict iframe embedding with X-Frame-Options or frame-ancestors. The Onramp Kit iframe loads from https://onramp.deepfathom.ai.

If your site is embedded​

If your site is embedded in another page (e.g., a portal or CMS), ensure the parent page allows:

Content-Security-Policy: frame-ancestors 'self' https://your-portal.com;

If the configurator iframe fails​

Check for these headers on your page that might block the iframe:

X-Frame-Options: DENY

This header should be SAMEORIGIN or removed to allow the configurator iframe.

Storage and cookies​

Modern browsers increasingly block third-party cookies. The Onramp Kit is designed to work without them:

  • Session state: Stored in URL or snapshot service, not cookies
  • Preferences: Passed via configuration, not persisted
  • Analytics: Delegated to your page's analytics (not configurator-internal)

Local storage​

The configurator uses localStorage to preserve assessment progress between page loads. This works in all browsers except:

  • Private/incognito mode (some browsers)
  • Safari with "Prevent cross-site tracking" enabled (for iframed configurators)

When local storage isn't available, visitors can still complete assessments—they just can't resume after closing the page.

Known limitations​

Safari ITP​

Safari's Intelligent Tracking Prevention may clear localStorage for the configurator iframe after 7 days of no interaction. For long-running assessments, use the snapshot service for persistence.

Firefox Enhanced Tracking Protection​

In strict mode, Firefox may block some cross-origin requests. The configurator handles this gracefully, but snapshot service calls may fail. Use relaxed protection for partner sites, or configure CORS carefully on your snapshot service.

Mobile keyboards​

On mobile devices, the configurator adjusts layout when the keyboard appears. In rare cases with complex pages, you may notice layout shifts. Setting a fixed height on the container can help:

[data-deep-fathom-onramp] {
  min-height: 600px;
}

Testing your integration​

Browser testing checklist​

Before launching, test in:

  • Chrome (latest)
  • Firefox (latest)
  • Safari (latest)
  • Edge (latest)
  • Mobile Safari (iOS)
  • Chrome for Android

If you support legacy browsers​

Also test in:

  • IE11 (iframe mode)
  • Edge Legacy (iframe mode)

CSP testing​

  1. Open browser DevTools → Console
  2. Load your page with the configurator
  3. Look for CSP violation errors (red text)
  4. Update your CSP to allow blocked resources

Troubleshooting​

Configurator doesn't appear​

  1. Check console for errors — CSP violations, script load failures
  2. Verify script URL — Ensure CDN URL is correct and accessible
  3. Check container element — Must have data-deep-fathom-onramp attribute

Configurator appears but doesn't work​

  1. Check for JavaScript errors — May indicate compatibility issues
  2. Try iframe mode explicitly — Set data-mode="iframe"
  3. Test in a modern browser — Isolate whether it's a compatibility issue

Events not received​

  1. Verify origin — Event origin must match expected configurator origin
  2. Check iframe sandbox — Don't add restrictive sandbox attribute
  3. Test postMessage — Add temporary logging to verify messages arrive

Next steps​