# 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.

## Content Security Policy

### The policy

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

```text
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](#booking-questions).

If you serve Screeb from your own domain through a proxy (see [Custom collector URL](https://developers.screeb.app/sdk-js/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 each directive allows

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.                                                                                         |

### Directives Screeb does not need

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.                                                                                           |

### Where Screeb loads from

| 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.

### script-src

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.

### connect-src

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.

### style-src

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.

### img-src

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.

### font-src

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.

### media-src

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.

### frame-src

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.

## Booking questions

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;`

## Install without inline script

`@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.

> [!WARNING]
> **Subresource Integrity is not supported**
> `tag.js` is a mutable pointer updated at every release, and the loader fetches versioned bundles at runtime without `integrity` attributes. An `integrity` attribute on the Screeb script breaks it at the next release. Use `script-src` allowlisting and `require-trusted-types-for` for supply-chain control instead.

## Running inside an iframe

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.

### Sandbox tokens

| 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](#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.

### Permissions policy

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:

```html
<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.                              |

### Cross-origin frames

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](https://developers.screeb.app/sdk-browser/cross-origin-limitations).

### 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.

## Other requirements

### Storage

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.              |

### Network and transport

- 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.

### Allowed domains

Workspaces with the Custom domains feature can restrict which origins may call the API, see [Serve Screeb through your own domain](https://help.screeb.app/account/custom-domains/). 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.

### Frame messaging

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

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](https://developers.screeb.app/sdk-js/custom-collector-url) and [Reverse proxy templates](https://developers.screeb.app/sdk-js/reverse-proxy-templates). Update your CSP with the proxy origin when you do.

## Feature requirements

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                                                                                          |

## Check your setup

Open [Screeb Inspector](https://help.screeb.app/troubleshooting/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:

```ts
import * as Screeb from "@screeb/sdk-browser";

Screeb.debug();
```

To catch CSP violations yourself:

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

If something still does not add up, [Troubleshooting](https://developers.screeb.app/sdk-browser/troubleshooting) covers the causes that are not CSP.
