Why We Ditched iFrames for Our Testimonial Widget (And Wrote 1,000 Lines of Vanilla JS Instead)

lscreen mode

initWall fetches wall data using the embedSlug as the sole credential, constructs the DOM, injects scoped styles, and appends everything to the container. The slug is a random 16-character string—unguessable, non-rotatable, and intentionally decoupled from auth sessions. Compromise only results in public testimonial display, which aligns with the widget's threat model.

Scoping CSS without Shadow DOM

Shadow DOM was evaluated but rejected because it blocks host page font inheritance, breaking typography consistency for design-conscious customers. Instead, every CSS rule is prefixed with .proofly-root:

.proofly-root {
  font-family: inherit;
  box-sizing: border-box;
}

.proofly-root .wall-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
  gap: 1rem;
}

.proofly-root .testimonial-card {
  background: var(--proofly-card-bg, #ffffff);
  border-radius: var(--proofly-radius, 8px);
  padding: 1.25rem;
}

Enter fullscreen mode Exit fullscreen mode

CSS custom properties (--proofly-card-bg, --proofly-radius, etc.) enable host-page theming without exposing a configuration API. Customers set variables on the container, and the widget inherits them natively.

To prevent duplicate style injections across multiple embed instances, an inject-once guard is implemented:

function injectStyles() {
  if (document.getElementById('proofly-embed-styles')) return;
  const style = document.createElement('style');
  style.id = 'proofly-embed-styles';
  style.textContent = EMBED_CSS; // minified at build time
  document.head.appendChild(style);
}

Enter fullscreen mode Exit fullscreen mode

The ~1,000 Lines Architecture

The embed is 1,140 lines of vanilla JS, deliberately avoiding bundlers or framework dependencies to ensure compatibility across React, Webflow, legacy WordPress, and plain HTML environments. The codebase is partitioned into:

• Card Renderer (~200 lines): Handles text, video thumbnails, audio, and star ratings
• Grid Layout Manager (~150 lines): Responsive columns, masonry-style height balancing, lazy loading
• CSS Injection (~180 lines): Full minified stylesheet
• Video Modal (~200 lines): Click-to-expand playback, keyboard close, scroll lock
• Utilities (~100 lines): Debounce, intersection observer, DOM helpers
• Initialization & Public API (~150 lines): initWall, attribute scanner, window.Proofly object

Error Boundary & Host Safety

Without iFrame sandboxing, runtime errors could theoretically interrupt host page execution. A global try/catch ensures silent failure:

try {
  initWall(container, slug);
} catch (e) {
  console.warn('[Proofly] Widget failed to initialize:', e);
  // silent failure — the container just stays empty
}

Enter fullscreen mode Exit fullscreen mode

A failed initialization leaves an empty div rather than breaking the host page, providing the safest possible fallback without a sandbox boundary.

Pitfall Guide

1. Ignoring Mobile Scroll Isolation in iFrames: Touch-scroll conflicts between parent and iframe cause stuck sections and degraded UX. Native DOM injection eliminates gesture fighting entirely.
2. Over-Engineering CSS Isolation with Shadow DOM: Shadow DOM blocks host font inheritance, breaking design consistency. Use scoped class prefixes (.proofly-root) + CSS custom properties instead.
3. Missing Style Injection Deduplication: Loading the embed script multiple times duplicates <style> tags, bloating the DOM and causing style conflicts. Always verify element existence before appending.
4. Neglecting Host Page Error Boundaries: Inline scripts can crash host environments if unhandled. Wrap initialization in try/catch to ensure graceful, silent failure.
5. Overcomplicating Embed Security: Public widgets don't require auth tokens. Use unguessable, opaque slugs with rate-limited public endpoints to balance security, simplicity, and performance.
6. Shipping Framework Dependencies in Embeds: Bundlers and frameworks conflict with diverse host environments (React, Webflow, legacy WP). Stick to vanilla JS with zero imports for maximum compatibility and minimal bundle size.

Deliverables

Direct DOM Embed Blueprint: Architecture diagram detailing the data- attribute scanner, initWall execution flow, CSS variable inheritance chain, and error boundary placement. Includes responsive grid layout logic and lazy-loading intersection observer patterns.

Embed Deployment Checklist:

• Verify ResizeObserver/postMessage alternatives are removed
• Confirm CSS scoping prefix (.proofly-root) covers all rules
• Validate CSS custom property fallbacks for host compatibility
• Test inject-once guard across multiple script loads
• Audit try/catch boundaries for silent failure behavior
• Run mobile touch-scroll validation on iOS/Android
• Verify slug endpoint rate-limiting and public access controls
• Performance budget check: <1,200 lines, zero external dependencies, <50KB gzipped