Skip to content

Safari ITP Limitations

Overview

Safari's Intelligent Tracking Prevention (ITP) imposes restrictions on third-party storage access. This affects the Hyper widget when your application (that includes the Hyper widget) is embedded as an iframe on a different domain.

Impact

When your application is embedded as an iframe on a different domain (e.g., your app at app.yourdomain.com is embedded in an iframe on parentdomain.com), Safari users with ITP enabled will experience:

  1. No session persistence across page navigations
  2. The widget uses sessionStorage to maintain session IDs
  3. Safari blocks sessionStorage access in third-party contexts

  4. Each page load creates a new session

  5. Loss of context between pages

  6. User progress in multi-step guidances is lost
  7. Chat history doesn't persist
  8. Onboarding state resets on navigation

Affected Scenarios

  • ❌ Your app in a cross-domain iframe - When your application (with Hyper widget) is embedded in an iframe on a different domain
  • ✅ Your app accessed directly - Not affected when users access your application directly
  • ✅ Your app in a same-origin iframe - Not affected when iframe and parent share the same domain

Recommendations for Customers

Option 1: Single Page Application (SPA)

If your application is a SPA (React, Vue, Angular, etc.), this limitation doesn't apply: - No page navigations = no session loss - SessionStorage persists throughout the user's journey - Works perfectly even in cross-domain iframes

This is often the simplest solution if you're already using a modern frontend framework.

Option 2: Avoid Cross-Domain Iframes

If possible, avoid having your application embedded in cross-domain iframes: - Provide direct links to your application instead of iframe embeds - Educate customers about the limitations when embedding in iframes - Offer alternative integration methods

Option 3: Same-Origin Embedding

If iframe embedding is necessary, ensure your application is served from the same domain as the parent: - Use subdomains of the parent domain - Set up proper DNS and SSL certificates - Configure your application to work from multiple domains

Option 4: User Communication

If your application must be embedded in cross-domain iframes, inform users about Safari limitations: - Detect when running in a cross-domain iframe context - Show a notice to Safari users about potential issues - Suggest using a different browser or accessing your app directly - Provide alternative support channels

Technical Details

The limitation stems from: - Safari's ITP blocks all storage APIs (localStorage, sessionStorage, IndexedDB) in third-party contexts - When your application runs in a cross-domain iframe, it's considered a third-party context - This affects all JavaScript running in your application, including the Hyper widget - This is a privacy feature to prevent cross-site tracking

Detection

You can detect if a user might be affected:

function isThirdPartyContext() {
  try {
    return window.self !== window.top;
  } catch (e) {
    return true;
  }
}

function isSafari() {
  return /^((?!chrome|android).)*safari/i.test(navigator.userAgent);
}

if (isThirdPartyContext() && isSafari()) {
  console.warn('User may experience session persistence issues due to Safari ITP');
}

Future Considerations

  • The proposed Hyper.setParams() API would also be affected when your app runs in cross-domain iframes
  • Any feature relying on client-side storage will face similar restrictions in this scenario
  • Consider backend-based session management as a more robust alternative
  • Educate customers about the implications of embedding applications in cross-domain iframes