Skip to content
Open Screeb

CSP, iframes and security requirements

Allow Screeb in your Content Security Policy, iframe sandbox and permissions policy, and know what degrades when a requirement is missing.

Screeb runs inside your page. If your site sends a Content Security Policy (CSP), is served inside an iframe, or restricts browser permissions, it must grant Screeb a small, explicit set of privileges. This page lists what Screeb needs, what happens when a requirement is missing, and what keeps working anyway. It applies to websites and web apps: the mobile SDKs are not affected.

Add these sources to your existing policy, next to your own domains. This policy runs every Screeb feature:

default-src 'self';
script-src 'self' https://*.screeb.app;
connect-src 'self' https://*.screeb.app https://s3.fr-par.scw.cloud;
style-src 'self' https://*.screeb.app;
img-src 'self' data: blob: https://*.screeb.app;
font-src 'self' https://*.screeb.app;
media-src 'self' blob: https://*.screeb.app;
frame-src 'self';

There is no 'unsafe-eval' and no 'unsafe-inline' anywhere, for scripts or styles.

No Screeb origin appears in frame-src: the frames Screeb creates carry no src. Add your booking provider’s origin there if you use booking questions, see Booking questions.

If you serve Screeb from your own domain through a proxy (see Custom collector URL), add your proxy hostname wherever the policy lists *.screeb.app. Keep https://*.screeb.app in img-src for emoji and https://s3.fr-par.scw.cloud in connect-src for uploads: the proxy does not carry them.

What breaks when a source is missing, from the most to the least visible:

Directive Sources If missing
script-src https://*.screeb.app Nothing loads. Your own page keeps working.
connect-src https://*.screeb.app No survey configuration is fetched, nothing is tracked and answers cannot be sent.
connect-src https://s3.fr-par.scw.cloud File, voice, video and screenshot answers fail to upload.
style-src https://*.screeb.app Recent browsers fall back to another way to apply the styles. On older browsers, surveys and messages may not render at all.
img-src https://*.screeb.app, data:, blob: Question images, logos, emoji and attachment previews are broken.
font-src https://*.screeb.app Surveys use the system font.
media-src https://*.screeb.app, blob: Audio and video in questions, recorded answers and notification sounds do not play.
frame-src 'self', plus your booking provider Booking questions show an empty box.

You can keep these as strict as you want:

Directive Why it is not needed
'unsafe-eval' No eval, no new Function, no WebAssembly. Browser capability detection is feature-based.
script-src 'unsafe-inline' Only the optional inline HTML snippet of the JavaScript tag needs it. The attribute install and the npm packages have no inline script.
style-src-attr 'unsafe-inline' Screeb writes no style attribute. What it styles at runtime goes through CSSOM or its own stylesheet, which CSP does not govern.
worker-src Screeb starts no Web Worker, Shared Worker or Service Worker.
object-src No object, embed or applet element.
base-uri, form-action Screeb renders no form and never rewrites base.
prefetch-src Browsers check the preload and modulepreload links of Screeb against script-src and style-src, which already list its origin. Required by older tag versions only.
font-src blob: Fonts load by URL since tag 0.48.1. Remove it if an older guide made you add it.
Origin Used for Directives
https://t.screeb.app The loader tag.js, the versioned bundles (core.js, widget.js, editor.js, inspector.js), their stylesheets, webfonts, translations, notification sounds, recolored emoji script-src, style-src, font-src, img-src, connect-src
https://rpc.screeb.app REST API: survey configuration, identity, event capture, survey answers, session replay batches, upload authorization connect-src
https://r.screeb.app SDK error and health reporting connect-src
https://static.screeb.app Images, audio and video attached to your questions, and reading back uploaded answer files img-src, media-src
https://emoji.screeb.app Emoji glyphs (SVG) img-src
https://s3.fr-par.scw.cloud Pre-signed upload of file, voice, video and screenshot answers connect-src
https://admin.screeb.app postMessage peer of the survey builder only, never fetched from your page none

Every Screeb origin is HTTPS only. Screeb refuses a non-HTTPS custom endpoint, so upgrade-insecure-requests or block-all-mixed-content change nothing.

The loader and the bundles are ES modules served from the tag origin. The bundles run inside frames Screeb creates on your page. These frames have no src, so they inherit your page’s CSP: your script-src governs them too.

If it is missing, nothing loads. Screeb reports the failure and every pending Screeb call rejects quickly instead of hanging. Your page is otherwise unaffected.

Under 'strict-dynamic', the scripts Screeb injects pass with no nonce, but the preload link it adds for the widget does not: the browser refuses and reports it to your report-uri while the widget still loads.

It covers the REST API (survey answers included), the report endpoint, and the fetches of Screeb’s own translations, sounds and stylesheet text.

File, voice, video and screenshot answers are uploaded with a pre-signed PUT to https://s3.fr-par.scw.cloud/<bucket>/.... The bucket name is the first path segment, not a subdomain, so a wildcard such as https://*.s3.fr-par.scw.cloud does not match: list https://s3.fr-par.scw.cloud.

A CSP source can carry a path, so you can allow the Screeb bucket only instead of the whole host: https://s3.fr-par.scw.cloud/static.screeb.app/. On the dedicated platforms, use https://s3.fr-par.scw.cloud/static.idfm.screeb.app/ or https://s3.fr-par.scw.cloud/static.sncf.screeb.app/. This is optional: the host alone stays valid.

If it is missing, no configuration is fetched and no answer is sent.

The widget, editor and inspector CSS ship as real stylesheets from the tag origin. Screeb sets no style attribute: what it styles at runtime (recolored emoji, widget geometry) goes through CSSOM, which CSP does not govern.

If it is missing, Screeb falls back in three steps rather than show an unstyled panel to your users:

  1. A stylesheet link, the normal path.
  2. Constructed stylesheets (adoptedStyleSheets). They are CSSOM, so they work even under style-src 'none'. They need Chrome 73, Firefox 101 or Safari 16.4 or later.
  3. An inline style element, for the opposite policy: one that allows 'unsafe-inline' but not the Screeb origin.

Every fallback is logged as an error, because only you can fix the policy. If all three fail (an old browser under a policy that refuses both the origin and inline styles), no survey, message or feedback button renders at all, while tracking and targeting keep working. This is the CSP mistake with the least visible symptoms.

Question images and logos (static.screeb.app), emoji (emoji.screeb.app), recolored emoji (t.screeb.app), data: for the transparent placeholder a masked emoji is painted over, and blob: for the thumbnail of a file or screenshot the user has just attached.

If it is missing, images are broken. Text, navigation and answers are unaffected.

Survey webfonts (Inter, Rubik, Montserrat, your brand font) are declared through the Font Loading API against t.screeb.app/assets/fonts.

If it is missing, the widget uses the system font stack. Everything else works.

Audio and video attached to your questions (static.screeb.app), plus blob: for two local cases: playing back the voice or video answer the user just recorded, and the notification sound.

If it is missing, media does not play. The survey stays answerable.

Only booking questions need it: they embed your scheduling tool in an iframe. Add that provider’s origin yourself. Screeb only loads the HTTPS URL you set on the question and refuses anything else before it reaches the frame.

No Screeb origin belongs here. The frames Screeb creates for its own bundles carry no src: they inherit your page’s origin and policy, so frame-src 'self' covers them.

If it is missing, the booking question shows an empty box and cannot be completed. Other questions are unaffected.

Add the origin of your provider to frame-src, next to 'self':

Provider Origin to allow
Calendly https://calendly.com
Google Calendar appointments https://calendar.google.com
HubSpot Meetings https://meetings.hubspot.com (or your regional meetings- subdomain)
Cal.com https://cal.com
SavvyCal https://savvycal.com
Microsoft Bookings https://outlook.office.com

For example: frame-src 'self' https://calendly.com;

@screeb/sdk-browser adds no inline script: your bundler outputs a regular file that script-src 'self' covers, and load() appends the tag with a src. No nonce, hash or 'unsafe-inline' is needed.

If your page is embedded in another document (a portal, a marketplace shell, a partner site, a native WebView), the embedder’s sandbox attribute and permissions policy apply to Screeb too.

Token Needed for Without it
allow-scripts Everything Screeb cannot run at all.
allow-same-origin Everything The frame gets an opaque origin: localStorage throws and anonymous mode refuses to start (see Storage). Screeb also cannot read the host page, so URL, scroll and element targeting stop.
allow-popups and allow-popups-to-escape-sandbox Buttons and links that open a new tab window.open returns null and the button does nothing.
allow-top-navigation-by-user-activation Buttons that navigate the current tab Screeb first tries window.top.location, then an anchor with target="_top", which this token permits. Without either, the navigation is blocked.

allow-forms, allow-modals and allow-downloads are not required: Screeb renders no form, never calls alert, confirm or prompt, and triggers no download.

The frames Screeb creates on your page are same-origin, so they inherit your page’s permissions: you do not need to annotate them. But if your page is framed, its embedder must delegate the permissions:

<iframe
src="https://app.example.com"
allow="microphone; camera; display-capture; fullscreen; clipboard-write"
></iframe>
Permission Screeb feature Without it
microphone Voice answers on open-text questions Recording fails. Typing still works.
camera Video answers on open-text questions Recording fails. The other answer modes still work.
display-capture Screenshot capture on open-text questions Capture fails. File upload still works.
fullscreen Fullscreen button on video questions The video plays inline only.
clipboard-write “Copy to clipboard” actions The action does nothing.
autoplay (optional) Video that starts by itself in a question The user presses play.

When Screeb runs in one origin and the content you target lives in another, the browser blocks all access between them and several targeting rules stop resolving. See Cross-origin pages and iframes.

Cross-Origin-Opener-Policy and the survey builder

Section titled “Cross-Origin-Opener-Policy and the survey builder”

The visual survey builder opens your site in a popup and talks to it through window.opener and window.name. A page that sends Cross-Origin-Opener-Policy: same-origin severs that link: the builder sees the popup as closed, window.opener is null and window.name is reset. The specification mandates it, and Screeb cannot work around it.

Workarounds, best first:

  1. Use the builder’s “Open with URL parameters” action. It starts the editor through the page URL and syncs over the API instead of postMessage, so COOP does not affect it. The builder then shows your changes when it refetches rather than live.
  2. Relax the header to Cross-Origin-Opener-Policy: restrict-properties or same-origin-allow-popups on the pages where you edit surveys.

Cross-Origin-Embedder-Policy: require-corp is not compatible with Screeb: its assets are not served with Cross-Origin-Resource-Policy: cross-origin.

frame-ancestors is not involved: the builder uses a popup, never an iframe.

Screeb sets no cookie, on your page or anywhere else. Identity and display history live in localStorage and sessionStorage on your own origin, so no third-party cookie or Storage Access permission is involved, and browser anti-tracking modes do not affect Screeb.

Situation Behavior
Storage available Normal operation.
Storage blocked or full, user identified Screeb falls back to memory. The session works, but display history and capping reset at each page load, so the user may see the same survey again.
Storage blocked, anonymous user init fails with an explicit error. An anonymous user needs a persistent identifier: without one, each page load would be a new user.
  • Every endpoint is HTTPS. Screeb rejects a non-HTTPS custom endpoint when it starts.
  • API requests are sent in CORS mode and without credentials: no cookie and no Authorization header from your session are attached.
  • Requests carry the browser’s Origin header, which the allowed domains check below reads. Referrer-Policy does not affect it.

Workspaces with the Custom domains feature can restrict which origins may call the API, see Serve Screeb through your own domain. A request whose Origin is not on the list is rejected with 403 (origin not in workspace allowed domains). localhost, 127.0.0.1 and ::1 are always accepted, and requests without an Origin header (mobile SDKs, server to server) are not checked.

If you also override the endpoints, Screeb checks them against the same list when it starts and logs a console warning on a mismatch.

Screeb talks between your page and its own frames with postMessage. It accepts incoming messages from three origins only: your own page, the tag origin (https://t.screeb.app or your proxy) and https://admin.screeb.app. Everything else is dropped before it is parsed.

Each of these origins is also bound to the part of Screeb it may speak for, so a message from one trusted origin cannot impersonate another part to reach handlers it should not. The loader always addresses its frames with its own origin, and never trusts an origin given inside a message.

Ad blockers often block *.screeb.app whatever your CSP, and the symptom looks like a missing script-src: test in a browser without extensions. On the Enterprise plan, you can serve Screeb from your own domain, see Custom collector URL and Reverse proxy templates. Update your CSP with the proxy origin when you do.

The last column says whether the rest of Screeb keeps working when the requirement is not met.

Feature Requirement If not met Rest of Screeb
Screeb loads at all script-src https://*.screeb.app Nothing loads, Screeb calls reject with a reported error Stops, your page is unaffected
Inline HTML snippet (JavaScript tag) script-src 'unsafe-inline', a nonce or a hash The snippet never runs Stops, use the data-channel-id install
Survey configuration, targeting, event tracking, identity connect-src https://*.screeb.app No configuration is fetched, nothing is captured Stops
Answering a survey or message connect-src https://*.screeb.app Answers fail to submit after three retries The survey is unusable
Survey and message rendering style-src https://*.screeb.app Constructed stylesheets, then an inline style element Works on recent browsers. On older browsers under style-src 'none', nothing renders while tracking keeps working
Brand webfont font-src https://*.screeb.app The system font stack is used Works
Question images, logos, emoji img-src https://*.screeb.app data: Broken images Works
Colored and keycap emoji style-src https://*.screeb.app Fall back with the rest of the stylesheet Works
Audio and video in questions media-src https://*.screeb.app Media does not play Works
Fullscreen video allow="fullscreen" when your page is framed Inline playback only Works
Notification sound media-src blob: Silent Works
Voice answers allow="microphone" when your page is framed Recording fails Works, typed answers too
Video answers allow="camera" when your page is framed Recording fails Works
Screenshot answers allow="display-capture" when your page is framed Capture fails Works, file upload too
Playing back a recorded answer media-src blob: The preview does not play Works, the answer still uploads
Attachment thumbnails img-src blob: No thumbnail Works, the upload too
File, voice, video and screenshot uploads connect-src https://s3.fr-par.scw.cloud The upload fails Works, the survey completes
Booking questions frame-src with your booking provider Empty embed That question cannot be completed
“Copy to clipboard” actions allow="clipboard-write" when your page is framed Nothing is copied Works
Buttons opening a new tab sandbox with allow-popups allow-popups-to-escape-sandbox The button does nothing Works
Buttons navigating the current tab sandbox with allow-top-navigation-by-user-activation Navigation is blocked Works
Session replay connect-src https://*.screeb.app and a readable same-origin host page Recording does not start Works, surveys are unaffected
Anonymous users Writable localStorage, sandbox with allow-same-origin init fails with an explicit error Stops, identify your users instead
Identified users None: Screeb falls back to memory Display history and capping reset at each page load Works
URL, scroll, element and exit intent targeting Same-origin access to the host page The rule never matches Time, event and manual triggers still work
Survey builder on your site No Cross-Origin-Opener-Policy: same-origin Popup detection and live sync are severed Use “Open with URL parameters”
SDK error reporting connect-src https://r.screeb.app Screeb support loses diagnostics Works, invisible to users

Open Screeb Inspector on your site. In its Overview tab, the “Installation & Health” checklist tests the API, the report endpoint, the widget stylesheet, fonts and media, and names the directive to fix for each failure. Images, uploads and booking frames are not tested there: check the browser console, where Screeb logs the CSP violations it causes.

The debug command only tells you whether the API is blocked:

import * as Screeb from "@screeb/sdk-browser";
Screeb.debug();

To catch CSP violations yourself:

document.addEventListener("securitypolicyviolation", (event) => {
console.log(event.violatedDirective, event.blockedURI);
});

If something still does not add up, Troubleshooting covers the causes that are not CSP.