Content Security Policy (CSP) is a security header that whitelists allowed resources. When a merchant (or any host) sets a strict CSP, embedded widgets break unless they're explicitly allowed.

What inline-script restrictions break

Strict CSP without 'unsafe-inline' blocks:

1. Inline <script> blocks:

<script>doStuff();</script>   ← blocked

2. Inline event handlers in HTML:

<button onclick="doStuff()">Click</button>   ← blocked

3. javascript: URIs:

<a href="javascript:doStuff()">Click</a>   ← blocked

4. eval() and new Function():

eval('1 + 1')               ← blocked without 'unsafe-eval'
new Function('return 1')();

5. Inline styles (if style-src is similarly strict):

<div style="color: red">…</div>   ← may be blocked

6. Dynamic script injection (often used by analytics/tag managers):

const s = document.createElement('script');
s.innerHTML = '…';
document.head.appendChild(s);   ← blocked if script content is inline

How to legitimately do inline under strict CSP

Nonces: server generates a fresh random nonce per response and includes it in CSP + each allowed inline script tag:

Content-Security-Policy: script-src 'self' 'nonce-abc123'

<script nonce="abc123">init();</script>

Hashes: precompute SHA-256 of the inline script body, list in CSP:

Content-Security-Policy: script-src 'self' 'sha256-xyz...'

Strict-dynamic: trust scripts loaded by already-trusted scripts:

Content-Security-Policy: script-src 'self' 'strict-dynamic' 'nonce-abc123'

What frame-src restrictions break

frame-src (or child-src) controls which origins can be embedded as iframes.

Common breakage on strict frame-src:

• Payment widgets: Stripe Elements (iframes for card input), PayPal buttons, Apple Pay popups.
• Embedded videos: YouTube, Vimeo, Twitch.
• Embedded maps: Google Maps iframe embeds, OpenStreetMap.
• Social embeds: tweets, Instagram, Facebook posts.
• OAuth flows: third-party SSO popups (Google, GitHub, Microsoft).
• Chat widgets: Intercom, Drift, Zendesk.
• Analytics: some heatmap and session-replay tools (e.g., FullStory) iframe in.
• Captchas: reCAPTCHA, hCaptcha load in iframes.

What to do when integrating

If you're the embedded widget asking a merchant to embed you:

1. Document your CSP requirements: tell merchants exactly which directives to add.

• script-src https://js.yourservice.com
• frame-src https://yourservice.com
• connect-src https://api.yourservice.com
• img-src https://images.yourservice.com

1. Minimize inline code so merchants don't need 'unsafe-inline'.
2. Use nonces or external scripts instead of inline.
3. Provide nonced inline option if you must inline (publish-time hash, runtime nonce).
4. Test on merchant's staging CSP before going live.

If you're the merchant setting CSP:

1. Start in report-only mode to find what would break:

`` Content-Security-Policy-Report-Only: script-src 'self'; report-uri /csp-report ``

1. Enumerate trusted origins from third parties you use.
2. Use nonces for legitimate inline rather than 'unsafe-inline'.
3. Adopt strict-dynamic to simplify the policy.
4. Iterate: tighten the policy as you remove inline scripts and reduce third-party sprawl.

Debugging

When a widget breaks under CSP:

• Browser console shows: Refused to execute inline script because it violates the following Content Security Policy directive…
• Network panel: blocked resources show (blocked:csp) or similar.
• Use report-uri / report-to to collect violations from real users.

Other related CSP directives

• default-src — fallback for unspecified directives.
• script-src — JS.
• style-src — CSS.
• img-src — images.
• font-src — fonts.
• connect-src — XHR/fetch/WebSocket.
• frame-src — iframes.
• frame-ancestors — who can embed YOU as iframe.
• form-action — where forms can submit.
• base-uri — <base> tag values.

Bonus: X-Frame-Options + frame-ancestors

If the merchant doesn't want to be embedded:

Content-Security-Policy: frame-ancestors 'self'
X-Frame-Options: SAMEORIGIN

Prevents anyone from embedding their site in an iframe. Defense against clickjacking.

Mental model

CSP is a contract between the page and the browser. Strict CSP closes most XSS attack surfaces, but it also breaks anything that uses inline JS, eval, or unallowed external origins. As a widget vendor, design for CSP-friendliness; as a merchant, adopt CSP gradually with report-only first.