Context
Creatives are part of the Formbricks Enterprise Edition, on self-hosted
instances whose license includes Creatives. They are not available on Formbricks Cloud.
docs/adr/ (0003–0014); this page connects them.
A creative has three parts:
- What it shows: type-specific
contentandstyling(JSON, validated per type). - When it shows:
showOn(page view or actions, throughCreativeTrigger),showConditions,displayPercentage,startAtandendAt. - Its Destination: a survey (
surveyId) or a link (linkUrl). A banner without a button has neither.
How The Pieces Connect
Why Creatives Render In js-core, Inside A Shadow DOM
ADR 0005. Context. A feedback button renders on every matching page view, on the order of a billion a year for one large customer. js-core is loaded on every page; the survey bundle (about 240 KB gzipped) loads only when a survey shows. Decision.- A tiny DOM renderer,
@formbricks/creatives, is bundled into js-core.packages/js-core/src/bundle-size.test.tsholds it to 6,250 B gzipped and js-core to 21,000 B. resolvedecides from the cached environment state and the page context what to show;renderdraws it. Neither touches the network.- Each creative sits in an open Shadow DOM whose
:hoststarts fromall: initial, with px units. Host-page CSS can’t reach in; with Page font on,font-familyinherits through it. - Styles arrive as server-resolved values per appearance (light, dark) and device (desktop, phone), so the renderer holds no theme logic. They go into a
<style>element in the shadow root carrying the nonce fromsetNonce(), so strict CSPs work; insets usestyle.setProperty, which a CSP without'unsafe-inline'allows. - Only the creative’s own compiled Custom CSS enters the shadow root; workspace CSS never does (ADR 0014).
- The survey bundle loads only on a click. js-core requests it from a versioned URL (
/js/surveys.umd.cjs?v=<content hash>), so a new SDK never runs an old cached renderer that would drop attribution. - The editor preview mounts the same
render.
#fbjs (host CSS and survey-oriented workspace CSS leak both ways); a separate React preview (it drifts from what visitors see).
The SDK loop. reconcileCreatives (packages/js-core/src/lib/creatives/creatives.ts) runs on every page view (single-page-app route changes included), on every tracked action, on a state refresh, when the nonce, appearance or language changes, after a banner dismiss and at the next schedule boundary. At SDK start it draws the creatives in the cached state before the refresh, so an In page banner appears with the page; a failed refresh takes them off again. layout.ts stacks banners per edge and passes the space Overlay banners take to feedback buttons as CSS custom properties.
The click path (ADR 0006) doesn’t go through triggerSurvey: openSurveyForCreative renders the Destination survey right away with no delay or auto-close, bypassing its triggers, conditions, segment, recontact, cooldown and percentage. The display it creates still updates the user’s displays and lastDisplayAt. Pressing while the same survey is open does nothing; a different open survey is closed first.
Why Impressions And Clicks Are Counters, Not Events
ADR 0007. Context. An always-on button produces on the order of a billion impressions a year for one customer. Decision.- The SDK batches a page view’s events into requests of at most 100 events, sent 2 s after the first event, on
pagehide, or as soon as 100 are queued; a page view with more events sends more than one. It goes astext/plainwithkeepalive, so there is no CORS preflight. An Impression is once per creative per page view (host + path); a Click is a press that opened the Destination. - The events endpoint always answers 204. It drops bots, bodies over 16 KB, ids that aren’t countable creatives of the workspace (cached for 60 s) and requests over the IP rate limit (
rateLimitConfigs.api.clientCreativeEvents, 600 a minute). - One Lua script increments Redis hashes per creative and UTC day: by device type, and by page, capped at 1,000 pages a creative a day with the rest under
(other). Keys live about 48 h. - The
creative-stats.flushjob runs every 60 s and upserts yesterday’s and today’s totals intoCreativeDailyStatandCreativeDailyPageStatwithGREATEST(stored, counted). A run takes at most 50 claims of 100 creatives per day; a larger backlog waits for the next run, so counts can then lag more than a minute.
- Only aggregates can be reported, and a new breakdown can’t be backfilled. That is why device type is on the daily totals from day one.
- The flush is idempotent, so overlapping replicas and a repeated run are harmless.
- Without a BullMQ worker the counters never reach Postgres and expire from Redis after about 48 h. If Redis is unavailable or refuses writes, the endpoint still answers 204 and the counts are lost.
Why A Creative’s Status Is Derived
ADR 0004. Context. A creative stores its author’s intent:status (draft · inProgress · paused · completed, the survey values), archivedAt and publishedAt. A survey’s status is written from 8+ paths: the editor, the list, the summary, API v1 and v3, MCP, the close-date job, the response-limit auto-complete and archiving.
Decision. What everyone sees is computed by one function, getCreativeDisplayState (modules/ee/creatives/lib/display-status.ts), in this order:
- Archived if
archivedAtis set; Draft and Closed (completed) as the author set them. - Closed (
scheduleEnded) onceendAthas passed. - Paused as the author set it.
- Paused (
destinationMissing,actionMissing) when delivery could never show it. The same rule,getCreativeDeliveryGap, keeps it out of the SDK payload. - Scheduled before
startAt. - Paused (
surveyNotActive) while the Destination survey isn’tinProgressor is archived. Link Destinations and banners without a button only follow their own status and schedule. - Otherwise Active.
display-status-sql.ts is its SQL twin for list filters, and display-status-cases.ts holds both to one case table. The API exposes the writable status and a read-only displayStatus with displayStatusReason.
Why. Writing a survey’s state onto its creatives would miss some of those paths, and the two would disagree. Deriving it also removes the need for a minute-level cron for schedules.
Consequences.
- Resuming a survey brings its creatives back by themselves. The resume dialog’s Keep these creatives paused is the only place a survey change writes to creatives.
- A new reason a creative can’t show only adds a row to the derivation and its SQL twin.
- A save that would turn a creative that isn’t Active into Active stores
pausedinstead, so editing never takes a creative live.
Other Decisions
License gate.
getCreativesAccess (modules/ee/creatives/lib/access.ts) returns full when the license includes creatives, windDown on a self-hosted instance without it whose workspace still has creatives, and none otherwise, always on Cloud. Only full delivers creatives and counts events. windDown keeps the list, summary and API reads, and allows pause, close and delete (CREATIVES_WIND_DOWN_OPERATIONS in access-rules.ts); everything else answers 403 creatives_not_entitled. Losing the license writes nothing to creatives, so they come back on their own when the license does; a pause, close or delete made during wind-down is written as usual and stays. See License Check.
How To Add A Creative Type
No new columns (ADR 0003). The one schema change is a new value in the PostgreSQLCreativeType enum behind Creative.type, which needs an additive migration before the type can be stored. A type needs:
- A payload variant: add the value to
CreativeTypeinpackages/database/schema/creatives.prismaand create its migration withpnpm fb-migrate-dev. Add itscontentandstylingschemas to the API v3 spec underdocs/api-v3-reference/src/, then runpnpm api:v3:sync. Add the variant toTCreativePayloadinpackages/creatives/src/types.ts. - A renderer module in
packages/creatives/src/render.ts, and its rules inresolve.tsif it shows differently. Mind the bundle budget inbundle-size.test.ts. - Style resolution in
modules/ee/creatives/lib/style.ts: which workspace Look & Feel tokens it starts from and which overrides it allows. - The editor: its Content and Styling cards (
components/editor/content-tab.tsx,styling-tab.tsx), its publish checks (lib/publish-check.ts) and its placement in the overlap check (lib/overlap.ts) and the SDK layout (packages/js-core/src/lib/creatives/layout.ts).
Known Limitations
- Freshness. Creative writes don’t clear the cached environment state: it expires after 60 s in Redis and at the CDN, and the SDK keeps its copy for up to an hour. Creating, editing or pausing a creative reaches returning visitors within about an hour.
- Schedules run on SDK timers to the minute, for visitors whose state already holds the creative. The server’s
serverTimecorrects device clocks that are behind by more than 2 minutes or ahead by more than 5; smaller skews are left alone. - Layout shift. An In page banner shifts the page down when it appears. On a multi-page site that can be every page load: the snippet loads js-core asynchronously, so the page can paint before the banner, however early the cached draw runs. A
[data-formbricks-slot="banner-top"]element with a min-height reserves its place. - Stale SDK after a deploy. js-core is served from an unversioned URL, cached for an hour by browsers and up to 30 days by a CDN. Until visitors get the new file, they run the old SDK, which ignores
creatives. Purge the CDN as in the Custom CSS rollout. - Web only. The mobile SDKs ignore
creatives, and old SDKs never show the trigger-less surveys that only creatives open: those go out withtriggers: [].