@pollyou/embed-core
v1.2.0
Published
The <pollyou-survey> web component, the collector API client and the embed.js loader of the script snippet.
Readme
@pollyou/embed-core
The <pollyou-survey> web component (Lit, Shadow DOM), the client of the public collector
API (/api/collect) and the embed.js loader of the script snippet. Framework packages
(React, Vue, Angular, …) wrap this element.
<div data-pollyou-survey="PUBLIC_ID"></div>
<script src="https://embed.pollyou.org/v1/embed.js" async></script>User documentation (German): docs/embed/script.md.
Commands
pnpm --filter @pollyou/embed-core test # Vitest (jsdom): state machine, API client, queue, renderers, axe-core
pnpm --filter @pollyou/embed-core build # dist/esm (ESM, Lit external) + dist/cdn (IIFEs, versioned, SRI; scripts/build-cdn.mjs)
pnpm --filter @pollyou/embed-core size # size-limit: embed.js < 29.3 KB (29.21 KB), renderer, logic + overlay chunks, iframe-resizer.js < 2 KB gzip (runs in CI)
pnpm --filter @pollyou/embed-core serve:cdn # serves dist/cdn on :5174 (direct link page /s/… in dev)
pnpm --filter @pollyou/embed-core storybook # Storybook dev server on :6006
pnpm --filter @pollyou/embed-core storybook:build # static Storybook in dist/storybook
pnpm exec playwright test e2e/embed-snippet.spec.ts # snippet on demo/index.html (needs the build)
pnpm exec playwright test e2e/embed-iframe-resizer.spec.ts # iframe-resizer.js with a fake iframe page
pnpm exec playwright test e2e/embed-live-results.spec.ts # live results in two windows (real stack + worker)
pnpm exec playwright test e2e/embed-iframe.spec.ts e2e/embed-config.spec.ts e2e/embed-device-dedup.spec.ts # real stack, Chromium/Firefox/WebKit
pnpm exec playwright test e2e/overlay-triggers.spec.ts # overlay modes: every trigger + frequency rules, real stack, all browsersdemo/index.html is a static page with two surveys, a container added later and an event
log. Serve the package directory with any static server after building.
Architecture
| Module | Responsibility |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| src/state-machine.ts | Pure transition(state, event): loading → question ⇄ (errors) → submitting → results \| thank_you, plus already_answered, closed, blocked, error. |
| src/controller.ts | Side effects of one instance: load, session on the first answer, PATCH per page, complete, event tracking, client-side "already answered" marker. |
| src/api-client.ts | fetch-based collector client (credentials: 'omit'), CollectorError/NetworkError, events via navigator.sendBeacon (text/plain, fallback fetch + keepalive). |
| src/retry-queue.ts | FIFO queue for session/PATCH/complete calls: retries offline/5xx/429 with exponential backoff (1 s … 60 s, 10 attempts), mirrored to sessionStorage, flushes on online. |
| src/captcha.ts | ALTCHA proof of work for surveys with settings.captcha (WebCrypto digest in batches of 500 with a yield in between: off the main thread, no Worker, CSP-safe). |
| src/device.ts | Device token of the dedup strategy device (localStorage key pollyou:device, one per browser and host origin, 32 random base64url characters). |
| src/validation.ts | Lightweight answer validator mirroring @pollyou/survey-schema (see "Validation" below). |
| src/survey-element.ts | The Lit element: rendering, theming, focus management, live region; overlay hooks (mode resolution, loading the overlay chunk, impression once shown). |
| src/overlay-chunk.ts | Overlay chunk (embed-overlay.js): popup/slider/fullpage markup and CSS, Escape and focus trap, triggers, frequency rules (see "Overlay modes" below). |
| src/renderers/* | Question types and results bars. Inline: single_choice, multiple_choice, dropdown, rating, nps, yes_no, likert, text_short, text_long, number, email. Lazy chunks (lazy.ts): matrix, ranking, date, image_choice. hidden is never rendered. |
| src/logic-chunk.ts | Branching logic chunk (embed-logic.js): the engine of @pollyou/survey-schema/logic, the router onto the shown pages and the disqualified texts (see "Branching logic" below). |
| src/i18n.ts | UI texts (de, en; registerLocale for more), locale resolution, RTL detection. |
| src/live-results.ts | Mercure subscription (EventSource on realtime.hubUrl?topic=…) used by the controller while results are shown (live-results). |
| src/iframe-resizer.ts | Host script of the iframe embed (iframe-resizer.js): resizes iframe[data-pollyou-iframe], re-dispatches pollyou:* events; origin-checked. |
| src/loader.ts, embed.ts | Mounts [data-pollyou-survey] containers, also later ones (MutationObserver); IIFE entry with window.PollYou. |
Poll vs. survey
- Poll (
type: "poll"): all questions on one view, button "Vote"; after voting the results (if the server returns them) appear immediately. - Survey: one view per page with progress bar, back/next; every "next" saves the page with
PATCH /responses/{id}(through the retry queue), "submit" sends all answers withcomplete.
Resume after a reload (surveys, not polls): once the session exists, the controller keeps
pollyou:resume:<publicId> in localStorage ({responseId, sessionToken, expiresAt,
versionNumber, subject} - no answers). On the next load of a live survey it fetches
GET /responses/{id} and continues that response: same session (no second start), the
answers of the partial saves, on the page after lastPageIndex (state question with
resumed: true: a notice and a live region announcement, no focus move; cleared by the next
page change). The entry is dropped when it expired (the response is abandoned after
COLLECT_ABANDON_AFTER_HOURS, default 24 h), belongs to another version or another identity
(sub of identity-token), the response is completed/unknown (401/404) or the survey is
already answered (completion marker); on network/5xx errors it is kept for the next load.
pollyou:ready reports resumed.
The response session (POST …/sessions) is created on the first answer, not on load, so
impressions without interaction create no responses. 409 already_answered switches to the
"already answered" view (with results if the body contains them), 403 not_open to the
closed/scheduled view, 422 maps answers.<key> violations back to the questions (403 not_open on a PATCH or complete also switches to closed, 401 invalid_session starts a new session once, 409 already_completed counts as completed). Offline,
the completion is queued and the respondent sees a "will be sent when you are back online"
thank-you page that turns into results once the queue went through.
Dedup, captcha, honeypot and blocked states
- Dedup strategies (
settings.dedupStrategy):device(and the legacycookie) sends the device token asdeviceToken(created on the first session of such a survey only);identitysendsidentity-token. The client-side completion markerpollyou:done:<publicId>lives insessionStorageforsession, inlocalStoragefordevice/ip_hashand is not written fornone/identity/login. The server decides (409already_answered); the marker only shows "already answered" right away. - Captcha (
settings.captcha): the session request fetchesGET /api/collect/captchaand solves it while the respondent answers (src/captcha.ts); solutions are single-use, so each session solves a fresh one. Without WebCrypto (insecure context) the session is sent without solution and ends incaptcha_required. - Honeypot: every form renders a visually hidden
<input name="website">(aria-hiddenwrapper,tabindex="-1",autocomplete="off"); a filled value is sent aswebsitewith the session and the completion (the server accepts but flags the response). - Blocked (state
blockedwithreason): 403origin_not_allowed,identity_required,identity_invalid,captcha_required(with "Try again") andlogin_requiredfrom the session, PATCH or completion. Requirements that cannot be met are shown right after loading (login,identity/requireSignedIdentitywithout token). A disallowed origin gets the 403 without CORS headers, so the load fails as a network error: the client then sends an opaqueno-corsrequest to the same URL; if that succeeds, the collector is reachable and refused the origin (offline it fails as well and the normal load error appears). - Embed overrides:
survey.embed.overrides(locale,theme,showResults;null= unset) win over the attributes once the survey is loaded.
Question types
| Type | Rendering |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| single_choice, multiple_choice | native radios/checkboxes, optional images, "other" text field |
| dropdown | native <select> (placeholder entry, config.placeholder or "Please choose …"), "other" text field |
| rating, nps, yes_no | numbered scale / stars / two options |
| likert | one radio per point (5 or 7) with config.labels or the translated disagree…agree labels |
| text_short, text_long, email | <input> / <textarea> / <input type="email" autocomplete="email">, maxlength from the config, labelled by the question title |
| number | <input type="number"> with min/max/step (from decimals), the unit next to it; empty = not answered |
| matrix (chunk) | one role="radiogroup" per row (labelled by the row), one radio per column; wide containers show a column header (container query), narrow ones the column name next to each radio |
| ranking (chunk) | ordered list with "move up/down" buttons, the new position is announced in a polite live region and the focus stays on the moved item; "Keep this order" accepts the shown order (randomized unless randomizeOptions: false) |
| date (chunk) | native <input type="date"> with min/max |
| image_choice (chunk) | image cards as radios or checkboxes (config.multiple); the caption names the input, the image is decorative |
| hidden | never rendered (left out of the pages; pages with hidden fields only are skipped). The value comes from the host: the hidden-<key> attribute (data-hidden-<key> of the snippet, PollYou.open({ hidden })) or the meta entry with the question key; trimmed, max. 500 characters, sent with the completion. The direct link page passes ?<key>= URL parameters as data-hidden-<key>. |
Branching logic
Rules live in the version definition (pages[].logic, questions and pages referenced by id;
semantics and the shared test cases: @pollyou/survey-schema, schemas/logic-conformance.json).
- Loading: only surveys with at least one rule load
embed-logic.js(CDN, SRI like the renderer chunks; a dynamicimport()in the package entry) while the survey loads, before the first page shows. A failed load ends in the load error view; "Try again" loads it again. - Routing (
route()instate-machine.ts, the chunk'srouter): the engine walks the survey with the current answers and the meta (themetaattribute,hidden-*values and the unverifiedmetaclaim of the identity token - like the collector, the token wins on equal keys; the collector verifies it and decides authoritatively). Its result is mapped onto the shown pages:order= shown pages on the path that have a visible question (pages with hidden fields only, or whose questions are all hidden, are passed through),visible= keys of the visible questions. Without rules every page and question is shown, as before. - Navigation: a page renders only its visible questions and re-evaluates on every answer
(questions appear/disappear live on the same page). "Next" goes to the next page of the path,
"Back" to the previous one; the primary button reads "Submit" when no shown page follows on
the path (also when
end_survey/disqualifyends it). Validation covers the visible questions only, so required questions hidden or skipped by logic are not required. - Progress: "Page n of m" counts the shown pages of the path predicted with the current answers (recomputed on every change, so skipping shortens it).
- Saving:
PATCHsends the visible answers of the left page with the staticpageIndex(index into the shown pages, unchanged meaning); the completion sends only answers of visible questions on the path - the collector rejects others (logic_skipped) and drops saved ones off the path. - Resume after a reload: the restored answers are walked again; the survey continues on the
path page after the page saved last (
lastPageIndex), or on the last page of the path if that one ends it. - Disqualified: the completion (
disqualified: truein the response, or the client's prediction in preview/offline) shows a fixed translated text instead of the thank-you message, without results and redirect;pollyou:completehasdisqualified: trueandresults: null. - Size: the engine (≈1.5 KB gzip with texts) is a lazy chunk; what stays in embed.js is the routing glue (route/step helpers, filtered validation and submission, the chunk loading, the disqualified view, identity meta) - about 0.6 KB. embed.js had 0.09 KB of its budget left, so the budget was raised from 28.5 to 29.1 KB (embed.js 28.41 → 29.0 KB): every survey must be able to branch without a second round trip on pages that do not use logic, and moving the glue into the chunk would need a router interface of about the same size.
Overlay modes (popup, slider, fullpage)
The mode comes from the mode attribute, else from the embed configuration
(survey.embed.mode, so <div data-pollyou-survey data-embed-id> is enough on the host page).
inline and iframe render inline. An element with an overlay mode loads the overlay chunk
(embed-overlay.js, ~3.3 KB gzip, SRI like the renderer chunks; a dynamic import in the
package entry) and renders nothing until it is open. Inline embeds never load it.
- Presentation (chunk):
popup= modal dialog (role="dialog",aria-modal, backdrop, bottom sheet below 480 px),fullpage= modal dialog over the whole viewport (content max. 720 px wide),slider= non-modalrole="complementary"region in a bottom corner (position), which never takes the focus. All have a labelled close button, close with Escape (popup/fullpage also on a backdrop click), return the focus, trap Tab in the modal modes, animate only withoutprefers-reduced-motion, usez-index: 2147483000and live in the shadow root (host CSS does not leak in). The chunk's<style>(and the theme's custom CSS) is inserted before Lit's content: a changed root template clears everything after it. The survey header is a<div part="header">, not<header>(a banner landmark inside the slider region or a host landmark violates axe's landmark rules). - Triggers (chunk, armed once the survey is loaded and in state
question- answered, closed and blocked surveys never open on their own):manual(default: onlyPollYou.open()),delay(delaySecondsafter loading),scroll(scrollY / (scrollHeight - innerHeight)≥scrollPercent; pages that do not scroll count as 100 %),exit_intent(mouseoutondocumentwithout related target atclientY ≤ 0; only with(pointer: fine)- on touch devices back button and visibility changes are too late or must not be hijacked, so the trigger never fires there),page_views(from the n-th page view:pollyou:views:<publicId>in localStorage, counted once per page load). - Settings precedence: element attribute (
trigger,delay,scroll,page-views,frequency,cooldown-days,position) →data-*of the snippet container (read by the chunk, so embed.js needs no list of them) →survey.embed.overlay→ defaults (same as the server'sEmbedOverlay::DEFAULTS). Invalid values are ignored. - Frequency:
pollyou:overlay:<publicId>={closedAt?, participatedAt?}(epoch ms), written onpollyou:closeandpollyou:complete. A participation ends automatic opening for good; after closingonce= never,cooldown= aftercooldownDays,always= next page. Storage per dedup strategy:session→ sessionStorage;identity→ localStorage with:<sub>of the identity token appended;none/device/cookie/ip_hash/login→ localStorage. Without usable Web Storage a first-party cookie (pollyou_overlay_<publicId>,SameSite=Lax, session cookie forsession, else 400 days) replaces it. The completion marker of the dedup strategy (pollyou:done:*, statealready_answered) blocks automatic opening as well. - Analytics: with an overlay mode the element tracks
impressionandviewonly when the overlay is open (deferImpressioncontroller option,controller.impression()), so triggers that never fire do not lower the conversion rate. Closing without completing sendsdismiss(new collector event type).pollyou:shown{surveyId, mode, trigger}is dispatched (by the chunk) when the overlay appears;pollyou:closewhen it closes. - Fallback: if the chunk cannot be loaded, an opened overlay renders inline at the element's position; a closed one stays hidden.
- Size: the core hooks cost ~0.3 KB gzip; moving the former popup CSS, the focus trap and the overlay markup into the chunk paid for them, so embed.js stays within the 29.1 KB budget (29.01 → 29.07 KB) without raising it.
- Budget 29.1 → 29.2 KB: the overlay modes and multilingual surveys were built in parallel and each fit into 29.1 KB on its own (29.07 KB); together embed.js is 29.14 KB (+42 bytes gzip for passing all locale preferences and the survey language to the server). Splitting that glue off would need a chunk round trip before the first render, so the budget was raised by 0.1 KB.
- Budget 29.2 → 29.3 KB: main had grown to the limit meanwhile; refetching the live results after a reconnect (the Mercure hub keeps no history, see "Live results") adds about 40 bytes gzip (29.21 KB), so the budget was raised by 0.1 KB.
Lazy renderers and the size budget
embed.js had 30 bytes left of its 25 KB budget, and the eleven new types cost about 7.6 KB gzip in total. The decision:
- Inline (in embed.js):
dropdown,likert,text_short,text_long,number,emailand thehiddenhandling - one native control each, used in many surveys (a lazy load would cost a request for the most common types), and their validation lives invalidation.tsanyway. - Lazy (own chunk each, loaded on first render of such a question):
matrix(1.17 KB),ranking(1.55 KB),image_choice(1.09 KB),date(0.41 KB) - the larger renderers with their own CSS and texts (ranking), used less often. - Budget raised to 28.5 KB (embed.js: 24.93 → 28.41 KB gzip). The +3.5 KB are the inline renderers, 15 translated texts in two languages (new error codes, Likert labels, loading states), the validator rules of all 16 types (they must stay in the core: a page is validated before submit even if a chunk failed), the chunk loader with the SRI hashes of the chunks (~0.3 KB) and the hidden-field handling. Moving the inline types into chunks as well would save about 1.5 KB but add a request to nearly every survey with a text field.
How it works (src/renderers/lazy.ts):
- A chunk exports a factory
(runtime) => renderer; it imports only types, so it bundles neither Lit nor helpers. The core passesruntime={html, svg, nothing, describedBy, errorMessage, ids, withConfigDefaults, isCalendarDate, registerLocale}- the chunk renders with the core's Lit instance. Chunk texts are registered withregisterLocale(en, de) and their CSS is a<style>in the rendered template. - CDN:
src/chunks/<type>.tsis built as its own IIFE (vite.cdn.config.ts --mode chunk-<type>, list inscripts/chunks.json) and callswindow.PollYouRenderers.register(type, factory), which embed.js defines. embed.js loadsembed-<type>.jswith a<script>resolved relative to its own URL (document.currentScript, captured at startup):/v1/embed.jsloads/v1/embed-matrix.js,/v1.2.3/embed.jsthe immutable/v1.2.3/embed-matrix.js, so core and chunk versions always match.scripts/build-cdn.mjsbuilds the chunks first, writes their sha384 hashes and injects them into embed.js (__POLLYOU_CHUNK_SRI__): every chunk is loaded withintegrityandcrossorigin="anonymous"(the CDN sendsAccess-Control-Allow-Origin: *). A host page's CSP must allow the CDN directory, not onlyembed.js. - ESM / package entry (dashboard preview, framework wrappers, Storybook):
src/renderers/modules.tsuses dynamicimport(); the app's bundler splits the chunks. - While a chunk loads the question shows a
role="status"placeholder; a failed load shows an alert with "Try again" (a new attempt). Elements re-render when a chunk registered.
Validation
@pollyou/survey-schema validates with ajv. Bundled, its answer validator alone is
37 KB gzip (measured with Vite/rolldown, minified) — more than the whole 25 KB budget — and
ajv compiles schemas with new Function, which breaks host pages with a strict CSP. embed-core
therefore ships src/validation.ts, which mirrors the answer rules (JSON schema first, then the
semantic checks, same error codes). tests/validation-parity.spec.ts runs all shared conformance
cases (schemas/conformance.json) and extra edge cases against both validators and compares
the codes, and checks that the config defaults are identical. Types come from
@pollyou/survey-schema (type-only imports, no runtime cost). The collector validates again
authoritatively.
Attributes
| Attribute | Description |
| ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| survey-id | Public id of the survey (required). |
| embed-id | Embed configuration (sent as ?embed= and in the session); its overrides win over locale, theme, show-results. |
| mode | inline (default), popup, slider or fullpage (overlays, visible while open is set); without the attribute the embed configuration's mode applies. |
| trigger, delay, scroll, page-views, frequency, cooldown-days, position | Overlay trigger and frequency (also as data-* on the snippet container); they win over the embed configuration, see "Overlay modes". |
| locale | UI language and requested content locale; default: nearest lang, then the browser languages, then English. All candidates go to the server as ?locale=a,b,c, which picks the language of a multilingual survey (fallback: its default language); the UI and text direction then follow the survey language shown (survey.locale), which is reported as surveyLocale with the session. |
| theme | Color scheme: auto (default, follows prefers-color-scheme), light, dark. The theme tokens come from the server. |
| show-results | false hides results even if the survey shows them. |
| live-results | Present (not false): shown results update live via Mercure when the survey offers realtime (public results). |
| identity-token | Signed identity of a logged-in user (forwarded as identityToken). |
| meta | JSON object with string/number/boolean values (max. 20 keys; keys [a-z0-9_]{1,32}, strings ≤ 200 characters - others are dropped, the collector would refuse them). Also fills hidden questions by key. |
| hidden-* | Hidden fields, e.g. hidden-user-id="42" → meta.user_id = "42" (hyphens become _) and the answer of a hidden question with key user_id. |
| api-base | Origin of the collector API; default PollYou.configure({ apiBase }), then the loader's script origin/data-api-base. |
| channel | Channel reported to the collector (script by default; framework wrappers set their own). |
| open | Overlay is open (boolean). |
The loader passes the same names as data-* attributes of the container
(data-locale, data-hidden-user-id, …). Property previewState renders a fixed state
without network access (Storybook, previews).
Property previewData (a PublicSurvey-shaped object) renders that survey instead of loading
survey-id, e.g. the unpublished draft in the dashboard builder: fully interactive, but nothing
goes over the network: sessions and the completion are simulated in memory, results are
previewData.results plus the preview answer (simulateResults), events are not tracked,
nothing is stored and redirects are not followed. The simulation lives in src/preview.ts and is
installed by the package entry (enablePreview()), so embed.js does not ship it.
Events
All events are CustomEvents that bubble and cross the shadow boundary (composed).
| Event | detail |
| ------------------ | ------------------------------------------------- |
| pollyou:ready | { surveyId, type, status, resumed } |
| pollyou:start | { surveyId } (first answer, session requested) |
| pollyou:answer | { surveyId, questionKey, answer } |
| pollyou:complete | { surveyId, responseId, results, disqualified } |
| pollyou:shown | { surveyId, mode, trigger } (overlay appeared) |
| pollyou:close | { surveyId, mode } |
| pollyou:error | { surveyId, phase: 'load' \| 'submit', status } |
Imperative API (window.PollYou, also exported as PollYou)
PollYou.configure({ apiBase: 'https://app.pollyou.org', locale: 'de' })
const el = PollYou.open({ surveyId: 'AbC123xyz0', hidden: { ref: 'newsletter' } }) // popup
PollYou.open('AbC123xyz0') // opens a mounted overlay of the survey in place, else a new popup
PollYou.open({ surveyId: 'AbC123xyz0', mode: 'slider' }) // new slider (or 'fullpage')
PollYou.open({ surveyId: 'AbC123xyz0', target: '#slot' }) // inline into an element
PollYou.close() // all opened instances and open overlays; or PollYou.close('AbC123xyz0') / PollYou.close(el)
const off = PollYou.on('complete', (detail) => console.log(detail.results))
PollYou.registerLocale('fr', { submit: 'Envoyer', next: 'Suivant' })
PollYou.mount(document.querySelector('#content')) // mount containers below a node manuallyCalls before embed.js has loaded can be queued:
(window.PollYou = window.PollYou || { q: [] }).q.push(['open', { surveyId: '…' }]).
Styling
Theme tokens become CSS custom properties (toCssVariables from @pollyou/themes) on the
root element (part container, class .pollyou-survey); dark colors apply with
theme="dark" or prefers-color-scheme: dark. Custom CSS of the theme (sanitized and scoped
below .pollyou-survey by the server) is injected into the shadow root.
::part() names: container, dialog, backdrop, close-button, header, title,
description, progress, page-title, form, question, question-title,
question-description, options, option, option-selected, option-input, option-label,
other-input, input (text, number, e-mail, date fields), select (dropdown), matrix,
matrix-row, matrix-cell, ranking, rank-item, scale, scale-item, scale-item-selected, scale-labels, stars, star,
error, error-summary, actions, button, button-primary, button-secondary, status,
spinner, celebration (check icon and confetti of the thank-you view), message, notice,
results-section, results, result-question,
result-summary, result, result-label, result-percent, result-bar, result-fill,
result-total.
pollyou-survey::part(button-primary) {
text-transform: uppercase;
}Accessibility
Native radio buttons/checkboxes in <fieldset>/<legend> (arrow keys, space, Enter submits),
native select/text/number/date inputs labelled by the question title, matrix rows as labelled
radio groups, ranking with buttons and announced positions,
44 px targets, visible focus ring (focusRing token), required marker with screen reader
text, errors linked via aria-describedby, focus moves to the first invalid question, to the
new page or to the results heading after user actions (never on initial load), a polite live
region announces state changes, results are aria-live. Popup and fullpage are modal dialogs
with focus trap, Escape and focus return; the slider is a non-modal complementary region.
tests/a11y.spec.ts runs axe-core on every state (light, dark, RTL, popup), on every overlay
mode in light, dark and RTL and on every question type (unanswered, answered, with errors, RTL); the Playwright spec repeats it in Chromium including color contrast.
CDN layout
pnpm build writes:
dist/cdn/v1/embed.js channel of the major version (updated with every 1.x release)
dist/cdn/v1.0.0/embed.js immutable release
dist/cdn/v1/iframe-resizer.js host script of the iframe embed (same channel/release layout)
dist/cdn/v1/embed-<type>.js renderer chunks (matrix, ranking, date, image-choice), loaded by embed.js
dist/cdn/v1/embed-logic.js branching logic chunk, loaded by embed.js for surveys with rules
dist/cdn/v1/embed-overlay.js overlay chunk (popup/slider/fullpage, triggers), loaded for overlay modes
dist/cdn/integrity.json { version, channel, files: { "/v1/embed.js": "sha384-…", … } }
dist/cdn/_headers cache headers (Netlify/Cloudflare Pages syntax)Cache headers: the channel /v1/ is served with
Cache-Control: public, max-age=300, stale-while-revalidate=86400, releases /v1.2.3/ with
public, max-age=31536000, immutable; both with Access-Control-Allow-Origin: *
(needed for SRI with crossorigin="anonymous"). SRI hashes only make sense for fixed
releases, because the channel file changes. Uploading to the CDN belongs to the deployment.
Live results
With live-results the controller subscribes to survey.realtime ({hubUrl, topic},
delivered by the collector while the results are public) as soon as a state with results
is shown (results, already_answered, closed), and feeds every ResultsPayload into the
state machine (results event, honours show-results). The EventSource is anonymous (no
credentials) and closed when the element disconnects or restarts. The hub keeps no history
(Mercure transport local): when the browser reopens a dropped connection, the controller
refetches the results once (GET …/results), as updates sent meanwhile are not replayed.
Without EventSource or realtime nothing happens. Cost: about 0.3 KB gzip.
iframe-resizer.js
Separate IIFE (src/iframe-resizer-entry.ts, built with vite build --config
vite.cdn.config.ts --mode iframe-resizer, about 0.6 KB gzip). It accepts messages
{source: "pollyou", type: "resize" | "event", publicId, height?, event?, detail?} only from
the window of an iframe[data-pollyou-iframe] and only from the origin of that iframe's
src; resize sets style.height (capped at 20000 px), event dispatches
pollyou:<event> (bubbling CustomEvent, detail + publicId) on the iframe element; the
iframe page sends the full name (event: "pollyou:complete"), a bare complete works too.
User documentation: docs/embed/iframe.md.
