Pitcher iframe Integration Approaches

Comparison of One-Time Parameter Passing vs. Real-Time Message Pipeline

Overview

Two primary approaches exist for integrating Pitcher applications via iframes:

1. One-Time Parameter Passing: Parameters passed once during initialization
2. Window Message Pipeline: Real-time bidirectional communication

Feature Comparison

Aspect	Approach 1: One-Time Parameter Passing	Approach 2: Window Message Pipeline
Communication	Unidirectional - Parameters passed once via URL query strings or iframe attributes during initialization	Bidirectional - Real-time two-way communication using postMessage API with event listeners
Data Transfer	Limited - URL length restrictions (~2000 chars), data must be serializable to query strings	Unlimited - Can send complex objects, binary data, and large payloads
API Access	Static - Cannot access Pitcher API after initial load, requires page refresh for updates	Dynamic - Real-time access to Pitcher API, can make requests on-demand
Event Handling	None - No event bridge, iframe operates independently	Full Support - Complete event bridge for user actions, state changes, and notifications
State Persistence	Manual - Must implement own localStorage/sessionStorage logic localStorage.setItem('lastPage', currentPage);	Coordinated - Can sync state with parent, use localStorage with parent awareness parent.postMessage({type: 'saveState', page: currentPage}, '*');
Security	Basic - Token/credentials exposed in URL, limited validation options	Enhanced - Origin validation, secure token exchange, encrypted payloads possible
Implementation	Simple - Minimal code, quick setup const params = new URLSearchParams(window.location.search);	Complex - Requires message handlers, protocol design, error handling window.addEventListener('message', handleMessage);
Maintenance	Low - Fewer moving parts, less code to maintain	Higher - Message protocol versioning, backwards compatibility concerns
Performance	Fast Initial Load - No message overhead, direct rendering	Slight Overhead - Message serialization/deserialization, but enables lazy loading
User Experience	Static - Page refreshes for updates, limited interactivity with parent	Dynamic - Seamless updates, real-time synchronization, rich interactions

Use Case: "Remember Last Page iframe Was Left"

Approach 1: One-Time Parameters

Implementation:

// On iframe load
const lastPage = localStorage.getItem('lastPage');
if (lastPage) navigateToPage(lastPage);

// On page change
localStorage.setItem('lastPage', currentPage);

Limitations:

• Parent unaware of navigation changes
• Cannot sync across multiple sessions
• Storage isolated to iframe origin
• No way to clear from parent app

Approach 2: Message Pipeline

Implementation:

// iframe sends navigation updates
parent.postMessage({
    type: 'pageChanged',
    page: currentPage,
    timestamp: Date.now()
}, '*');

// Parent stores and returns on next load
window.addEventListener('message', (e) => {
    if (e.data.type === 'restoreState') {
        navigateToPage(e.data.lastPage);
    }
});

Advantages:

• Parent tracks all navigation
• Can sync across devices via Pitcher API
• Centralized state management
• Analytics and usage tracking

⚠️ Important: Cookie & iframe Limitations

Both approaches are subject to browser cookie policies and iframe restrictions:

• SameSite Cookie Restrictions: With SameSite=Lax (browser default), cookies are not sent in cross-origin iframe requests
• Third-Party Cookie Blocking: Many browsers block third-party cookies in iframes by default (Safari ITP, Firefox ETP)
• Storage Access: localStorage/sessionStorage are partitioned per origin - iframe storage is isolated from parent

Solutions Required:

• Use SameSite=None; Secure for cross-origin cookies (requires HTTPS)
• Implement Storage Access API for user consent
• Consider server-side session management
• Use postMessage for state sharing instead of relying on cookies

Impact: Authentication tokens, session data, and user preferences stored in cookies may not be accessible in cross-origin iframes without proper configuration.

When to Use Each Approach

When to Use Approach 1: One-Time Parameters

• Simple, static content display
• No need for runtime updates
• Quick prototypes or MVPs
• Limited integration requirements
• Security-sensitive environments where minimal surface area is preferred
• Bandwidth-constrained scenarios
• When iframe content is mostly self-contained

When to Use Approach 2: Message Pipeline

• Rich, interactive applications
• Real-time data synchronization needs
• Complex user workflows spanning parent and iframe
• Analytics and tracking requirements
• Multi-device or multi-tab state sync
• Dynamic permission or configuration updates
• When iframe needs to trigger parent actions

Additional Use Cases Comparison

Use Case	Approach 1	Approach 2
User Authentication	Pass token once, handle expiry internally	Refresh tokens via parent, seamless re-auth
Data Updates	Requires full reload for new data	Push updates in real-time, partial updates
Error Handling	Isolated error handling, no parent notification	Centralized error reporting, parent can react
Analytics	Separate tracking, duplicate implementation	Unified tracking through parent application

Recommendations

• For simple integrations: Start with Approach 1 and migrate to Approach 2 as needs grow
• For enterprise applications: Implement Approach 2 from the start for future flexibility
• For mixed scenarios: Consider hybrid approach - initial parameters with optional message channel