Skip to main content

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 saysWhose policySee
…because an ancestor violates… frame-ancestorsThe video'sThe video refuses your site
…set 'X-Frame-Options' to 'sameorigin'The video'sA watch link in the frame
…violates… frame-src (or child-src, default-src)Your site'sYour site refuses the frame
…violates… script-srcYour site'sYour site refuses the script tag
…violates… style-srcYour site'sThe 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:

  • www or not. example.com matches only example.com, not www.example.com, and *.example.com matches every subdomain but not example.com itself. To allow both, list both.
  • Plain http://. A domain matches only pages served over https://. A page on http://example.com is refused, whatever the list says. Serve it over HTTPS.
  • A port. localhost:3000 must be listed with its port. Local pages are usually plain http:// too, so they're refused anyway: for local development, try a video without embed_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 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 workNeeds
The fullscreen buttonfullscreen in allow, the allowfullscreen attribute, and your Permissions-Policy not refusing fullscreen
autoplay=1autoplay (and the video muted, as every browser wants)
Picture-in-picturepicture-in-picture
A DRM-protected videoencrypted-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.