le via CSS vars | Medium (requires try/catch) | High (~1,140 lines) |
Key Findings & Sweet Spot: Direct DOM injection eliminates render flash and mobile scroll friction while enabling native typography inheritance. The sweet spot lies in accepting higher maintenance overhead in exchange for a polished, responsive default experience. For static, fixed-height widgets, iFrames remain viable. For dynamic, design-conscious embeds, direct DOM injection is architecturally superior.
Core Solution
The replacement architecture bypasses the iFrame sandbox entirely, injecting the widget directly into the host page's DOM via a lightweight script tag. The host page only requires a container with a data-proofly-wall attribute:
<div data-proofly-wall="your-embed-slug"></div>
<script src="https://proofly.shipquick.app/embed.js" async></script>
Enter fullscreen mode Exit fullscreen mode
On load, the embed script scans for containers and triggers initialization:
(function() {
const containers = document.querySelectorAll('[data-proofly-wall]');
containers.forEach(container => {
const slug = container.getAttribute('data-proofly-wall');
if (!slug) return;
initWall(container, slug);
});
})();
Enter fullscreen mode Exit fullscreen 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
- 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.
- 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.
- 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.
- Neglecting Host Page Error Boundaries: Inline scripts can crash host environments if unhandled. Wrap initialization in
try/catch to ensure graceful, silent failure.
- 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.
- 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:
