427e7578-d7bf-49c8-aee9-2dd999e25316/specs/010-embeddable-widget/README.md

status, created, tags, priority, created_at, depends_on, updated_at

status	created	tags	priority	created_at	depends_on	updated_at
planned	2026-03-16	embed widget	low	2026-03-16T07:51:51.430Z	009-public-sharing	2026-03-16T07:52:06.356Z

Embeddable Poll Widget

Status: 🗓️ Planned · Priority: Low · Created: 2026-03-16 · Tags: embed, widget

Overview

Allow polls to be embedded on external websites and potentially in messaging apps. This extends the public sharing with an inline experience.

Design

Embed Options

1. iframe embed (simplest, broadest support)

   • <iframe src="https://evocracy.app/embed/[pollId]" width="400" height="300"></iframe>
   • Renders a compact read-only results view
   • Self-contained, works anywhere iframes are supported
   • Uses postMessage to communicate height for responsive sizing

2. oEmbed protocol (for platforms that support it—Notion, WordPress, Medium, etc.)

   • Endpoint: https://evocracy.app/oembed?url=https://evocracy.app/poll/[pollId]
   • Returns iframe-based rich embed

3. Web Component (deferred to v2)

   • <script src="https://evocracy.app/widget.js"></script>
   • <evocracy-poll poll-id="[pollId]"></evocracy-poll>
   • Shadow DOM for style isolation
   • Deferred: iframe covers 90% of use cases

Messenger Compatibility

• iMessage / WhatsApp / Telegram: Open Graph link previews (handled by spec 009)
• Slack / Discord: oEmbed + Open Graph unfurling
• Actual inline voting in messengers is not feasible without platform-specific bots

Embed Route

• /embed/[id] — minimal chrome, compact layout, no navigation
• Auto-resizes via postMessage to parent frame

Plan

• Create /embed/[id] route with compact poll results view
• Implement iframe auto-resize via postMessage
• Add "Get embed code" UI to poll management page
• Implement oEmbed endpoint (/oembed)
• Build web component wrapper (widget.js) (deferred to v2)

Test

• iframe embed renders correctly on a test HTML page
• Auto-resize adjusts to content height
• oEmbed endpoint returns valid JSON
• Web component renders in isolation (Shadow DOM)

Notes

• DECIDED: Web component deferred to v2—iframe alone covers 90% of use cases
• Messenger "embeds" are really just link previews, not interactive widgets