Troubleshooting
An embedded player that stays blank, shows the browser's "refused to connect" page, or never appears at all is almost always a Content Security Policy (CSP) saying no. Two policies meet in an embed, and either can refuse it:
- The video's: Crumbcast's embed page tells the browser which sites may frame it,
from the video's
embed_domains. - Your site's: your page's own CSP says what it may load: frames, scripts, styles.
The browser names the one that refused in its console. Open the developer tools on the page with the embed (Console tab) and look for a message starting "Refused to…": it quotes the directive, and the directive says whose policy it is.
| The console says | Whose policy | See |
|---|---|---|
…because an ancestor violates… frame-ancestors | The video's | The video refuses your site |
| …set 'X-Frame-Options' to 'sameorigin' | The video's | A watch link in the frame |
…violates… frame-src (or child-src, default-src) | Your site's | Your site refuses the frame |
…violates… script-src | Your site's | Your site refuses the script tag |
…violates… style-src | Your site's | The frame is there but has no size |
The embed page's own policy is in its headers:
curl -sI https://your-crumbcast/embed/<video id> | grep -i content-security-policy
content-security-policy: frame-ancestors 'self' example.com *.example.com
frame-ancestors * means any site may frame it: the video has no embed_domains.
The video refuses your site
The video's embed_domains don't match the page it's on. Check what it has:
curl https://your-crumbcast/api/v1/videos/$VIDEO_ID/ \
-H "Authorization: Bearer $CRUMBCAST_TOKEN" | jq .embed_domains
What usually doesn't match:
wwwor not.example.commatches onlyexample.com, notwww.example.com, and*.example.commatches every subdomain but notexample.comitself. To allow both, list both.- Plain
http://. A domain matches only pages served overhttps://. A page onhttp://example.comis refused, whatever the list says. Serve it over HTTPS. - A port.
localhost:3000must be listed with its port. Local pages are usually plainhttp://too, so they're refused anyway: for local development, try a video withoutembed_domains, or a local HTTPS server. - A frame around your page. Every frame above the player must be allowed, not only
the page with the
<iframe>tag. A CMS's preview or editor, a site builder, or a code playground (CodePen, JSFiddle) shows your page inside a frame of its own, from its own domain. The embed works on the published page but not in the preview; or list the preview's domain too.
Change the list with Update Video; the next load of the embed uses it:
curl -X PATCH https://your-crumbcast/api/v1/videos/$VIDEO_ID/ \
-H "Authorization: Bearer $CRUMBCAST_TOKEN" \
-H "Content-Type: application/json" \
-d '{"embed_domains": ["example.com", "*.example.com"]}'
Domains are host names: https://example.com/blog is kept as example.com. A video
takes up to 20. Live streams' embeds may be framed by any site.
A password video's question frames on the same sites as the video: a refused password
page is the same embed_domains problem.
A watch link in the frame
A watch page (/watch/<id>) is a page of Crumbcast's own, and no other site may frame
it. Frames take the embed page, /embed/<id>, with the same ID: the snippets in the
video's Share menu in the dashboard, and in Play videos,
use it.
Your site refuses the frame
Your page's CSP doesn't allow frames from Crumbcast. Add its address to frame-src:
Content-Security-Policy: frame-src 'self' https://your-crumbcast
Without a frame-src, the browser uses child-src, then default-src: add it to
whichever your policy has. The policy may be in a response header or a
<meta http-equiv="Content-Security-Policy"> tag; in a CMS, often a security plugin or
the host's settings.
Only the frame needs allowing. The player loads its video, captions and thumbnails
inside the frame, under Crumbcast's policy, so your media-src, img-src and
connect-src don't need Crumbcast or any storage in them.
Your site refuses the script tag
The script tag needs two things from your CSP: the script itself, and the frame it puts on the page.
Content-Security-Policy: script-src 'self' https://your-crumbcast; frame-src 'self' https://your-crumbcast
With a nonce-based script-src, give the tag your page's nonce
(<script async nonce="…" src="https://your-crumbcast/embed/script.js" …>). If your
policy can't allow another script at all, use the <iframe> instead: it needs only
frame-src.
The frame is there but has no size
The <iframe> snippet sizes the player with style="…" attributes. A style-src
without 'unsafe-inline' drops them, leaving a small frame, or none visible. Move the
same rules into your stylesheet:
<div class="crumbcast-player">
<iframe src="https://your-crumbcast/embed/<video id>" title="Launch day"
allow="autoplay; fullscreen; picture-in-picture; encrypted-media" allowfullscreen></iframe>
</div>
.crumbcast-player { position: relative; width: 100%; aspect-ratio: 16 / 9; }
.crumbcast-player iframe { position: absolute; inset: 0; width: 100%; height: 100%; border: 0; }
The script tag sets its sizes from its script, which style-src doesn't limit.
It plays, but not everything works
The <iframe>'s allow attribute lets the player use what it needs, and your site's own
Permissions-Policy header can still take it away: what the header refuses, allow
can't give back.
| Doesn't work | Needs |
|---|---|
| The fullscreen button | fullscreen in allow, the allowfullscreen attribute, and your Permissions-Policy not refusing fullscreen |
autoplay=1 | autoplay (and the video muted, as every browser wants) |
| Picture-in-picture | picture-in-picture |
| A DRM-protected video | encrypted-media |
A sandbox attribute on the <iframe>, which some CMSs add, stops the player too: it
needs at least sandbox="allow-scripts allow-same-origin" (without allow-same-origin
it can't fetch the video), or no sandbox at all.
Controlling the player from your page with postMessage
isn't something CSP limits. If messages go unanswered, check the target origin you send
to and the message.origin you check are both https://your-crumbcast.